ReactNative/animated

صُمِّمَت واجهة ‎Animated‎ البرمجيّة لتسهيل التعبير عن مجموعة متنوعة من أنماط التحريك والتفاعل بطريقة فائقة الأداء. تركّز واجهة ‎Animated‎ على العلاقات التعريفية بين المدخلات (inputs) والمخرجات (outputs)، مع وجود تحويلات قابلة للضّبط بينهما، إضافة إلى تابعَي ‎start‎ و‎stop‎ بسيطين للتحكم في تنفيذ التّحريك على أساس الوقت.

لإنشاء تأثير حركي عليك أولًا البدء بإنشاء متغيّر Animated.Value وربطه بواحدة أو أكثر من أنماط المكون المتحركة ودفع التحديثات عبر التأثيرات الحركية باستخدام الدالة ()Animated.timing.

مثال: استخدام مكون دالِّي (Function component)

عند استخدام المكونات الدالِّية لإنشاء التأثيرات الحركية يجب عدم تعديل قيمة animmated.value مباشرةً، وإنما يجب استخدام الخطاف useRef لإرجاع كائن مرجعي قابل للتعديل، وتُهيّئ الخاصية current للكائن ref على أنّها المعاملات المبدئية، وتستمر طوال دورة حياة المكون.

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

const App = () => {
  // fadeAnim will be used as the value for opacity. Initial Value: 0
  const fadeAnim = useRef(new Animated.Value(0)).current;

  const fadeIn = () => {
    // Will change fadeAnim value to 1 in 5 seconds
    Animated.timing(fadeAnim, {
      toValue: 1,
      duration: 5000
    }).start();
  };

  const fadeOut = () => {
    // Will change fadeAnim value to 0 in 5 seconds
    Animated.timing(fadeAnim, {
      toValue: 0,
      duration: 5000
    }).start();
  };

  return (
    <View style={styles.container}>
      <Animated.View
        style={[
          styles.fadingContainer,
          {
            opacity: fadeAnim // Bind opacity to animated value
          }
        ]}
      >
        <Text style={styles.fadingText}>Fading View!</Text>
      </Animated.View>
      <View style={styles.buttonRow}>
        <Button title="Fade In" onPress={fadeIn} />
        <Button title="Fade Out" onPress={fadeOut} />
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: "center",
    justifyContent: "center"
  },
  fadingContainer: {
    paddingVertical: 8,
    paddingHorizontal: 16,
    backgroundColor: "powderblue"
  },
  fadingText: {
    fontSize: 28,
    textAlign: "center",
    margin: 10
  },
  buttonRow: {
    flexDirection: "row",
    marginVertical: 16
  }
});

export default App;

مثال: استخدام مكون صنفي (Class component) استخدام المكونات الصنفية لإنشاء التأثيرات الحركية يجب عدم تعديل قيمة animmated.value مباشرةً، وإنما يجب تخزينها في صورة متغيّر في الحالة الخاصة بالمكون state.

import React, { Component } from "react";
import { Animated, Text, View, StyleSheet, Button } from "react-native";

class App extends Component {
  // fadeAnim will be used as the value for opacity. Initial Value: 0
  state = {
    fadeAnim: new Animated.Value(0)
  };

  fadeIn = () => {
    // Will change fadeAnim value to 1 in 5 seconds
    Animated.timing(this.state.fadeAnim, {
      toValue: 1,
      duration: 5000
    }).start();
  };

  fadeOut = () => {
    // Will change fadeAnim value to 0 in 5 seconds
    Animated.timing(this.state.fadeAnim, {
      toValue: 0,
      duration: 5000
    }).start();
  };

  render() {
    return (
      <View style={styles.container}>
        <Animated.View
          style={[
            styles.fadingContainer,
            {
              opacity: this.state.fadeAnim // Bind opacity to animated value
            }
          ]}
        >
          <Text style={styles.fadingText}>Fading View!</Text>
        </Animated.View>
        <View style={styles.buttonRow}>
          <Button title="Fade In" onPress={this.fadeIn} />
          <Button title="Fade Out" onPress={this.fadeOut} />
        </View>
      </View>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: "center",
    justifyContent: "center"
  },
  fadingContainer: {
    paddingVertical: 8,
    paddingHorizontal: 16,
    backgroundColor: "powderblue"
  },
  fadingText: {
    fontSize: 28,
    textAlign: "center",
    margin: 10
  },
  buttonRow: {
    flexDirection: "row",
    marginVertical: 16
  }
});

