المكون VirtualizedList في ReactNative

إذا أردت أن تتحصل على مرونة أكبر من التي يوفرها المكونان <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.

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

ListHeaderComponenet

يُُعرض في أعلى القائمة، ويمكن أن يكون مكوِّن صنفي (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 الرسمي.