ReactNative/virtualizedlist

إذا أردت أن تتحصل على مرونة أكبر من التي يوفرها المكونان <FlatList> و<SectionList> لطريقة عرض القوائم، فعليك استخدام المكون VirtualizedList، والذي يوفّر عناصر البناء الرئيسية لعرض القوائم. للاستخدام مع البيانات الغير قابلة للتعديل بدلًا عن المصفوفات العادية على سبيل المثال.

لهذا المكوّن فوائد عديدة حيث أنه يقلّل استهلاك الذاكرة ويحسِّن أداء القوائم كثيرًا من خلال الحفاظ على نافذة عرض محدودة للعناصر النشطة، ويستبدل العناصر الموجودة خارج هذه النافذة بمساحات فارغة بأحجام مناسبة. ويتم عرض العناصر تتابعيًا عند التمرير لأسفل في الشاشة، إذ تُعرض (تصير) العناصر البعيدة عن مجال الرؤية أو العرض بأسلوب أداء منخفض low-pri (قبل تشغيل أي تفاعلات) أو إن كانت قريب من مجال الرؤية، فتعرض بأسلوب أداء مرتفع hi-pri وكل ذلك لتقليل أي احتمال برؤية مسافة فارغة.

مثال

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

import React from 'react';
import { SafeAreaView, View, VirtualizedList, StyleSheet, Text, StatusBar } from 'react-native';

const DATA = [];

const getItem = (data, index) => ({
  id: Math.random().toString(12).substring(0),
  title: `Item ${index+1}`
});

const getItemCount = (data) => 50;

const Item = ({ title }) => (
  <View style={styles.item}>
    <Text style={styles.title}>{title}</Text>
  </View>
);

const App = () => {
  return (
    <SafeAreaView style={styles.container}>
      <VirtualizedList
        data={DATA}
        initialNumToRender={4}
        renderItem={({ item }) => <Item title={item.title} />}
        keyExtractor={item => item.key}
        getItemCount={getItemCount}
        getItem={getItem}
      />
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    marginTop: StatusBar.currentHeight,
  },
  item: {
    backgroundColor: '#f9c2ff',
    height: 150,
    justifyContent: 'center',
    marginVertical: 8,
    marginHorizontal: 16,
    padding: 20,
  },
  title: {
    fontSize: 32,
  },
});

export default App;

ملاحظات

• عند تمرير المحتوى خارج نافضة العرض، لا يحتفظ المكون VirtualizedList بالحالة الخاصة به، لذلك يجب التأكد من حفظها في مخزن خارجي للبيانات مثل Flux أو Redux أو Relay.
• يعتبر هذا المكون PureComponent، أي أنه لن يعاد رسمه إذا كانت الخاصيَّات متساوية تساويًا سطحيًا (shallow-equal). لذلك يجب التأكد من أن جميع الخاصيات التي تعتمد الدالة renderItem عليها قد تم تمريرها كمعاملات لا تساوي قيمتها قيمة الخاصيَّات الحالية للتأكد من تحديث واجهة المستخدم عند تغيير البيانات.
• يُعرض المحتوى بطريقة غير متزامنة خارج نافذة العرض، وذلك للحفاظ على مساحة الذاكرة وضمان التمرير السلس، هذا يعي أنه من الممكن ظهور مساحات فارغة للحظات بسيطه قبل ظهور المحتوى عند التمرير بسرعة عالية. ونعمل على تحسين هذا السلوك خلف الكواليس.
• يبحث المكون VirtualizedList افتراضيًا عن الخاصية key في كلّ عنصر من العناصر الأبناء.

الخاصيات

يرث خواص المكون ScrollView.

data

مصفوفة من الأصناف يمثِّل كلّ صنف أحد العناصر التي ستُعرض في القائمة، ويكون كلّ صِنف في الشكل {key: string} افتراضيًا، ويمكن استخدام الخاصيِّات getItem وgetItemCount وkeyExtractor للتعامل مع جميع انواع البيانات المُرتبة.

النوع	مطلوب
أي نوع <any>	نعم

getItem

(data: any, index: number) => object;

دالة تمكِّنك من الوصول لعنصر معين من العناصر المحفوظة في الخاصية data إن كانت بياناتها خام blob.

النوع	مطلوب
دالة (function)	نعم

getItemCount