export default App;

إرجع إلى دليل التأثيرات الحركية لمزيد من الأمثلة.

نظرة عامة

هناك نوعان من البيانات يمكن استخدامهم مع المكون Animated هما:

• Animated.Value(): للقيم المُفردة.
• Animated.ValueXY(): للمُتجهات.

يمكن أن ترتبط Animated.Value بخصائص النمط أو الخواص الأخرى، كما يمكن أن تؤدّي قيمة Animated.Value واحدة العديد من الخصائص.

إنشاء وضبط التأثيرات الحركية

يوفر المكون Animated ثلاثة أنواع من التأثيرات الحركية يُمثّل كلٌّ منها منحنى حركة معيّن يتحكم في معدَّل تغير قيمة التأثير الحركي من القيمة الأولية إلى القيمة النهائية.

• ()Animated.decay: يبدأ بسرعة أولية و يتباطأ تدريجيًا حتى يتوقف.
• Animated.spring: تُمثل نموذجًا أساسيًا لفيزياء النوابض.
• Animated.timing: يُغيِّر قيمة التأثير الحركي مع مرور الزمن باستخدام دوال التسارع (easing functions).

في أغلب الأحيان تُستعمل الدالة ()timing، والتي تستخدم منحنى easeInOut إفتراضيًّا. هذا المنحنى يمثل التسارع التدريجي لجسمٍ ما إلى أقصى سرعة ثم التباطؤ تدريجيًأ حتى التوقف.

التعامل مع التأثيرات الحركية

تبدأ التأثيرات الحركية عن طريق استدعاء الدالة ()start على التأثير الحركي. تأخذ الدالة start رد نداء (callback) يُستدعى عند انتهاء التأثير الحركي، حيثُ تكون قيمة المعامل finished فيه هي true إذا اكتمل التأثير الحركي بنجاح وحينها يتم استدعاء دالة إيقاف التأثير الحركي stop، وتكون قيمته false فيما عدا ذلك.

Animated.timing({}).start(({ finished }) => {
  /* completion callback */
});

استخدام برامج التشغيل الأصلية

المُشغِّل الأصلي (Native driver) يُحوِّل جميع المعلومات الخاصة بالتأثير الحركي المُراد إنشاءه إلى شيفرة أصلية (Native Code) قبل بدء التنفيذ، مما يسمج للشيفرة الأصلية بتنفيذ التأثيرات على واجهة المستخدم مباشرة دون المرور بالجسر الذي يربط بين شيفرة React Native والشيفرة الأصلية.

يمكن تفعيل استخدام المشغلات الأصلية من خلال إعطاء الخاصية useNativeDriver القيمة true . لمزيد من المعلومات انظر دليل التأثيرات الحركية.

المكونات القابلة للتحريك

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

تُستخدم الدالة ()createAnimatedComponent لإنشاء مكوّنات قابلة للتحريك.

يشمل المكون Animated المكونات التالية:

• Animated.Image
• Animated.ScrollView
• Animated.Text
• Animated.View
• Animated.FlatList
• Animated.SectionList

تركيب التأثيرات الحركية

يُمكن تركيب التأثيرات الحركية المختلفة لإنشاء تأثيرات أكثر تعقيدًا عن طريق استخدام دوال الدمج.

• ()nimated.delay: تؤخِّر بدء تنفيذ التحريك بمقدار زمني معين.
• ()Animated.parallel: تبدأ تنفيذ عدد من التأثيرات الحركية في نفس الوقت.
• ()Animated.squence: تُنفِّذ التأثيرات الحركية واحدًا تلوَ الآخر بالتسلسل.
• ()Animated.stagger: تبدأ التأثيرات الحركية متوازيةً ومتسلسل، ولكن مع تتأخيرات متتالية.

