المكون 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 | لا |
يُعرض في أسفل القائمة (تذييل للقائمة)،ويمكن أن يكون مكوِّن صنفي (Class component) أو مكون دالِّي (function componenet) أو عنصر.
النوع | مطلوب |
---|---|
component، function، element | لا |
تُحدد أنماط المكون 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