(data: any) => number;

تحسب عدد العناصر الموجودة في البيانات الخام data.

النوع	مطلوب
دالة (function)	نعم

renderItem

(info: any) => ?React.Element<any>

تأخذ عنصر من data وتعرضه في القائمة.

النوع	مطلوب
دالة (function)	نعم

CellRendererComponent

تُعرض جميع الخلايا بواسطة هذا العنصر. وقد يكون React Component Class أو render function.

والقيمة الإفتراضية له هي المكون View.

النوع	مطلوب
مكون component، دالة function	لا

ItemSeparatorComponent

يعرض هذا المكوّن فواصلًا بين العناصر، ويمتلك الخاصيتين highlighted وleadingItem إفتراضيًّا.

توفِّر الخاصية renderItem الخواص separators.highlight وseparators.unhighlight واللتان تُستعملان لتحديث قيمة الخاصية highlighted. يمكن أيضًا إضافة خواص أخرى عن طريق الخاصية separators.updateProps.

النوع	مطلوب
مكون component، دالة function	لا

listEmptyComponent

يُعرض هذا المكون عندما تكون القائمة فارغة، ويمكن أن يكون مكون React (مثل SomeComponent) أو عنصر React (مثل <SomeComponent /‎>).

النوع	مطلوب
مكون component، عنصر element	لا

ListItemComponent

مكون يُستخدم لعرض عناصر القائمة، وقد يكون مكون صنف (Class component) أو دالة عرض (تصيير).

النوع	مطلوب
مكون component، دالة function	لا

ListFooterComponent

يُعرض في أسفل القائمة (تذييل للقائمة)، ويمكن أن يكون مكون React (مثل SomeComponent) أو عنصر React (مثل <SomeComponent /‎>).

النوع	مطلوب
مكون component، عنصر element	لا

ListFooterComponentStyle

تُحدد أنماط المكوّن ListFooterComponent.

النوع	مطلوب
خاصيات ViewStyle	لا

ListHeaderComponenet

يُُعرض في أعلى القائمة، وr$ ويمكن أن يكون مكون React (مثل SomeComponent) أو عنصر React (مثل <SomeComponent /‎>).

النوع	مطلوب
مكون component، عنصر element	لا

ListHeaderComponenetStyle

تُحدد أنماط المكون ListHeaderCompoenet.

النوع	مطلوب
خاصيات ViewStyle	لا

debug

يظهر المزيد من التفاصيل عن الأخطاء التي تحدث أثناء التعامل مع المكون VirtulizedList مما يسهل عملية تصحيح الأخطاء (debugging).

النوع	مطلوب
قيمة منطقية (bool)	لا

disableVirtualization

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

النوع	مطلوب
قيمة منطقية (bool)	لا

extraData

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

النوع	مطلوب
قيمة منطقية (bool)	لا

getItemLayout

(
    data: any,
    index: number,
  ) => {length: number, offset: number, index: number}

النوع	مطلوب
دالة (function)	لا

horizontal

إن كانت true، فستعرض عناصر القائمة بجانب بعضها بعضًا أفقيًا بدلًا من عرضها فوق بعضها شاقوليًا.

النوع	مطلوب
قيمة منطقية (bool)	لا

initialNumToRender

تُحدد عدد العناصر التي ستُعرض في أول دفعة. يجب أن يكون عدد العناصر كافي لملء الشاشة أو أقل من ذلك ولكن يجب أن لا يزيد عن حجم الشاشة.

ملاحظة: لتحسين عملية التمرير لأعلى (Scroll-to-top) يجب ألّا تُحذف هذه العناصر كجزء من إطارات العرض.

النوع	مطلوب
عدد (number)	لا

initialScrollIndex

بدلًا عن عرض أول عنصر في أعلى القائمة، تحدِّد هذه الخاصية ترتيب العنصر الذي يجب بدء عرضه في بداية القائمة، وذلك عن طريق ايقاف تحسين التمرير الى الأعلى الذي يحافظ على عرض عناصر initialNumToRender ويُعرض العناصر ابتداءً من أول عنصر في الترتيب، وتتطلّب هذه الخاصية أن تكون الخاصية getItemLayout مفعّلة.

النوع	مطلوب
عدد (number)	لا

inverted

تعكس إتجاه التمرير باستخدام تحويلات بمقياس (-1).

