ReactNative/virtualizedlist

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

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

مثال

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

const DATA = [];

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

const getItemCount = (data) => {
  return 50;
}

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

const VirtualizedListExample = () => {
  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: Constants.statusBarHeight,
  },
  item: {
    backgroundColor: '#f9c2ff',
    height: 150,
    justifyContent: 'center',
    marginVertical: 8,
    marginHorizontal: 16,
    padding: 20,
  },
  title: {
    fontSize: 32,
  },
});

export default VirtualizedListExample;

ملاحظات

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

الخاصيات

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

renderItem

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

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

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

data

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

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

getItem

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

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

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

getItemCount

(data: any) => number;

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

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

debug

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

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

extraData

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

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

getItemLayout

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

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

initialScrollIndex

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

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

inverted

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

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

CellRendererComponent

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

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

النوع	مطلوب
component, function	لا

ItemSeparatorComponent

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

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

النوع	مطلوب
component, function	لا

listKey

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

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

listEmptyComponent

يُعرض هذا المكون عندما تكون القائمة فارغة، وقد يكون مكوِّنًا صنفيًّا (Class component) أو مكونًا دالِّيًا (function componenet) أو عنصرًا.

النوع	مطلوب
component، function، element	لا

ListItemComponent

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

النوع	مطلوب
component, function	لا

ListFooterComponent

يُعرض في أسفل القائمة (تذييل للقائمة)، وقد يكون مكوِّنًا صنفيًّا (Class component) أو مكونًا دالِّيًا (function componenet) أو عنصرًا.

النوع	مطلوب
component، function، element	لا

ListFooterComponentStyle

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

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

ListHeaderComponenet

يُُعرض في أعلى القائمة، وr$ يكون مكوِّن صنفي (Class component) أو مكون دالِّي (function componenet).

النوع	مطلوب
component، function، element	لا

ListHeaderComponenetStyle

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

النوع	مطلوب
component، function، element	لا

onRefresh

() => void

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

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

onScrollToIndexFailed

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

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

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

onViewableItemsChanged

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

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

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

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 في نفس الزوج.

النوع	مطلوب
(array of (ViewabilityConfigCallbackPair	لا

horizontal

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

initialNumToRender

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

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

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

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)	لا

updateCellsBatchingPeriod

تُحدد المدة الزمنية بين عرض دفعات العناصر.

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

windowSize

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

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

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

disableVirtualization

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

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

persistentScrollbar

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

progressViewOffset

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

النوع	مطلوب	نظام التشغيل
عدد	لا	أندرويد

الدوال

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 الإزاحة التي يجب التمرير لها. إذا كانت القائمة أفقية تكون قيمة هذه المعامل على محور (x)، وعلى محور (y) إذا كانت القائمة رأسية.
• يُحدد المعامل animated ما إذا كانت ستُضاف تأثيرات حركية أثناء عملية التمرير أم لا.

‎recordInteraction()‎

recordInteraction();

()flashScrollINdicators

flashScrollIndicators();

getScrollResponder

getScrollResponder() => ?scollResponderType;

()getScrollableNote

getScrollableNode () => ?number;

‎getScrollRef()‎

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

‎setNativeProps()‎

setNativeProps((props: Object));

‎getChildContext()‎

getChildContext() => Object;

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

• VirtualizedList (كائن). يتكون من:

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

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

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

• getOutermostParentListRef (دالة).

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

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

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

وتُرجع ChildListState.

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

{
	key: string,
	state: ChildListState
}

• ‪debugInfo (ListDebugInfo)

‎hasMore()‎

hasMore() => boolean

المصادر

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