ويمكن أيضًأ ربط التأثيرات الحركية ببعضها البعض عن طريق تعيين قيمة الخاصية toValue لأحد التأثيرات لتكون Animated.Value. انظر تتبع القيم في دليل التأثيرات الحركية.

دمج التأثيرات الحركية

يمكن دمج التأثيرات الحركية عن طريق عمليات الجمع، والطرح، والضرب، والقسمة، وباقي القسمة للحصول على تأثيرات حركية جديدة.

• ()Animated.add
• ()Animated.subtract
• ()Animated.divide
• ()Animated.modulo
• ()Animated.multiply

الاستيفاء

تُستخدم الدالة interpolate لتحديد مدى معيّن للمُدخلات للحصول على مُخرجات في مدى معين آخر. حيث تقرأ افتراضيًّا المنحنى خارج المدى المحدد، ولكن يمكنك جعله يثبّت قيمة المخرجات. تستخدم الدالة الاستيفاء الخطي افتراضيًّأ ولكنها تدعم جميع وظائف التحريك (easing functions).

انظر دليل التأثيرات الحركية.

التعامل مع الإيماءات والأحداث الأخرى

يمكن تحديد قيم للإيماءات، مثل التحريك أو التمرير، والأحداث الأخرى باستخدام الدالة ()Animated.event ، حيث تُستخدم بنية الخريطة الهيكلية لاستخراج القيم من الكائنات المعقدة.

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