النوع	مطلوب
دالة (function)	لا

listKey

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

النوع	مطلوب
سلسلة نصية (string)	لا

keyExtractor

(item: object, index: number) => string;

تُستخدم للحصول على مفتاح عنصر ذو ترتيب معيّن في القائمة. يستخدم المفتاح للتخزين المؤقت (Caching) و على أساس مفتاح لتتبع ترتيب العناصر. يتحقق مُستخرج المفاتيح الافتراضي من item.key، ثم يرجع لاستخدام الترتيب، مثل ما يحدث في React تمامًا.

النوع	مطلوب
دالة (function)	لا

maxToRenderPerBatch

تُحدد أقصى عدد من العناصر يمكن عرضه في الدفعة الواحدة، وكلما زاد هذا العدد ستحصل على معدل ملء شاشة أفضل، ولكن قد يتأثر تجاوب التطبيق مع أحجام الشاشات المختلفة (responsiveness) بسبب تداخل المحتوى المعروض عند الضغط على الأزرار أو التفاعلات الأخرى.

النوع	مطلوب
عدد (number)	لا

onEndReached

دالة تستدعى عند الوصول للموقع المحدَّد بالخاصية onEndReachedThreshold في المحتوى المعروض.

(info: {distanceFromEnd: number}) => void;

النوع	مطلوب
دالة (function)	لا

onEndReachedThreshold

تُحدد إلى أيّ مدى يجب أن تكون الحافة السفلية للقائمة بعيدة من نهاية المحتوى (بوحدات الطول المرئي للقائمة) لتشغيل رد النداء onEndReached. فالقيمة 0.5 على سبيل المثال ستُشغل ردّ النداء onEndReached عندما تكون نهاية المحتوى في حدود نصف الطول المرئي للقائمة.

النوع	مطلوب
عدد (number)	لا

onRefresh

() => void

توفِّر RefreshControl قياسي يُضاف لوظيفة السحب للتحديث (Pull to Refresh)، وعند استخدامها يجب التأكد من ضبط الخاصية refreshing بطريقة صحيحة.

النوع	مطلوب
دالة (funcion)	لا

onScrollToIndexFailed

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

(info: {
    index: number,
    highestMeasuredFrameIndex: number,
    averageItemLength: number,
  }) => void

النوع	مطلوب
دالة (funcion)	لا

onViewableItemsChanged

دالة تُستدعى عندما تتغير الصفوف المعروضة، كما هي مُعرَّفة بالخاصية ViewabilityConfig.

(info: {
    viewableItems: array,
    changed: array,
  }) => void

النوع	مطلوب
دالة (funcion) ‎(callback: { changed: array of ViewTokens, viewableItems: array of ViewTokens }) => void	لا

persistentScrollbar

النوع	مطلوب
قيمة منطقية (bool)	لا

progressViewOffset

اضبط قيمة هذه الخاصية إذا كنت تحتاج لمساحة لعرض مؤشر التحميل.

النوع	مطلوب
عدد	لا

refreshing

اعطي هذه الخاصية القيمة true أثناء إنتظار تحميل بيانات جديدة.

النوع	مطلوب
قيمة منطقية (bool)	لا

refreshControl

عنصر يستخدم للتحكم في طريقة تحديث عناصر القائمة، ويستبدل المكون <RefreshControl> الأصلي، وعند استخدامة يتم تجاهل الخاصيتين onRefreshing وrefreshing.

ملاحظة: يعمل فقط مع المكوّن VirtualizedList عندما تكون القائمة رأسية.

النوع	مطلوب
عنصر element	لا

removeClippedSubviews

تُستخدم لتحسين عملية التمرير في القوائم الطويلة.

ملاحظة: قد تحتوي على أخطاء (محتوى مفقود) في بعض الحالات - استخدمها على مسؤوليتك الخاصة-.

النوع	مطلوب
قيمة منطقية (bool)	لا

renderScrollComponent

(props: object) => element;

تعرض عنصر تمرير (scroll element) مخصَّص، على سبيل المثال RefreshControl ذو أنماط مختلفة.

النوع	مطلوب
دالة (function)	لا

viewabilityConfig

انظر ViewabilityHelper.js لمزيد من المعلومات.

النوع	مطلوب
ViewabilityConfig	لا

