عرض مصدر ReactNative/animatedvaluexy

<noinclude>{{DISPLAYTITLE:المتغير Animated.ValueXY في React Native}}</noinclude>
هو قيمة ثنائية الأبعاد 2D لتوجيه التأثيرات الحركية ثنائية الأبعاد، مثل الإيماءات الشاملة pan gestures، وهو واجهة API متطابقة تقريبًا مع المتغيّر <code>[[ReactNative/animatedvalue|Animated.Value]]</code> العادي، ولكنها مضاعَفة. يحتوي هذا المتغير على متغيري <code>Animated.Value</code> نمطيتين ضمنيًا.

== مثال توضيحي ==
إليك المثال التالي ([https://snack.expo.dev/@hsoubwiki/animated.valuexy تجربة حية]):<syntaxhighlight lang="javascript">
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;
</syntaxhighlight>

== التوابع ==

===<code>setValue()‎</code>===
<syntaxhighlight lang="javascript">
setValue(value);
</syntaxhighlight>يضبط هذا التابع القيمة مباشرة، فهذا سيؤدي إلى إيقاف أي تأثيرات حركية تعمل على هذه القيمة وتحديث جميع الخصائص المرتبطة بها.

'''المعاملات Parameters''':
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|value
|عدد number
|نعم
|قيمة Value
|}

===<code>setOffset()‎</code>===
<syntaxhighlight lang="javascript">
setOffset(offset);
</syntaxhighlight>يضبط هذا التابع الإزاحة المُطبَّقة على أية قيمة مضبوطة، سواء عبر التابع <code>setValue</code> أو عبر التحريك أو عبر <code>Animated.event</code>، وهو مفيد لتعويض أشياء كبدء إيماءة شاملة pan gesture.

'''المعاملات''':
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|offset
|عدد number
|نعم
|قيمة إزاحة
|}

===<code>flattenOffset()‎</code>===
<syntaxhighlight lang="javascript">
flattenOffset();
</syntaxhighlight>يدمج هذا التابع قيمة الإزاحة مع القيمة الأساسية ويعيد ضبط الإزاحة إلى الصفر، أي لم يتغير خرج القيمة النهائي.

===<code>extractOffset()‎</code>===
<syntaxhighlight lang="javascript">
extractOffset();
</syntaxhighlight>يضبط هذا التابع قيمة الإزاحة على القيمة الأساسية، ويعيد ضبط القيمة الأساسية إلى الصفر، أي لم يتغير خرج القيمة النهائي.

===<code>addListener()‎</code>===
<syntaxhighlight lang="javascript">
addListener(callback);
</syntaxhighlight>يضيف هذا التابع مستمعًا غير متزامن إلى القيمة لتتمكّن من مراقبة تحديثات التأثيرات الحركية، وهذا مفيد لأنه لا توجد طريقة لقراءة القيمة بصورة متزامنة لأنها قد تكون موجَّهة بطريقة أصيلة. يعيد هذا التابع سلسلة نية تعمل كمعرّف للمستمع.

'''المعاملات''':
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|callback
|دالة function
|نعم
|دالة رد نداء callback التي ستتلقى كائنًا له مفتاح <code>value</code> مضبوط على القيمة الجديدة.
|}

===<code>removeListener()‎</code>===
<syntaxhighlight lang="javascript">
removeListener(id);
</syntaxhighlight>يلغي هذا التابع تسجيل مستمع. يجب أن يتطابق المعامل <code>id</code> مع المعرّف الذي أعاده التابع <code>addListener()‎</code> مسبقًا.

'''المعاملات''':
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|id
|سلسلة نصية string
|نعم
|معرّف Id المستمع المحذوف.
|}

===<code>removeAllListeners()‎</code>===
<syntaxhighlight lang="javascript">
removeAllListeners();
</syntaxhighlight>يحذف هذا التابع جميع المستمعين المسجّلين.

===<code>stopAnimation()‎</code>===
<syntaxhighlight lang="javascript">
stopAnimation([callback]);
</syntaxhighlight>يوقف هذا التابع أي تأثيرات حركية أو تتبّع قيد التشغيل. تُستدعى الدالة <code>callback</code> مع القيمة النهائية بعد إيقاف التأثير الحركي، وهذا أمر مفيد لتحديث الحالة لمطابقة مكان التحريك مع التخطيط.

'''المعاملات''':
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|callback
|دالة function
|لا
|دالة ستتلقى القيمة النهائية.
|}

===<code>resetAnimation()‎</code>===
<syntaxhighlight lang="javascript">
resetAnimation([callback]);
</syntaxhighlight>يوقف هذا التابع أي تأثير حركي ويعيد ضبط القيمة إلى أصلها.

'''المعاملات''':
{| class="wikitable"
!الاسم
!النوع
!مطلوب
!الوصف
|-
|callback
|دالة function
|لا
|دالة ستتلقى القيمة الأصلية.
|}

===<code>getLayout()‎</code>===
<syntaxhighlight lang="javascript">
getLayout();
</syntaxhighlight>يحوّل هذا التابع <code>{x, y}</code> إلى <code>{left, top}</code> لاستخدامه في نمط style كما يلي:<syntaxhighlight lang="javascript">
style={this.state.anim.getLayout()}
</syntaxhighlight>

===<code>getTranslateTransform()‎</code>===
<syntaxhighlight lang="javascript">
getTranslateTransform();
</syntaxhighlight>يحوّل هذا التابع <code>{x, y}</code> إلى تحوّل ترجمة قابل للاستخدام كما يلي:<syntaxhighlight lang="javascript">
style={{
  transform: this.state.anim.getTranslateTransform()
}}
</syntaxhighlight>

== مصادر ==

* [https://reactnative.dev/docs/animatedvaluexy صفحة Animated.ValueXY في توثيق React Native الرسمي.]
[[تصنيف:ReactNative]]
[[تصنيف:React Native API]]