المتغير Animated.ValueXY في React Native

هو قيمة ثنائية الأبعاد 2D لتوجيه التأثيرات الحركية ثنائية الأبعاد، مثل الإيماءات الشاملة pan gestures، وهو واجهة API متطابقة تقريبًا مع المتغيّر Animated.Value العادي، ولكنها مضاعَفة. يحتوي هذا المتغير على متغيري Animated.Value نمطيتين ضمنيًا.

مثال توضيحي

إليك المثال التالي (تجربة حية):

import React, { useRef } from "react";
import { Animated, PanResponder, StyleSheet, View } from "react-native";

const DraggableView = () => {
  const pan = useRef(new Animated.ValueXY()).current;

  const panResponder = PanResponder.create({
    onStartShouldSetPanResponder: () => true,
    onPanResponderMove: Animated.event([
      null,
      {
        dx: pan.x, // x,y are Animated.Value
        dy: pan.y,
      },
    ]),
    onPanResponderRelease: () => {
      Animated.spring(
        pan, // مُضاعَف نلقائيًا
        { toValue: { x: 0, y: 0 } } // العودة إلى الصفر
      ).start();
    },
  });

  return (
    <View style={styles.container}>
      <Animated.View
        {...panResponder.panHandlers}
        style={[pan.getLayout(), styles.box]}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
  },
  box: {
    backgroundColor: "#61dafb",
    width: 80,
    height: 80,
    borderRadius: 4,
  },
});

export default DraggableView;

التوابع

setValue()‎

setValue(value);

يضبط هذا التابع القيمة مباشرة، فهذا سيؤدي إلى إيقاف أي تأثيرات حركية تعمل على هذه القيمة وتحديث جميع الخصائص المرتبطة بها.

المعاملات Parameters:

الاسم	النوع	مطلوب	الوصف
value	عدد number	نعم	قيمة Value

setOffset()‎

setOffset(offset);

يضبط هذا التابع الإزاحة المُطبَّقة على أية قيمة مضبوطة، سواء عبر التابع setValue أو عبر التحريك أو عبر Animated.event، وهو مفيد لتعويض أشياء كبدء إيماءة شاملة pan gesture.

المعاملات:

الاسم	النوع	مطلوب	الوصف
offset	عدد number	نعم	قيمة إزاحة

flattenOffset()‎

flattenOffset();

يدمج هذا التابع قيمة الإزاحة مع القيمة الأساسية ويعيد ضبط الإزاحة إلى الصفر، أي لم يتغير خرج القيمة النهائي.

extractOffset()‎

extractOffset();

يضبط هذا التابع قيمة الإزاحة على القيمة الأساسية، ويعيد ضبط القيمة الأساسية إلى الصفر، أي لم يتغير خرج القيمة النهائي.

addListener()‎

addListener(callback);

يضيف هذا التابع مستمعًا غير متزامن إلى القيمة لتتمكّن من مراقبة تحديثات التأثيرات الحركية، وهذا مفيد لأنه لا توجد طريقة لقراءة القيمة بصورة متزامنة لأنها قد تكون موجَّهة بطريقة أصيلة. يعيد هذا التابع سلسلة نية تعمل كمعرّف للمستمع.

المعاملات:

الاسم	النوع	مطلوب	الوصف
callback	دالة function	نعم	دالة رد نداء callback التي ستتلقى كائنًا له مفتاح value مضبوط على القيمة الجديدة.

removeListener()‎

removeListener(id);

يلغي هذا التابع تسجيل مستمع. يجب أن يتطابق المعامل id مع المعرّف الذي أعاده التابع addListener()‎ مسبقًا.

المعاملات:

الاسم	النوع	مطلوب	الوصف
id	سلسلة نصية string	نعم	معرّف Id المستمع المحذوف.

removeAllListeners()‎

removeAllListeners();

يحذف هذا التابع جميع المستمعين المسجّلين.

stopAnimation()‎

stopAnimation([callback]);

يوقف هذا التابع أي تأثيرات حركية أو تتبّع قيد التشغيل. تُستدعى الدالة callback مع القيمة النهائية بعد إيقاف التأثير الحركي، وهذا أمر مفيد لتحديث الحالة لمطابقة مكان التحريك مع التخطيط.

المعاملات:

الاسم	النوع	مطلوب	الوصف
callback	دالة function	لا	دالة ستتلقى القيمة النهائية.

resetAnimation()‎

resetAnimation([callback]);

يوقف هذا التابع أي تأثير حركي ويعيد ضبط القيمة إلى أصلها.

المعاملات:

الاسم	النوع	مطلوب	الوصف
callback	دالة function	لا	دالة ستتلقى القيمة الأصلية.

getLayout()‎

getLayout();

يحوّل هذا التابع {x, y} إلى {left, top} لاستخدامه في نمط style كما يلي:

style={this.state.anim.getLayout()}

getTranslateTransform()‎

getTranslateTransform();

يحوّل هذا التابع {x, y} إلى تحوّل ترجمة قابل للاستخدام كما يلي:

style={{
  transform: this.state.anim.getTranslateTransform()
}}

مصادر

• صفحة Animated.ValueXY في توثيق React Native الرسمي.