viewabilityConfigCallbackPairs

قائمة من أزواج، يتكون كل زوج من المكونين ViewabilityConfig و onViewableItemsChanged. تُستدعى الدالة onViewableItemsChanged من زوج معين عندما يتم استيفاء شروطها المحددة في الخاصية ViewabilityConfig في نفس الزوج.

النوع	مطلوب
مصوفة من الكائن ViewabilityConfigCallbackPair	لا

updateCellsBatchingPeriod

تُحدد المدة الزمنية بين عرض دفعات العناصر بعيدة الرؤية في الوضع low-pri لعرض هذه العناصر. تشبه إلى حد ما maxToRenderPerBatch.

النوع	مطلوب
عدد (number)	لا

windowSize

تُحدد الحدّ الأقصى من العناصر التي يمكن عرضها خارج المنطقة المرئية. على سبيل المثال إذا كانت القائمة تملأ الشاشة، فستعرض الخاصية windowSize=21 كامل القائمة (المنطقة المرئية) بالإضافة لمساحة 10 شاشات فارغة أعلى القائمة و10 أسفلها.

ملاحظة: القيم الصغيرة لهذه الخاصية تؤدّي لتقليل استهلاك الذاكرة وتحسين الأداء، ولكنها تزيد من احتمالية ظهور مساحات فارغة عند التمرير بسرعة كبيرة.

النوع	مطلوب
عدد (number)	لا

التوابع

()flashScrollINdicators

flashScrollIndicators();

‎getChildContext()‎

getChildContext() => Object;

يتكون الكائن VirtualizedList المُرجع من هذه الدالة من:

• getScrollMetrics (دالة). تُرجع كائن يحتوي على الخواص التالية:

{
	contentLength: number,
	dOffest: number,
	dt: number,
	offset: number,
	timestamp: number,
	velocity: number,
	visibleLength: number
}

• horizontal (قيمة منطقية) - اختياري-.

• getOutermostParentListRef (دالة).

• getNestedChildState (دالة) - تُرجع ChildListState.

• registerAsNestedChild (دالة) وتُرجع ChildListState. تستقبل كائنًا يحتوي على الخواص التالية:

{
	cellKey: string,
	key: string,
	ref: VirtualizedList,
	parentDebugInfo: ListDebugInfo
}

• unregisterAsNestedChild (دالة). تستقبل كائن يحتوي على الخواص التالية:

{
	key: string,
	state: ChildListState
}

• ‪debugInfo (ListDebugInfo)

()getScrollableNote

getScrollableNode () => ?number;

‎getScrollRef()‎

getScrollRef () => | ?React.ElementRef<typeof ScrollView>
    | ?React.ElementRef<typeof View>;

()getScrollResponder

getScrollResponder() => ?scollResponderType;

يوفر معالجًا لمستجب التمرير الداخلي (الرئيسي). انتبه إلى أن this._scrollRef قد لا تكون ScrollView، لذا يجب التحقق من أنه يستجيب إلى getScrollResponder قبل استدعائه.

‎hasMore()‎

hasMore() => boolean

scrollToEnd

scrollToEnd((params: object));

Valid `params` consist of:

- 'animated' (boolean). Optional default is true.

scrollToIndex

scrollToIndex((params: object));

المعاملات

المعامل	النوع	مطلوب
animated	قيمة منطقية (bool)	لا
index	عدد (number)	نعم
viewOffset	عدد (number)	لا
viewPosition	عدد (number)	لا

scrollToItem

scrollToItem((params: object));

المعاملات

المعامل	النوع	مطلوب
animated	قيمة منطقية (bool)	لا
item	item	نعم
viewPosition	عدد (number)	لا

scrollToOffset

scrollToOffset((params: object));

تُمرر إلى موضع معين في القائمة.

• يُحدد المعامل offset الإزاحة التي يجب التمرير لها. إذا كانت القائمة أفقية horizontal تكون قيمة هذه المعامل على محور (x)، وعلى محور (y) إذا كانت القائمة رأسية.
• يُحدد المعامل animated ما إذا كانت ستُضاف تأثيرات حركية أثناء عملية التمرير أم لا. قيمته الافتراضية true.

‎recordInteraction()‎

recordInteraction();

‎setNativeProps()‎

setNativeProps((props: Object));

المصادر

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