• [Animated.event().](https://reactnative.dev/docs/animated#event)

عند التعامل مع إيماءات التمرير الأفقي على سبيل المثال، يمكنك القيام بما يلي من أجل تعيين event.nativeEvent.contentOffset.x إلى scrollY.

 onScroll={Animated.event(
   // scrollX = e.nativeEvent.contentOffset.x
   [{ nativeEvent: {
        contentOffset: {
          x: scrollX
        }
      }
    }]
 )}

التوابع

ملاحظة عندما استخدام ValueXY بدلًا عن Value لإستقبال المُدخلات، فستُصبح خيارات الضبط (Config options) مجموعة متجهات (vectors) بدلًا عن قيم قياسية (أرقام).

decay()

static decay(value, config)

تُحرك قيمة معينة من السرعة الإبتدائية إلى الصفر بمعدل معين.

يحتوي الكائن config على خيارات التحريك وهي:

• velocity: (مطلوب) ويمثل السرعة الإبتدائية.
• deceleration: معدل التباطؤ. القيمة الافتراضية هي 0.997.
• isInteraction: تُحدد ما إذا كان التأثير الحركي سيُنشئ مُتحكِّم تفاعلي (interaction handle) في interacionManagerأم لا. القيمة الافتراضية هي true.
• useNativeDriver: تستخدم برنامج التشغيل الأصلي عندما تكون قيمتها true. القيمة الافتراضية هي false.

timing

static timing(value, config)

تُحرك قيمة على منحنى معين. تحتوي وِحدة التسارع على العديد من المنحنيات المُعرفَّة مسبقًا، ويمكنك أيضًا تعريف منحنيات جديدة باستخدام دوال معينة.

يحتوي الكائن config على خيارات التحريك وهي:

• duration: تُحدد المدة الزمنية (بالملي ثانية) التي يستغرقها التأثير الحركي للوصول لنقطة النهاية. القيمة الافتراضية هي 500.
• easing: تُحدد دالة التسارع التي بدورها تُعرِّف منحى التأثير الحركي. القيمة الافتراضية هي Easing.inOut(Easing.ease).
• delay: تؤخر بدء التأثير الحركي بمقدار زمني محدد. القيمة الافتراضية هي صفر.
• isInteraction: تُحدد ما إذا كان التأثير الحركي سيُنشئ مُتحكِّم تفاعلي (interaction handle) في interacionManagerأم لا. القيمة الافتراضية هي true.
• useNativeDriver: تستخدم برنامج التشغيل الأصلي عندما تكون قيمتها true. القيمة الافتراضية هي false.

spring

static spring(value, config)

يُحرِّك القيمة وفقًأ لنموذج النابض القائم على الحركة التذبذبية التوافقية.

ملاحظة يمكنك تعريف واحد فقط من الخيارات التالية: bounciness/speedأو tension/friction أو stiffness/damping/mass.

تُطابق friction/tension وbounciness/speed خيارات نموذج النابض الخاص بفيسبوك وRebound وOrigami.

• friction: يتحكم في النسبة bounciness/overshoot. القيمة الافتراضية هي 7.
• tension: يتحكم في السرعة. القيمة الافتراضية هي 40.
• speed`: يتحكم في سرعة التأثير الحركي. القيمة الافتراضية هي 12.
• bounciness`: يتحكم في القفزات. القيمة الافتراضية هي 8.

تحديد المعاملات stiffness/damping/mass يجعل Animated.springتستخدم نموذج نابض تحليلي يعتمد على معاطلات الحركة التذبذبية التوافقية. هذا الأسلوب يستعمل قوانين الفيزياء ويُحاكي تطبيق CASpringAnimation على نظام iOS.

• stiffness: يُحدد معامل صلابة النابض. القيمة الافتراضية هي 100.
• damping: يُحدد كيف تتباطأ سُرعة حركة النابض بسبب قوى الاحتكاك. القيمة الافتراضية هي 10.
• mass: تُحدد كتلة الجسم المُعَلَّق على النابض. القيمة الافتراضية هي 1.

معاملات اضافية

• velocity: السرعة الابتدائية للجسم المعلق على النابض. القيمة الافتراضية هي صفر.
• overshootClamping: قيمة منطقية تشير إلى ما إذا كان ينبغي تثبيت النابض وإيقاف الارتداد. القيمة الافتراضية هي false.
• restDisplacementThreshold : يحدد قيمة عتبة الإزاحة من السكون والتي يجب اعتبار النابض تحتها في حالة سكون (عدم حركة). القيمة الافتراضية هي 0.001.
• restSpeedThreshold: يحدد السرعة التي يعتبر عندها النابض في حالة سكون، وتقاس بوحدات البكسل في الثانية. القيمة الافتراضية هي 0.001.
• delay: تؤخر بدء التأثير الحركي بمقدار زمني محدد. القيمة الافتراضية هي صفر.
• isInteraction: تُحدد ما إذا كان التأثير الحركي سيُنشئ مُتحكِّم تفاعلي (interaction handle) في interacionManagerأم لا. القيمة الافتراضية هي true.
• useNativeDriver: تستخدم برنامج التشغيل الأصلي عندما تكون قيمتها true. القيمة الافتراضية هي false.

add()

تُنشئ تأثير حركي جديد ناتج عن دمج تأثيرين حركيين مع بعضهما البعض.

static add(a,b)

substract

تُنشئ تأثير حركي جديد عن طريق طرح التأثير الحركي الثاني من التأثير الحركي الأول.

static subtract(a,b)

divide()

تُنشئ تأثير حركي جديد عن طريق قسمة التأثير الحركي الأول على التأثير الحركي الثاني.

static divide(a,b)

multiply()

تُنشئ تأثير حركي جديد عن طريق ضرب التأثير الحركي الأول في التأثير الحركي الثاني.

static multiply(a,b)

modulo()

تُنشئ تأثير حركي جديد عن طريق أخذ باقي قسمة التأثير الحركي الأول على التأثير الحركي الثاني.

static modulo(a,b)

diffClamp

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

هذا مفيد مع أحداث التمرير، على سبيل المثال لإظهار شريط التنقل عند التمرير لأعلى وإخفاءه عند التمرير لأسفل.

static diffClamp(a, min, max)

delay()

تؤخر بدء التأثير الحركي بمقدار زمني محدد.

static delay(time)

sequence()

تُنفذ عدد من التأثيرات الحركية بشكل متتابع الواحد تلو الآخر.

static sequence(animations)

parallel()

تنفذ عددًا من التأثيرات الحركية (مصفوفة من الحركات) في نفس الوقت بشكل متوازي. بشكل افتراضي فإنًَه عند توقف تأثير حركي واحد تتوقف جميع التأثيرات الحركية الأخرى. ويمكن تجاوز هذا السلوك باستخدام المُعرِّف stopTogether.

static parallel(animations, config?)

stagger()

مصفوفة من التأثيرات الحركية تنفذ بشكل متوازي (متداخلة)، ولكنها تبدأ بشكل تسلسلي بتأخيرات معينة. مناسبة لعمل تأثيرات زائدة.

loop()

تُكرر التأثيرات الحركية بشكل مستمر. يحدث التكرار دون حظر سلسلة جافا سكريبت في حال كانت قيمة الخاصية useNativeDriver هي true.

من الممكن أن تمنع الحلقات المكونات المبنية على المكون VirtualizedList من عرض المزيد من الصفوف أثناء تشغيل التأثير الحركي، ويمكن إصلاح هذا عن طريق إعطاء الخاصية isInteraction القيمة false.

• iterations: عدد مرات تكرار التأثيرات الحركية. القيمة الافتراضية هي -1 وتعني إعادة التكرار إلى ما لا نهاية.

event()

static event(argMapping, config?)

تأخذ مصفوفة بيانات وتستخرج قيم التأثيرات الحركية من هذه البيانات. ثم تستدعى الدالة setValueعلى المخرجات المعينة.

*مثال

 onScroll={Animated.event(
   [{nativeEvent: {contentOffset: {x: this._scrollX}}}],
   {listener: (event) => console.log(event)}, // Optional async listener
 )}
 ...
 onPanResponderMove: Animated.event([
   null,                // raw event arg ignored
   {dx: this._panX}],    // gestureState arg
{listener: (event, gestureState) => console.log(event, gestureState)}, // Optional async listener
 ),

يحتوي الكائن config على الخيارات التالية:

• listener: (اختياري) مستمع غير متزامن.
• useNativeDriver: تستخدم برنامج التشغيل الأصلي عندما تكون قيمتهاtrue. القيمة الإفتراضية هيfalse`.

forkEvent()

static forkEvent(event, listener)

واجهة برمجية حديثة لمراقبة الأحداث المتحركة التي يتم تمريرها كمعاملات. تسمح بإضافة مستمع جديد إلى المستمع AnimatedEvent الموجود مسبقًا. إذا كان animatedEvent مستمعًا لجافا سكريبت سيدمج المستعمان معًا في مستمع واحد، وإذا كان animatedEvent خالي (أي قيمته null أو undefined)، يُعيَّن مستمع جافا سكريبت مباشرةً. تستخدم القيم مباشرةً إذا كان ذلك ممكنًا.

unforkEvent()

static unforkEvent(event, listener)

start()

static start([callback]: ?(result?: {finished: boolean}) => void)

تبدأ التأثيرات الحركية عندما يتم استدعاء الدالة start()، والتي بدورها تأخذ دالة أخرى تُستدعى عند إيقاف التأثير الحركي عن طريق الدالة stop().

الاسم	النوع	مطلوب	الوصف
callback	?(result?: {finished: boolean})	لا	دالة تُستدعى عندما يتم إيقاف التأثير الحركي باستخدام الدالة stopأو عن انتهائه.

مثال

Animated.timing({}).start(({ finished }) => {
  /* completion callback */
});

stop()

static stop()

توقف جميع التأثيرات الحركية قيد التنفيذ.

reset()

static reset()

توقف جميع التأثيرات الحركية قيد التنفيذ وتعيد قيمتها للقيمة الابتدائية.

مرجع الخاصيّات

value

القيمة الأساسية للتأثيرات الحركية، وعادة ما تأخذ القيمة صفر في البداية.

new Animated.Value(0)

مزيد من المعلومات حول Animated.Value.

valueXY()

كائن ثُنائي الابعاد يستخدم لإنشاء التأثيرات الحركية ثنائية الابعاد.

مزيد من المعلومات حول Animated.ValueXY.

Interpolation

تم تصديرها لاستخدام أنواع الاستيفاء في التدفق

Node

جميع القيم المتحركة مشتقة من هذا الصنف، وذلك لسهولة فحص أنواع البيانات عليه.

createAnimatedComponent

تستخدم لجعل المكونات قابلة للتحريك.

attachNativeEvent

واجهة برمجية ضرورية لاضافة القيم المتحرِّكة للأحداث في مكون العرض. يُفضّل استخدام Animated.eventمع الخاصية useNativeDriver: true.

المصادر

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