الفرق بين المراجعتين ل"ReactNative/scrollview"
(أنشأ الصفحة ب'# ScrollView هو عبارة عن مكوّن يغلّف المنصة ScrollView لتأمين التكامل مع منظومة مستجيب "responder" تعليق ال...') |
|||
| سطر 1: | سطر 1: | ||
| − | # ScrollView | + | <nowiki>#</nowiki> ScrollView |
| − | + | ||
| + | |||
| + | |||
هو عبارة عن مكوّن يغلّف المنصة ScrollView لتأمين التكامل مع منظومة مستجيب "responder" تعليق اللمس (touch locking). | هو عبارة عن مكوّن يغلّف المنصة ScrollView لتأمين التكامل مع منظومة مستجيب "responder" تعليق اللمس (touch locking). | ||
| − | يجب أن يكون ارتفاع المكوّن ScrollView | + | يجب أن يكون ارتفاع المكوّن ScrollView محدد (bounded) لكي يعمل, كونه سيضم مكونات أبناء غير محددة الارتفاع إلى حاوية محددة الارتفاع أثناء التمرير (scroll). وذلك بضبط ارتفاع العرض مباشرة بالخيار discouraged أو بالتأكد من أنه لجميع العروض الآباء ارتفاع محدد. يؤدي نسيان ضبط الالتفاف أسفل العرض على القيمة `{flex: 1}` إلى حدوث خطأ, يسارع مراقب (inspector) العناصر إلى تصحيحه (debug). |
| − | لا يدعم هذا | + | لا يدعم هذا المكون حتى الآن المستجيبات المتضمنة الأخرى لتعلّق عرض التمرير هذا. |
| − | **متى يُستخدم المكوّن [`FlatList`](https://reactnative.dev/docs/flatlist) بدل المكوّن `<ScrollView>`:** | + | <nowiki>**</nowiki>متى يُستخدم المكوّن [`FlatList`](<nowiki>https://reactnative.dev/docs/flatlist</nowiki>) بدل المكوّن `<ScrollView>`:** |
| − | يعرض المكوّن `ScrollView` جميع مكونات react الأبناء دفعة واحدة, مما يؤثر سلبًا على الأداء عند عرض القوائم الطويلة التي تتطلب إنشاء الكثير من مكونات JS والعروض الأصيلة (native) ليتم إظهارها دفعة واحدة, وهذا بدوره يبطئ | + | يعرض المكوّن `ScrollView` جميع مكونات react الأبناء دفعة واحدة, مما يؤثر سلبًا على الأداء عند عرض القوائم الطويلة التي تتطلب إنشاء الكثير من مكونات JS والعروض الأصيلة (native) ليتم إظهارها دفعة واحدة, وهذا بدوره يبطئ العملية الإظهار ويستهلك الكثير من الذاكرة. |
| − | في هذه الحالة يفضَّل استخدام المكون `FlatList` الذي لا يعرض المكونات المراد إظهارها إلا عند الوصول إليها, كما يقوم بإزالتها عند الانتهاء منها مما يوفر من قدرة المعالجة والذاكرة المستخدمة. كما | + | في هذه الحالة يفضَّل استخدام المكون `FlatList` الذي لا يعرض المكونات المراد إظهارها إلا عند الوصول إليها, كما يقوم بإزالتها عند الانتهاء منها مما يوفر من قدرة المعالجة والذاكرة المستخدمة. كما يستخدم هذا المكوّن عند الحاجة لإظهار فاصل بين العناصر أو بين الأعمدة المتعددة, أو لتمرير القوائم متناهية الطول وغيرها من الميزات الغير متوفرة في `ScrollView`. |
| − | ## مثال | + | <nowiki>##</nowiki> مثال |
| + | ```javascript | ||
| − | |||
import React from 'react'; | import React from 'react'; | ||
| + | |||
import { StyleSheet, Text, SafeAreaView, ScrollView } from 'react-native'; | import { StyleSheet, Text, SafeAreaView, ScrollView } from 'react-native'; | ||
| + | |||
import Constants from 'expo-constants'; | import Constants from 'expo-constants'; | ||
const App = () => { | const App = () => { | ||
| − | + | ||
| − | + | return ( | |
| − | + | ||
| − | + | <SafeAreaView style={styles.container}> | |
| − | + | ||
| − | + | <ScrollView style={styles.scrollView}> | |
| − | + | ||
| − | + | <Text style={styles.text}> | |
| − | + | ||
| − | + | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do | |
| − | + | ||
| − | + | eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad | |
| − | + | ||
| − | + | minim veniam, quis nostrud exercitation ullamco laboris nisi ut | |
| − | + | ||
| + | aliquip ex ea commodo consequat. Duis aute irure dolor in | ||
| + | |||
| + | reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla | ||
| + | |||
| + | pariatur. Excepteur sint occaecat cupidatat non proident, sunt in | ||
| + | |||
| + | culpa qui officia deserunt mollit anim id est laborum. | ||
| + | |||
| + | </Text> | ||
| + | |||
| + | </ScrollView> | ||
| + | |||
| + | </SafeAreaView> | ||
| + | |||
| + | ); | ||
| + | |||
} | } | ||
const styles = StyleSheet.create({ | const styles = StyleSheet.create({ | ||
| − | + | ||
| − | + | container: { | |
| − | + | ||
| − | + | flex: 1, | |
| − | + | ||
| − | + | marginTop: Constants.statusBarHeight, | |
| − | + | ||
| − | + | }, | |
| − | + | ||
| − | + | scrollView: { | |
| − | + | ||
| + | backgroundColor: 'pink', | ||
| + | |||
| + | marginHorizontal: 20, | ||
| + | |||
| + | }, | ||
| + | |||
| + | text: { | ||
| + | |||
| + | fontSize: 42, | ||
| + | |||
| + | }, | ||
| + | |||
}); | }); | ||
export default App; | export default App; | ||
| + | |||
``` | ``` | ||
| + | <nowiki>##</nowiki> الخاصيّات (Props) | ||
| − | + | موروثة من الخاصيّات [`View Props`](<nowiki>https://reactnative.dev/docs/view#props</nowiki>). | |
| − | + | <nowiki>###</nowiki> `alwaysBounceHorizontal` | |
| − | + | قيمتها الافتراضية `horizontal={true}` حيث تجعل عرض التمرير يرتد (bounce) أفقيًا عند وصوله للنهاية حتى ولو كان المحتوى أصغر من عرض التمرير نفسه. | |
| − | + | | النوع | مطلوب | المنصة | | |
| − | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| + | | قيمة منطقية (bool) | لا | iOS | | ||
| − | ### `alwaysBounceVertical` | + | <nowiki>###</nowiki> `alwaysBounceVertical` |
قيمتها الافتراضية `vertical={true}` حيث تجعل عرض التمرير يرتد (bounce) عموديًا عند وصوله للنهاية حتى ولو كان المحتوى أصغر من عرض التمرير نفسه. | قيمتها الافتراضية `vertical={true}` حيث تجعل عرض التمرير يرتد (bounce) عموديًا عند وصوله للنهاية حتى ولو كان المحتوى أصغر من عرض التمرير نفسه. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | ### `automaticallyAdjustContentInset` | + | | قيمة منطقية (bool) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `automaticallyAdjustContentInset` | ||
تجعل منصّة iOS تتحكم آليًا بإدخال (inset) المحتوى من أجل عروض التمرير المتواجدة خلف شريط التنقل أو شريط الأدوات. وقيمتها الافتراضية `true`. | تجعل منصّة iOS تتحكم آليًا بإدخال (inset) المحتوى من أجل عروض التمرير المتواجدة خلف شريط التنقل أو شريط الأدوات. وقيمتها الافتراضية `true`. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | ### `bounces` | + | | قيمة منطقية (bool) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `bounces` | ||
| + | |||
| + | قيمتها الافتراضية `true` حيث تجعل عرض التمرير يرتد عند وصوله لنهاية المحتوى إن كان أكبر من عرض التمرير وفق محور التمرير. أما في حال كانت قيمتها `false` فإنها تلغي جميع أنواع الارتداد حتى لو كانت الخاصيات `alwaysBounce*` مفعّلة. | ||
| − | + | | النوع | مطلوب | المنصة | | |
| − | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | ### `bouncesZoom` | + | | قيمة منطقية (bool) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `bouncesZoom` | ||
| + | |||
| + | قيمتها الافتراضية `true` حيث تتيح استخدام الإيماءات (gestures) في تجاوز الحد الأدنى والأقصى للتكبير, ويعود التكبير إلى حدوده الافتراضية بعد انتهاء الإيماءة. | ||
| − | + | | النوع | مطلوب | المنصة | | |
| − | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | ### `canCancelContentTouches` | + | | قيمة منطقية (bool) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `canCancelContentTouches` | ||
إذا كانت قيمتها `false` فإنها تمنع اللمسة المتحركة من السحب (drag). وقيمتها الافتراضية `true`. | إذا كانت قيمتها `false` فإنها تمنع اللمسة المتحركة من السحب (drag). وقيمتها الافتراضية `true`. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | ### `centerContent` | + | | قيمة منطقية (bool) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `centerContent` | ||
إذا كانت قيمتها `true` فإنها تضع المحتوى آليًا في منتصف عرض التمرير إن كان المحتوى أصغر من حدود عرض التمرير, أما إن كان المحتوى أكبر من عرض التمرير فلا تأثير لهذه الخاصيّة. وقيمتها الافتراضية `false`. | إذا كانت قيمتها `true` فإنها تضع المحتوى آليًا في منتصف عرض التمرير إن كان المحتوى أصغر من حدود عرض التمرير, أما إن كان المحتوى أكبر من عرض التمرير فلا تأثير لهذه الخاصيّة. وقيمتها الافتراضية `false`. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | + | | قيمة منطقية (bool) | لا | iOS | | |
| − | + | <nowiki>###</nowiki> `contentContainerStyle` | |
| − | **مثال:** | + | وهي مجموعة من التنسيقات المطبّقة على محتوى عرض التمرير, والتي تغلف جميع عروض المكونات الأبناء. |
| + | |||
| + | <nowiki>**</nowiki>مثال:** | ||
``` | ``` | ||
| + | |||
return ( | return ( | ||
| − | + | ||
| − | + | <ScrollView contentContainerStyle={styles.contentContainer}> | |
| + | |||
| + | </ScrollView> | ||
| + | |||
); | ); | ||
| + | |||
... | ... | ||
| + | |||
const styles = StyleSheet.create({ | const styles = StyleSheet.create({ | ||
| − | + | ||
| − | + | contentContainer: { | |
| − | + | ||
| + | paddingVertical: 20 | ||
| + | |||
| + | } | ||
| + | |||
}); | }); | ||
| + | |||
``` | ``` | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :-------------------------------------------: | :---: | | | :-------------------------------------------: | :---: | | ||
| − | |||
| − | + | | تنسيقات StyleSheetPropType(View Style props) | لا | | |
| − | تحدد مقدار دخول المحتوى من حواف عرض التمرير, | + | <nowiki>###</nowiki> `contentInset` |
| + | |||
| + | تحدد مقدار دخول المحتوى من حواف عرض التمرير, وقمتها الافتراضية `{top: 0, left: 0, bottom: 0, right: 0}`. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :----------------------------------------------------------: | :---: | :----: | | | :----------------------------------------------------------: | :---: | :----: | | ||
| − | |||
| + | | كائن (object: {top: number, left: number, bottom: number, right: number}) | لا | iOS | | ||
| + | <nowiki>###</nowiki> `contentInsetAdjustmentBehavior` | ||
| − | + | تحدد هذه الخاصيّة طريقة استخدام منطقة الإدخال لتعديل منطقة المحتوى في عرض التمرير. والقيمة الافتراضية لها `never`, ومتوفرة فقط على منصة iOS إصدار 11 وما فوق. | |
| − | + | | النوع | مطلوب | المنصة | | |
| − | |||
| :----------------------------------------------------------: | :---: | :----: | | | :----------------------------------------------------------: | :---: | :----: | | ||
| − | |||
| − | ### `contentOffset` | + | | قيمة اسمية (enum('automatic', 'scrollableAxes', 'never', 'always')) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `contentOffset` | ||
تُستخدم لتحديد إزاحة بداية التمرير يدويًا, والقيمة الافتراضية لها `{x: 0, y: 0}`. | تُستخدم لتحديد إزاحة بداية التمرير يدويًا, والقيمة الافتراضية لها `{x: 0, y: 0}`. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :-----------: | :---: | :----: | | | :-----------: | :---: | :----: | | ||
| − | |||
| − | ### `decelerationRate` | + | | PointPropType | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `decelerationRate` | ||
عبارة عن عدد عشري يحدد معدل تباطؤ التمرير بعد رفع الإصبع عن عرض التمرير, كما يمكن استخدام اختصارات السلاسل النصية `normal` و `fast` والتي تقابل الإعدادات `UIScrollViewDecelerationRateNormal` و `UIScrollViewDecelerationRateFast` على منصة iOS. | عبارة عن عدد عشري يحدد معدل تباطؤ التمرير بعد رفع الإصبع عن عرض التمرير, كما يمكن استخدام اختصارات السلاسل النصية `normal` و `fast` والتي تقابل الإعدادات `UIScrollViewDecelerationRateNormal` و `UIScrollViewDecelerationRateFast` على منصة iOS. | ||
| − | * `normal` (الافتراضية)- وتوافق القيمة 0.998 على | + | <nowiki>*</nowiki> `normal` (الافتراضية)- وتوافق القيمة 0.998 على منصة iOS والقيمة 0.985 على منصة Android. |
| − | * `fast` - وتوافق القيمة 0.99 على | + | |
| + | <nowiki>*</nowiki> `fast` - وتوافق القيمة 0.99 على منصة iOS والقيمة 0.9 على منصة Android. | ||
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :---------------------------------------------: | :---: | | | :---------------------------------------------: | :---: | | ||
| − | |||
| − | ### `directionalLockEnabled` | + | | قيمة اسمية, عدد (enum('fast', 'normal'),number) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `directionalLockEnabled` | ||
إذا كانت قيمتها `true` فإنها تسمح بالتمرير فقط وفق الاتجاه العمودي أو الأفقي أثناء السحب. وقيمتها الافتراضية `false`. | إذا كانت قيمتها `true` فإنها تسمح بالتمرير فقط وفق الاتجاه العمودي أو الأفقي أثناء السحب. وقيمتها الافتراضية `false`. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | ### `disableIntervalMomentum` | + | | قيمة منطقية (bool) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `disableIntervalMomentum` | ||
| − | إذا كانت قيمتها `true` فإنها توقف عرض التمرير على الدليل (index) التالي ( | + | إذا كانت قيمتها `true` فإنها توقف عرض التمرير على الدليل (index) التالي (المتعلق بموقع التمرير عند التحرير) بغض النظر عن سرعة الإيماءة. ويمكن أن تستخدم للتصفح الأفقي عندما يكون عرض الصفحة أصغر من عرض ScrollView. وقيمتها الافتراضية `false`. |
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | + | | قيمة منطقية (bool) | لا | | |
| − | إذا كانت قيمتها `true` فإنها تلغي عمل | + | <nowiki>###</nowiki> `disableScrollViewPanResponder` |
| + | |||
| + | إذا كانت قيمتها `true` فإنها تلغي عمل المكون [`PanResponder`](<nowiki>https://wiki.hsoub.com/ReactNative/panresponder</nowiki>) الافتراضي لعرض التمرير, ويُترك التحكم الكامل للمسات داخل عرض التمرير للمكونات الأبناء. وهذا مفيد عمليًا عندما تكون الخاصيّة `snapToInterval` مفعّلة كونها لا تتبع أنمط اللمسات النموذجية. يجب تجنب هذه الخاصيّة في الاستخدامات الاعتيادية لعرض التمرير من دون الخاصيّة `snapToInterval`, لأنها قد تسبب حدوث لمسات غير متوقعة أثناء التمرير. وقيمتها الافتراضية `false`. | ||
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | ### `endFillColor` | + | | قيمة منطقية (bool) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `endFillColor` | ||
| + | |||
| + | تُستخدم هذه الخاصية لملء الفراغ المتبقي في عرض التمرير والذي يحدث أحيانا نتيجة أخذ عرض التمرير لحيز أكبر من الذي يشغله المحتوى, حيث تسمح هذه الخاصية بتجنب إعداد الخلفية. وتعد هذه الخاصيّة من التحسينات المتقدمة والتي لا تُستخدم في الحالات الاعتيادية. | ||
| − | + | | النوع | مطلوب | المنصة | | |
| − | |||
| :--------------------------------------------------: | :---: | :-----: | | | :--------------------------------------------------: | :---: | :-----: | | ||
| − | |||
| − | |||
| − | تُستخدم لتلاشي (Fade) حواف المحتوى الممرر. فإذا كانت قيمتها أكبر من الصفر, فإن تلاشي الحواف سيكون | + | | لون ([`color`](https://reactnative.dev/docs/colors)) | لا | Android | |
| + | |||
| + | <nowiki>###</nowiki> `fadingEdgeLength` | ||
| + | |||
| + | تُستخدم لتلاشي (Fade) حواف المحتوى الممرر. فإذا كانت قيمتها أكبر من الصفر, فإن تلاشي الحواف سيكون وفقا لاتجاه ومكان التمرير الحالي للدلالة فيما إذا كان هنالك مزيدًا من المحتوى لإظهاره. | ||
| + | |||
| + | | النوع | مطلوب | القيمة الافتراضية | المنصة | | ||
| − | |||
| :----------: | :---: | :---------------: | :-----: | | | :----------: | :---: | :---------------: | :-----: | | ||
| − | |||
| − | ### `horizontal` | + | | عدد (number) | لا | 0 | Android | |
| + | |||
| + | <nowiki>###</nowiki> `horizontal` | ||
إذا كانت قيمتها `true` فإن المكونات الأبناء لعرض التمرير ستصطف أفقيًا في سطر بدل الاصطفاف عموديًا في عمود, وقيمتها الافتراضية `false`. | إذا كانت قيمتها `true` فإن المكونات الأبناء لعرض التمرير ستصطف أفقيًا في سطر بدل الاصطفاف عموديًا في عمود, وقيمتها الافتراضية `false`. | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | ### `indicatorStyle` | + | | قيمة منطقية (bool) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `indicatorStyle` | ||
تُستخدم لتنسيق مؤشر التمرير, وقيمها: | تُستخدم لتنسيق مؤشر التمرير, وقيمها: | ||
| − | * `default` (الافتراضية)- نفس `black`. | + | <nowiki>*</nowiki> `default` (الافتراضية)- نفس `black`. |
| − | * `black` - يكون المؤشر أسود ويستخدم مع الخلفيات الفاتحة. | + | |
| − | * `white` - يكون المؤشر أبيض ويستخدم مع الخلفيات الداكنة. | + | <nowiki>*</nowiki> `black` - يكون المؤشر أسود ويستخدم مع الخلفيات الفاتحة. |
| + | |||
| + | <nowiki>*</nowiki> `white` - يكون المؤشر أبيض ويستخدم مع الخلفيات الداكنة. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :--------------------------------------------: | :---: | :----: | | | :--------------------------------------------: | :---: | :----: | | ||
| − | |||
| − | |||
| − | تجعل هذه | + | | قيمة اسمية (enum('default', 'black', 'white')) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `invertStickyHeaders` | ||
| + | |||
| + | تجعل هذه الخاصية الترويسات الدبقة (sticky headers) تلتصق في أسفل عرض التمرير بدل الالتصاق في الأعلى, وعادة ما تستخدم مع عرض التمرير المقلوب. | ||
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | ### `keyboardDismissMode` | + | | قيمة منطقية (bool) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `keyboardDismissMode` | ||
تُستخدم لإبطال لوحة المفاتيح أثناء السحب, وقيمها: | تُستخدم لإبطال لوحة المفاتيح أثناء السحب, وقيمها: | ||
| سطر 250: | سطر 335: | ||
على المنصات المتعددة (Cross platform): | على المنصات المتعددة (Cross platform): | ||
| − | * `none` (الافتراضية)- لا يبطل السحب لوحة المفاتيح. | + | <nowiki>*</nowiki> `none` (الافتراضية)- لا يبطل السحب لوحة المفاتيح. |
| − | * `on-drag` - تبطل لوحة المفاتيح عند بدء السحب. | + | |
| + | <nowiki>*</nowiki> `on-drag` - تبطل لوحة المفاتيح عند بدء السحب. | ||
على منصّة iOS: | على منصّة iOS: | ||
| − | * `interactive` - تبطل لوحة المفاتيح تفاعليًا مع السحب والحركات بالتزامن مع اللمس, وتفعّل بالسحب للأعلى. وهذه الخاصيّة غير مفعّلة على منصّة | + | <nowiki>*</nowiki> `interactive` - تبطل لوحة المفاتيح تفاعليًا مع السحب والحركات بالتزامن مع اللمس, وتفعّل بالسحب للأعلى. وهذه الخاصيّة غير مفعّلة على منصّة وتبقى كما لو أن قيمتها `none`. |
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :---------------------------------------------: | :---: | | | :---------------------------------------------: | :---: | | ||
| − | |||
| − | ### `keyboardShouldPersistTaps` | + | | قيمة اسمية (enum('none', 'on-drag', 'interactive')) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `keyboardShouldPersistTaps` | ||
تحدد فيما إذا كانت لوحة المفاتيح ستبقى ظاهرة بعد النقر (tap), وقيمها: | تحدد فيما إذا كانت لوحة المفاتيح ستبقى ظاهرة بعد النقر (tap), وقيمها: | ||
| − | * `never` (الافتراضية)- إن النقر خارج إطار النص المركّز ولوحة المفاتيح مرفوعة, يؤدي إلى إبطالها. ولن تستقبل المكونات الأبناء لعرض التمرير النقر عند حدوث ذلك. | + | <nowiki>*</nowiki> `never` (الافتراضية)- إن النقر خارج إطار النص المركّز ولوحة المفاتيح مرفوعة, يؤدي إلى إبطالها. ولن تستقبل المكونات الأبناء لعرض التمرير النقر عند حدوث ذلك. |
| − | * `always` - لا تبطل لوحة المفاتيح تلقائيًا, ولن يستقبل عرض التمرير النقر لكن المكونات الأبناء تستطيع استقباله. | + | |
| − | * `handled` - لا تبطل لوحة المفاتيح تلقائيًا عند معالجة النقر من قبل المكونات الأبناء لعرض التمرير (أو عند استقباله من قبل المكونات الأجداد). | + | <nowiki>*</nowiki> `always` - لا تبطل لوحة المفاتيح تلقائيًا, ولن يستقبل عرض التمرير النقر لكن المكونات الأبناء تستطيع استقباله. |
| − | * `false` (مهملة)- استخدم `never` بدلًا منها. | + | |
| − | * `true` (مهملة)- استخدم `always` بدلًا منها. | + | <nowiki>*</nowiki> `handled` - لا تبطل لوحة المفاتيح تلقائيًا عند معالجة النقر من قبل المكونات الأبناء لعرض التمرير (أو عند استقباله من قبل المكونات الأجداد). |
| + | |||
| + | <nowiki>*</nowiki> `false` (مهملة)- استخدم `never` بدلًا منها. | ||
| + | |||
| + | <nowiki>*</nowiki> `true` (مهملة)- استخدم `always` بدلًا منها. | ||
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :----------------------------------------------------------: | :---: | | | :----------------------------------------------------------: | :---: | | ||
| − | |||
| − | + | | قيمة اسمية (enum('always', 'never', 'handled', false, true)) | لا | | |
| − | + | <nowiki>###</nowiki> `maintainVisibleContentPosition` | |
| − | + | عند استخدام هذه الخاصيّة, فإن عرض التمرير يضبط موقع التمرير بحيث لا يتغير موقع المكون الابن الأول والظاهر حاليًا (عند القيمة `minIndexForVisible` أو ما بعدها). وهذا مفيد مع القوائم التي تحمّل المحتوى من كلا الاتجاهين كما هي الحال في الدردشة, حيث تمنع هذه الخاصية الرسائل الجديدة الواردة من إزاحة موقع التمرير. القيمة الاعتيادية لهذه الخاصية هي `0`, غير أنه يمكن استخدام قيم أخرى مثل `1` من أجل تجاهل تحميل المحتوى الذي قد يغيّر موقع التمرير. | |
| − | + | يمكن استخدام القيمة الاختيارية `autoscrollToTopThreshold` لتمرير المحتوى تلقائيا للأعلى بعد ضبط موقع التمرير في حال كان المستخدم ضمن العتبة العليا قبل الضبط. وهذا مفيد في تطبيقات الدردشة من أجل رؤية الرسائل الجديدة الواردة بشكل تلقائي دون الحاجة للتمرير, في حال قام المستخدم بالتمرير بعيدًا عنها. | |
| − | **تنبيه 2:** تستخدم هذه الخاصيّة الخاصيتين `contentOffset` و `frame.origin` في الشفرة الأصيلة لحساب قدرة الإظهار (visibility). كما أنه لم يؤخذ في الاعتبار التحويلات وتعقيدات الإظهار الأخرى. | + | <nowiki>**</nowiki>تنبيه 1:** قد يؤدي إعادة ترتيب عناصر scrollview مع تمكين هذه الخاصيّة إلى حدوث تقفّز (jumpiness). ولا يوجد نيّة حاليًا لإصلاح هذا الخلل, لذا يجب حاليًا تجنّب إعادة ترتيب محتوى أي مكوّن scrollview أو Lists يستخدم هذه الخاصيّة. |
| + | |||
| + | <nowiki>**</nowiki>تنبيه 2:** تستخدم هذه الخاصيّة الخاصيتين `contentOffset` و `frame.origin` في الشفرة الأصيلة لحساب قدرة الإظهار (visibility). كما أنه لم يؤخذ في الاعتبار التحويلات وتعقيدات الإظهار الأخرى. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :----------------------------------------------------------: | :---: | :----: | | | :----------------------------------------------------------: | :---: | :----: | | ||
| − | |||
| − | ### `maximumZoomScale` | + | | كائن (object: { minIndexForVisible: number, autoscrollToTopThreshold: number }) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `maximumZoomScale` | ||
| − | تحدد مقياس الرسم (scale) الأعظمي للتكبير. قيمتها الافتراضية | + | تحدد مقياس الرسم (scale) الأعظمي للتكبير. قيمتها الافتراضية 1. |
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :----------: | :---: | :----: | | | :----------: | :---: | :----: | | ||
| − | |||
| − | + | | عدد (number) | لا | iOS | | |
| − | تحدد مقياس الرسم (scale) الأصغري للتكبير. قيمتها الافتراضية | + | <nowiki>###</nowiki> `minimumZoomScale` |
| + | |||
| + | تحدد مقياس الرسم (scale) الأصغري للتكبير. قيمتها الافتراضية 1. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :----------: | :---: | :----: | | | :----------: | :---: | :----: | | ||
| − | |||
| − | ### `nestedScrollEnabled` | + | | عدد (number) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `nestedScrollEnabled` | ||
تمكّن من التمرير المتداخل (nested), ومدعومة على واجهات منصة Android البرمجية من المستوى 21+. كما أنها مدعومة افتراضيًا على منصّة iOS. | تمكّن من التمرير المتداخل (nested), ومدعومة على واجهات منصة Android البرمجية من المستوى 21+. كما أنها مدعومة افتراضيًا على منصّة iOS. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :----------------: | :---: | :-----: | | | :----------------: | :---: | :-----: | | ||
| − | |||
| − | ### `onContentSizeChange` | + | | قيمة منطقية (bool) | لا | Android | |
| + | |||
| + | <nowiki>###</nowiki> `onContentSizeChange` | ||
تُستدعى هذه الدالة عند تغيّر المحتوى الممرر في ScrollView, حيث يمرر لهذه الدالة عرض وارتفاع المحتوى على شكل معاملين: `contentWidth` و `contentHeight`. | تُستدعى هذه الدالة عند تغيّر المحتوى الممرر في ScrollView, حيث يمرر لهذه الدالة عرض وارتفاع المحتوى على شكل معاملين: `contentWidth` و `contentHeight`. | ||
| سطر 319: | سطر 421: | ||
صُممت هذه الدالة باستخدام المعالج `onLayout` والمرتبط بحاوية المحتوى الذي يظهره ScrollView. | صُممت هذه الدالة باستخدام المعالج `onLayout` والمرتبط بحاوية المحتوى الذي يظهره ScrollView. | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :-------------: | :---: | | | :-------------: | :---: | | ||
| − | |||
| − | ### `onMomentumScrollBegin` | + | | دالة (function) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `onMomentumScrollBegin` | ||
تُستدعى هذه الدالة عند بدء زخم (momentum) التمرير (حين يبدأ ScrollView بالانزلاق). | تُستدعى هذه الدالة عند بدء زخم (momentum) التمرير (حين يبدأ ScrollView بالانزلاق). | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :-------------: | :---: | | | :-------------: | :---: | | ||
| − | |||
| − | ### `onMomentumScrollEnd` | + | | دالة (function) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `onMomentumScrollEnd` | ||
تُستدعى هذه الدالة عند انتهاء زخم التمرير(حين يتوقف ScrollView عن الانزلاق). | تُستدعى هذه الدالة عند انتهاء زخم التمرير(حين يتوقف ScrollView عن الانزلاق). | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :-------------: | :---: | | | :-------------: | :---: | | ||
| − | |||
| − | ### `onScroll` | + | | دالة (function) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `onScroll` | ||
تُطلق مرة واحدة على الأكثر لكل إطار (frame) أثناء التمرير. ويمكن التحكم بتردد الأحداث عن طريق الخاصيّة `scrollEventThrottle`, ولهذه الأحداث الشكل التالي (جميع القيم أعداد): | تُطلق مرة واحدة على الأكثر لكل إطار (frame) أثناء التمرير. ويمكن التحكم بتردد الأحداث عن طريق الخاصيّة `scrollEventThrottle`, ولهذه الأحداث الشكل التالي (جميع القيم أعداد): | ||
``` | ``` | ||
| + | |||
{ | { | ||
| − | + | ||
| − | + | nativeEvent: { | |
| − | + | ||
| − | + | contentInset: {bottom, left, right, top}, | |
| − | + | ||
| − | + | contentOffset: {x, y}, | |
| − | + | ||
| + | contentSize: {height, width}, | ||
| + | |||
| + | layoutMeasurement: {height, width}, | ||
| + | |||
| + | zoomScale | ||
| + | |||
| + | } | ||
| + | |||
} | } | ||
| + | |||
``` | ``` | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :-------------: | :---: | | | :-------------: | :---: | | ||
| − | |||
| − | ### `onScrollBeginDrag` | + | | دالة (function) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `onScrollBeginDrag` | ||
تُستدعى هذه الدالة عند بدء المستخدم بسحب عرض التمرير. | تُستدعى هذه الدالة عند بدء المستخدم بسحب عرض التمرير. | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :-------------: | :---: | | | :-------------: | :---: | | ||
| − | |||
| − | ### `onScrollEndDrag` | + | | دالة (function) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `onScrollEndDrag` | ||
تُستدعى هذه الدالة عند توقف المستخدم عن سحب عرض التمرير, وكذلك عندما يتوقف عرض التمرير أو يبدأ بالانزلاق. | تُستدعى هذه الدالة عند توقف المستخدم عن سحب عرض التمرير, وكذلك عندما يتوقف عرض التمرير أو يبدأ بالانزلاق. | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :-------------: | :---: | | | :-------------: | :---: | | ||
| − | |||
| − | ### `onScrollToTop` | + | | دالة (function) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `onScrollToTop` | ||
تُطلق عند تمرير عرض التمرير للأعلى بعد أن نُقر شريط الحالة. | تُطلق عند تمرير عرض التمرير للأعلى بعد أن نُقر شريط الحالة. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :-------------: | :---: | :----: | | | :-------------: | :---: | :----: | | ||
| − | |||
| − | ### `overScrollMode` | + | | دالة (function) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `overScrollMode` | ||
تُستخدم لتعديل القيمة الافتراضية لوضع التمرير الإضافي (overScroll), وقيمها: | تُستخدم لتعديل القيمة الافتراضية لوضع التمرير الإضافي (overScroll), وقيمها: | ||
| − | * `auto` (الافتراضية)- تسمح للمستخدم بالتمرير الإضافي لهذا العرض فقط في حال كان حجم المحتوى كبير بشكل كافي لهذا النوع من التمرير. | + | <nowiki>*</nowiki> `auto` (الافتراضية)- تسمح للمستخدم بالتمرير الإضافي لهذا العرض فقط في حال كان حجم المحتوى كبير بشكل كافي لهذا النوع من التمرير. |
| − | * `always` - تسمح دائمًا للمستخدم بالتمرير الإضافي لهذا العرض. | + | |
| − | * `never` - لا تسمح للمستخدم بالتمرير الإضافي لهذا العرض. | + | <nowiki>*</nowiki> `always` - تسمح دائمًا للمستخدم بالتمرير الإضافي لهذا العرض. |
| + | |||
| + | <nowiki>*</nowiki> `never` - لا تسمح للمستخدم بالتمرير الإضافي لهذا العرض. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :------------------------------------------: | :---: | :-----: | | | :------------------------------------------: | :---: | :-----: | | ||
| − | |||
| − | ### `pagingEnabled` | + | | قيمة اسمية (enum('auto', 'always', 'never')) | لا | Android | |
| + | |||
| + | <nowiki>###</nowiki> `pagingEnabled` | ||
عندما تكون قيمة هذه الخاصيّة `true` فإن عرض التمرير يتوقف عند مضاعفات حجم عرض التمرير, حيث يمكن استخدام هذه الخاصيّة من أجل التصفح الأفقي. وقيمتها الافتراضية `false`. | عندما تكون قيمة هذه الخاصيّة `true` فإن عرض التمرير يتوقف عند مضاعفات حجم عرض التمرير, حيث يمكن استخدام هذه الخاصيّة من أجل التصفح الأفقي. وقيمتها الافتراضية `false`. | ||
| − | **ملاحظة:** التصفح العمودي غير مدعوم على منصة Android. | + | <nowiki>**</nowiki>ملاحظة:** التصفح العمودي غير مدعوم على منصة Android. |
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | ### `persistentScrollbar` | + | | قيمة منطقية (bool) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `persistentScrollbar` | ||
لا تسمح لأشرطة التمرير بأن تعود شفافة بعد الانتهاء منها. وقيمتها الافتراضية `false`. | لا تسمح لأشرطة التمرير بأن تعود شفافة بعد الانتهاء منها. وقيمتها الافتراضية `false`. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :----------------: | :---: | :-----: | | | :----------------: | :---: | :-----: | | ||
| − | |||
| − | ### `pinchGestureEnabled` | + | | قيمة منطقية (bool) | لا | Android | |
| + | |||
| + | <nowiki>###</nowiki> `pinchGestureEnabled` | ||
| + | |||
| + | لا تسمح لأشرطة التمرير بأن تعود شفافة بعد الانتهاء منها. وقيمتها الافتراضية `false`. | ||
| − | + | | النوع | مطلوب | المنصة | | |
| − | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | ### `refreshControl` | + | | قيمة منطقية (bool) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `refreshControl` | ||
| − | + | يستخدم هذا المكوّن لتأمين وظيفة التحديث بالسحب (pull-to-refresh) لعرض التمرير, ويعمل مع عرض التمرير العمودي فقط (يجب أن تكون الخاصيّة `horizontal` بالقيمة `false`). ولمزيد من المعلومات حول هذا المكوّن يمكن الإطلاع على [`RefreshControl`](<nowiki>https://reactnative.dev/docs/refreshcontrol</nowiki>). | |
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :------------: | :---: | | | :------------: | :---: | | ||
| − | |||
| − | ### `removeClippedSubviews` | + | | عنصر (element) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `removeClippedSubviews` | ||
| + | |||
| + | <nowiki>**</nowiki>تجريبي:** عندما تكون القيمة `true` فإن عروض المكونات الأبناء (التي تكون فيها الخاصيّة `overflow` بالقيمة `hidden`) التي خارج الشاشة تُزال من العرض الرئيسي (superview), مما يحسّن من أداء التمرير في القوائم الطويلة. | ||
| − | + | | النوع | مطلوب | | |
| − | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | ### `scrollBarThumbImage` | + | | قيمة منطقية (bool) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `scrollBarThumbImage` | ||
يمكن بشكل اختياري استخدام صورة كأيقونة لشريط التمرير, وهذا بدوره يلغي اللون عند وجود الصورة, غير أنه يبقى اللون أثناء تحميل الصورة أو عند فشل التحميل. كما يمكن إلغاء اللون أثناء تحميل الصورة بجعل قيمة المعامل `alpha` الخاص باللون مساوية للصفر. | يمكن بشكل اختياري استخدام صورة كأيقونة لشريط التمرير, وهذا بدوره يلغي اللون عند وجود الصورة, غير أنه يبقى اللون أثناء تحميل الصورة أو عند فشل التحميل. كما يمكن إلغاء اللون أثناء تحميل الصورة بجعل قيمة المعامل `alpha` الخاص باللون مساوية للصفر. | ||
| − | * `uri` - سلسلة نصيّة تمثل معرّف مصدر الصورة, والذي هو عبارة عن مسار الملف المحلي للصورة أو اسم مصدر الصورة الثابت (static). | + | <nowiki>*</nowiki> `uri` - سلسلة نصيّة تمثل معرّف مصدر الصورة, والذي هو عبارة عن مسار الملف المحلي للصورة أو اسم مصدر الصورة الثابت (static). |
| − | * `number` - نوع مبهم (Opaque) معاد من قبل شيء ما مثل `import IMAGE from'./image.jpg'`. | + | |
| + | <nowiki>*</nowiki> `number` - نوع مبهم (Opaque) معاد من قبل شيء ما مثل `import IMAGE from'./image.jpg'`. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :----------: | :---: | :----: | | | :----------: | :---: | :----: | | ||
| − | |||
| − | ### `scrollEnabled` | + | | عدد (number) | لا | VR | |
| + | |||
| + | <nowiki>###</nowiki> `scrollEnabled` | ||
عندما تكون قيمتها `false` فإنه لا يمكن تمرير العرض باللمس. والقيمة الافتراضية `true`. | عندما تكون قيمتها `false` فإنه لا يمكن تمرير العرض باللمس. والقيمة الافتراضية `true`. | ||
| − | **ملاحظة:** يمكن تمرير العرض دائما باستدعاء `scrollTo`. | + | <nowiki>**</nowiki>ملاحظة:** يمكن تمرير العرض دائما باستدعاء `scrollTo`. |
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | + | | قيمة منطقية (bool) | لا | | |
| − | تتحكم بعدد مرات إطلاق أحداث التمرير أثناء التمرير (الفاصل الزمني بالميلي ثانية). وكلما كانت قيمتها أصغر كلما زادت دقة الشفرة البرمجية في تعقّب موقع التمرير, غير أن هذا قد يسبب مشاكل في الأداء بسبب كم المعلومات المرسل عبر الجسر, كما أنه لا يلاحظ الفرق عند تغيير القيم ضمن المجال 1- | + | <nowiki>###</nowiki> `scrollEventThrottle` |
| + | |||
| + | تتحكم بعدد مرات إطلاق أحداث التمرير أثناء التمرير (الفاصل الزمني بالميلي ثانية). وكلما كانت قيمتها أصغر كلما زادت دقة الشفرة البرمجية في تعقّب موقع التمرير, غير أن هذا قد يسبب مشاكل في الأداء بسبب كم المعلومات المرسل عبر الجسر, كما أنه لا يلاحظ الفرق عند تغيير القيم ضمن المجال 1- 16 بسبب تزامن حلقة JS مع معدل تحديث الشاشة. لذا يفضل عند عدم الحاجة للتعقب الدقيق لتعقب التمرير, وضع قيمة كبيرة لهذه الخاصيّة وذلك للتقليل من كمية المعلومات المرسلة عبر الجسر. إن القيمة الافتراضية لهذه الخاصيّة هي الصفر والذي يعني أن حدث التمرير يُرسل مرة واحدة فقط في كل مرة يمرر العرض. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :----------: | :---: | :----: | | | :----------: | :---: | :----: | | ||
| − | |||
| − | + | | عدد (number) | لا | iOS | | |
| − | تحدد مقدار دخول مؤشرات عرض التمرير من أطرافه, وعادة ما تُضبط قيمة هذه الخاصيّة بشكل مماثل لقيمة | + | <nowiki>###</nowiki> `scrollIndicatorInsets` |
| + | |||
| + | تحدد مقدار دخول مؤشرات عرض التمرير من أطرافه, وعادة ما تُضبط قيمة هذه الخاصيّة بشكل مماثل لقيمة للخاصيّة `contentInset`. وقيمتها الافتراضية `{0, 0, 0, 0}`. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :----------------------------------------------------------: | :---: | :----: | | | :----------------------------------------------------------: | :---: | :----: | | ||
| − | |||
| − | + | | كائن (object: {top: number, left: number, bottom: number, right: number}) | لا | iOS | | |
| − | هي عبارة عن وسم (tag) يُستخدم لتسجيل أداء عرض التمرير الحالي, حيث | + | <nowiki>###</nowiki> `scrollEventThrottle` |
| + | |||
| + | هي عبارة عن وسم (tag) يُستخدم لتسجيل أداء عرض التمرير الحالي, حيث يشغل أحداث الزخم (الخاصية `sendMomentumEvents`). هذا ولا تفعل هذه الخاصيّة أي شيء آخر, لذا نحتاج إلى تصميم مُنصت `FpsListener` أصيل للاستفادة من هذه الخاصيّة. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :-----------------: | :---: | :-----: | | | :-----------------: | :---: | :-----: | | ||
| − | |||
| − | ### `scrollToOverflowEnabled` | + | | سلسلة نصية (string) | لا | Android | |
| + | |||
| + | <nowiki>###</nowiki> `scrollToOverflowEnabled` | ||
عندما تكون قيمتها `true` فإنه يمكن برمجيًا تمرير عرض التمرير إلى خارج حدود حجم محتواه. وقيمته الافتراضية `false`. | عندما تكون قيمتها `true` فإنه يمكن برمجيًا تمرير عرض التمرير إلى خارج حدود حجم محتواه. وقيمته الافتراضية `false`. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | + | | قيمة منطقية (bool) | لا | iOS | | |
| − | عندما تكون قيمتها `true` فإن عرض التمرير | + | <nowiki>###</nowiki> `scrollsToTop` |
| + | |||
| + | عندما تكون قيمتها `true` فإن عرض التمرير يمرر للأعلى عند نقر شريط الحالة. وقيمتها الافتراضية `true`. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | + | | قيمة منطقية (bool) | لا | iOS | | |
| − | + | <nowiki>###</nowiki> `sendUpdatedChildFrames` | |
| + | <nowiki>**</nowiki>مهملة:** عندما تكون قيمتها `true` فإن عرض التمرير يرسل بيانات `updateChildFrames` في أحداث التمرير. أوجدت لدعم الإصدارات القديمة, وستُستخدم `onLayout` بدلًا منها لجلب بيانات الإطار. وقيمتها الافتراضية `false`. | ||
| + | |||
| + | | النوع | مطلوب | المنصة | | ||
| − | |||
| :----------------: | :---: | :----: | | | :----------------: | :---: | :----: | | ||
| − | |||
| − | ### `showsHorizontalScrollIndicator` | + | | قيمة منطقية (bool) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `showsHorizontalScrollIndicator` | ||
| + | |||
| + | عندما تكون قيمتها `true` فإنها تظهر مؤشر التمرير الأفقي. وقيمتها الافتراضية `true`. | ||
| − | + | | النوع | مطلوب | | |
| − | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | ### `showsVerticalScrollIndicator` | + | | قيمة منطقية (bool) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `showsVerticalScrollIndicator` | ||
| − | عندما تكون قيمتها `true` فإنها | + | عندما تكون قيمتها `true` فإنها تظهر مؤشر التمرير العمودي. وقيمتها الافتراضية `true`. |
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | ### `snapToAlignment` | + | | قيمة منطقية (bool) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `snapToAlignment` | ||
تحدد هذه الخاصيّة علاقة الانجذاب (snapping) بعرض التمرير في حال كانت الخاصيّة `snapToInterval` مفعّلة. ولها القيم التالية: | تحدد هذه الخاصيّة علاقة الانجذاب (snapping) بعرض التمرير في حال كانت الخاصيّة `snapToInterval` مفعّلة. ولها القيم التالية: | ||
| + | <nowiki>*</nowiki> `start` (الافتراضية)- تحاذي الانجذاب لليسار في التمرير الأفقي, وللأعلى في التمرير العمودي. | ||
| + | |||
| + | <nowiki>*</nowiki> `center` - تحاذي الانجذاب للمنتصف. | ||
| − | * | + | <nowiki>*</nowiki> `end` - تحاذي الانجذاب لليمين في التمرير الأفقي, وللأسفل في التمرير العمودي. |
| − | + | ||
| − | + | | النوع | مطلوب | المنصة | | |
| − | |||
| :-----------------------------------------: | :---: | :----: | | | :-----------------------------------------: | :---: | :----: | | ||
| − | |||
| − | ### `snapToEnd` | + | | قيمة اسمية (enum('start', 'center', 'end')) | لا | iOS | |
| + | |||
| + | <nowiki>###</nowiki> `snapToEnd` | ||
تعمل بالتعاون مع الخاصيّة `snapToOffsets`. حيث تعدّ نهاية القائمة كإزاحة للانجذاب عندما تكون قيمتها `true` (القيمة الافتراضية), ولتعطيل هذا السلوك يجب ضبطها بالقيمة `false` للسماح بالتمرير بحريّة بين نهاية القائمة وآخر إزاحة مضبوطة في الخاصيّة `snapToOffsets`. | تعمل بالتعاون مع الخاصيّة `snapToOffsets`. حيث تعدّ نهاية القائمة كإزاحة للانجذاب عندما تكون قيمتها `true` (القيمة الافتراضية), ولتعطيل هذا السلوك يجب ضبطها بالقيمة `false` للسماح بالتمرير بحريّة بين نهاية القائمة وآخر إزاحة مضبوطة في الخاصيّة `snapToOffsets`. | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | + | | قيمة منطقية (bool) | لا | | |
| − | تسمح هذه الخاصيّة بإيقاف عرض التمرير على مضاعفات قيمتها, لذا تُستخدم للتصفح عبر المكونات الأبناء التي طولها أصغر من عرض التمرير. وتُستخدم نموذجيًا مع الخاصيتين `snapToAlignment` و `decelerationRate="fast"`, وتلغي الخاصيّة `pagingEnabled` الأقل قابلية للضبط. | + | <nowiki>###</nowiki> `snapToInterval` |
| + | |||
| + | تسمح هذه الخاصيّة بإيقاف عرض التمرير على مضاعفات قيمتها, لذا تُستخدم للتصفح عبر المكونات الأبناء التي طولها أصغر من عرض التمرير. وتُستخدم نموذجيًا مع الخاصيتين `snapToAlignment` و `decelerationRate="fast"`, وتلغي الخاصيّة `pagingEnabled` الأقل قابلية للضبط. | ||
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :----------: | :---: | | | :----------: | :---: | | ||
| − | |||
| − | + | | عدد (number) | لا | | |
| − | تعمل هذه الخاصيّة على إيقاف عرض التمرير على الإزاحات المحددة, لذا تُستخدم للتصفح عبر المكونات الأبناء مختلفة الأحجام والتي طولها أصغر من عرض التمرير. وتُستخدم نموذجيًا مع | + | <nowiki>###</nowiki> `snapToOffsets` |
| + | |||
| + | تعمل هذه الخاصيّة على إيقاف عرض التمرير على الإزاحات المحددة, لذا تُستخدم للتصفح عبر المكونات الأبناء مختلفة الأحجام والتي طولها أصغر من عرض التمرير. وتُستخدم نموذجيًا مع الخاصيّة `decelerationRate="fast"`, وتلغي الخاصيتين `pagingEnabled` و `snapToInterval` الأقل قابلية للضبط. | ||
| + | |||
| + | | النوع | مطلوب | | ||
| − | |||
| :----------------------------: | :---: | | | :----------------------------: | :---: | | ||
| − | |||
| − | ### `snapToStart` | + | | مصفوفة عددية (array of number) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `snapToStart` | ||
تعمل بالتعاون مع الخاصيّة `snapToOffsets`. حيث تعدّ بداية القائمة كإزاحة للانجذاب عندما تكون قيمتها `true` (القيمة الافتراضية), ولتعطيل هذا السلوك يجب ضبطها بالقيمة `false` للسماح بالتمرير بحريّة بين بداية القائمة وأول إزاحة مضبوطة في الخاصيّة `snapToOffsets`. | تعمل بالتعاون مع الخاصيّة `snapToOffsets`. حيث تعدّ بداية القائمة كإزاحة للانجذاب عندما تكون قيمتها `true` (القيمة الافتراضية), ولتعطيل هذا السلوك يجب ضبطها بالقيمة `false` للسماح بالتمرير بحريّة بين بداية القائمة وأول إزاحة مضبوطة في الخاصيّة `snapToOffsets`. | ||
| − | | | + | | النوع | مطلوب | |
| + | |||
| :----------------: | :---: | | | :----------------: | :---: | | ||
| − | |||
| − | ### `stickyHeaderIndices` | + | | قيمة منطقية (bool) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `stickyHeaderIndices` | ||
| + | |||
| + | عبارة عن مصفوفة من أدلة المكونات الأبناء التي ستثبَّت بأعلى الشاشة عند التمرير, حيث يؤدي تمرير القيمة `stickyHeaderIndices={[0]}` إلى تثبيت الابن الأول بأعلى عرض التمرير. كما يمكن استخدام الإحداثيات `[x,y,z]` لجعل عدة عناصر دبقة (sticky) عند وصولها لأعلى الشاشة. لا تعمل هذه الخاصيّة مع الخاصيّة `horizontal={true}`. | ||
| − | + | | النوع | مطلوب | | |
| − | |||
| :----------------------------: | :---: | | | :----------------------------: | :---: | | ||
| − | |||
| − | ### `zoomScale` | + | | مصفوفة عددية (array of number) | لا | |
| + | |||
| + | <nowiki>###</nowiki> `zoomScale` | ||
تحدد مقياس الرسم لعرض التمرير الحالي, وقيمتها الافتراضية `1`. | تحدد مقياس الرسم لعرض التمرير الحالي, وقيمتها الافتراضية `1`. | ||
| − | | | + | | النوع | مطلوب | المنصة | |
| + | |||
| :----------: | :---: | :----: | | | :----------: | :---: | :----: | | ||
| − | |||
| − | + | | عدد (number) | لا | iOS | | |
| + | |||
| + | <nowiki>##</nowiki> التوابع (Methods) | ||
| − | ### `flashScrollIndicators()` | + | <nowiki>###</nowiki> `flashScrollIndicators()` |
```Javascript | ```Javascript | ||
| + | |||
flashScrollIndicators(); | flashScrollIndicators(); | ||
| + | |||
``` | ``` | ||
يُظهر مؤشرات التمرير لحظيًا. | يُظهر مؤشرات التمرير لحظيًا. | ||
| − | ### `scrollTo()` | + | <nowiki>###</nowiki> `scrollTo()` |
```Javascript | ```Javascript | ||
| + | |||
scrollTo( | scrollTo( | ||
| − | + | ||
| − | + | options?: {x?: number, y?: number, animated?: boolean} | number, | |
| − | + | ||
| + | deprecatedX?: number, | ||
| + | |||
| + | deprecatedAnimated?: boolean, | ||
| + | |||
); | ); | ||
| + | |||
``` | ``` | ||
يمرر نحو الإزاحة المعطاة (x,y) بحركة سريعة أو سلسة. | يمرر نحو الإزاحة المعطاة (x,y) بحركة سريعة أو سلسة. | ||
| − | **مثال:** | + | <nowiki>**</nowiki>مثال:** |
``` | ``` | ||
| + | |||
scrollTo({x: 0, y: 0, animated: true}) | scrollTo({x: 0, y: 0, animated: true}) | ||
| + | |||
``` | ``` | ||
| − | **ملاحظة:** لهذا التابع توقيع (signature) غريب لكونه صُمم لدعم المنصات القديمة, حيث يقبل معاملات منفصلة كبديل عن كائن الخيارات, لذا فإن هذا الكائن مهمل لمنع الالتباس. | + | <nowiki>**</nowiki>ملاحظة:** لهذا التابع توقيع (signature) غريب لكونه صُمم لدعم المنصات القديمة, حيث يقبل معاملات منفصلة كبديل عن كائن الخيارات, لذا فإن هذا الكائن مهمل لمنع الالتباس. |
| − | ### `scrollToEnd()` | + | <nowiki>###</nowiki> `scrollToEnd()` |
```Javascript | ```Javascript | ||
| + | |||
scrollToEnd(([options]: { animated: boolean, duration: number })); | scrollToEnd(([options]: { animated: boolean, duration: number })); | ||
| + | |||
``` | ``` | ||
| − | يمرر للأسفل في حال كان عرض التمرير عموديًا, ويمرر لليمين في حال كان عرض التمرير أفقيًا. وله الخيار `scrollToEnd({animated: true})` من أجل التمرير السلس وهو الإفتراضي, والخيار `scrollToEnd({animated: false})` من أجل التمرير السريع. كما | + | يمرر للأسفل في حال كان عرض التمرير عموديًا, ويمرر لليمين في حال كان عرض التمرير أفقيًا. وله الخيار `scrollToEnd({animated: true})` من أجل التمرير السلس وهو الإفتراضي, والخيار `scrollToEnd({animated: false})` من أجل التمرير السريع. كما يمكن على منصة إضافة المدة الزمنية للتمرير `scrollToEnd({duration: 500})`. في حال عدم تمرير أي خيار لهذا لتابع فإن القيمة الافتراضية للخيار `animated` هي `true`. |
| − | ### `scrollWithoutAnimationTo()` | + | <nowiki>###</nowiki> `scrollWithoutAnimationTo()` |
```Javascript | ```Javascript | ||
| + | |||
scrollWithoutAnimationTo(y, x); | scrollWithoutAnimationTo(y, x); | ||
| + | |||
``` | ``` | ||
| − | **مهمل:** استخدم التابع `scrollTo` بدلا منه. | + | <nowiki>**</nowiki>مهمل:** استخدم التابع `scrollTo` بدلا منه. |
| + | |||
| + | <nowiki>##</nowiki> مصادر | ||
| − | + | <nowiki>*</nowiki> [صفحة scrollView في توثيق React Native الرسمي.](<nowiki>https://facebook.github.io/react-native/docs/scrollview</nowiki>) | |
| − | * | + | * |
مراجعة 22:33، 5 ديسمبر 2020
# ScrollView
هو عبارة عن مكوّن يغلّف المنصة ScrollView لتأمين التكامل مع منظومة مستجيب "responder" تعليق اللمس (touch locking).
يجب أن يكون ارتفاع المكوّن ScrollView محدد (bounded) لكي يعمل, كونه سيضم مكونات أبناء غير محددة الارتفاع إلى حاوية محددة الارتفاع أثناء التمرير (scroll). وذلك بضبط ارتفاع العرض مباشرة بالخيار discouraged أو بالتأكد من أنه لجميع العروض الآباء ارتفاع محدد. يؤدي نسيان ضبط الالتفاف أسفل العرض على القيمة `{flex: 1}` إلى حدوث خطأ, يسارع مراقب (inspector) العناصر إلى تصحيحه (debug).
لا يدعم هذا المكون حتى الآن المستجيبات المتضمنة الأخرى لتعلّق عرض التمرير هذا.
**متى يُستخدم المكوّن [`FlatList`](https://reactnative.dev/docs/flatlist) بدل المكوّن `<ScrollView>`:**
يعرض المكوّن `ScrollView` جميع مكونات react الأبناء دفعة واحدة, مما يؤثر سلبًا على الأداء عند عرض القوائم الطويلة التي تتطلب إنشاء الكثير من مكونات JS والعروض الأصيلة (native) ليتم إظهارها دفعة واحدة, وهذا بدوره يبطئ العملية الإظهار ويستهلك الكثير من الذاكرة.
في هذه الحالة يفضَّل استخدام المكون `FlatList` الذي لا يعرض المكونات المراد إظهارها إلا عند الوصول إليها, كما يقوم بإزالتها عند الانتهاء منها مما يوفر من قدرة المعالجة والذاكرة المستخدمة. كما يستخدم هذا المكوّن عند الحاجة لإظهار فاصل بين العناصر أو بين الأعمدة المتعددة, أو لتمرير القوائم متناهية الطول وغيرها من الميزات الغير متوفرة في `ScrollView`.
## مثال
```javascript
import React from 'react';
import { StyleSheet, Text, SafeAreaView, ScrollView } from 'react-native';
import Constants from 'expo-constants';
const App = () => {
return (
<SafeAreaView style={styles.container}>
<ScrollView style={styles.scrollView}>
<Text style={styles.text}>
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut
aliquip ex ea commodo consequat. Duis aute irure dolor in
reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
</Text>
</ScrollView>
</SafeAreaView>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
marginTop: Constants.statusBarHeight,
},
scrollView: {
backgroundColor: 'pink',
marginHorizontal: 20,
},
text: {
fontSize: 42,
},
});
export default App;
```
## الخاصيّات (Props)
موروثة من الخاصيّات [`View Props`](https://reactnative.dev/docs/view#props).
### `alwaysBounceHorizontal`
قيمتها الافتراضية `horizontal={true}` حيث تجعل عرض التمرير يرتد (bounce) أفقيًا عند وصوله للنهاية حتى ولو كان المحتوى أصغر من عرض التمرير نفسه.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `alwaysBounceVertical`
قيمتها الافتراضية `vertical={true}` حيث تجعل عرض التمرير يرتد (bounce) عموديًا عند وصوله للنهاية حتى ولو كان المحتوى أصغر من عرض التمرير نفسه.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `automaticallyAdjustContentInset`
تجعل منصّة iOS تتحكم آليًا بإدخال (inset) المحتوى من أجل عروض التمرير المتواجدة خلف شريط التنقل أو شريط الأدوات. وقيمتها الافتراضية `true`.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `bounces`
قيمتها الافتراضية `true` حيث تجعل عرض التمرير يرتد عند وصوله لنهاية المحتوى إن كان أكبر من عرض التمرير وفق محور التمرير. أما في حال كانت قيمتها `false` فإنها تلغي جميع أنواع الارتداد حتى لو كانت الخاصيات `alwaysBounce*` مفعّلة.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `bouncesZoom`
قيمتها الافتراضية `true` حيث تتيح استخدام الإيماءات (gestures) في تجاوز الحد الأدنى والأقصى للتكبير, ويعود التكبير إلى حدوده الافتراضية بعد انتهاء الإيماءة.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `canCancelContentTouches`
إذا كانت قيمتها `false` فإنها تمنع اللمسة المتحركة من السحب (drag). وقيمتها الافتراضية `true`.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `centerContent`
إذا كانت قيمتها `true` فإنها تضع المحتوى آليًا في منتصف عرض التمرير إن كان المحتوى أصغر من حدود عرض التمرير, أما إن كان المحتوى أكبر من عرض التمرير فلا تأثير لهذه الخاصيّة. وقيمتها الافتراضية `false`.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `contentContainerStyle`
وهي مجموعة من التنسيقات المطبّقة على محتوى عرض التمرير, والتي تغلف جميع عروض المكونات الأبناء.
**مثال:**
```
return (
<ScrollView contentContainerStyle={styles.contentContainer}>
</ScrollView>
);
...
const styles = StyleSheet.create({
contentContainer: {
paddingVertical: 20
}
});
```
| النوع | مطلوب |
| :-------------------------------------------: | :---: |
| تنسيقات StyleSheetPropType(View Style props) | لا |
### `contentInset`
تحدد مقدار دخول المحتوى من حواف عرض التمرير, وقمتها الافتراضية `{top: 0, left: 0, bottom: 0, right: 0}`.
| النوع | مطلوب | المنصة |
| :----------------------------------------------------------: | :---: | :----: |
| كائن (object: {top: number, left: number, bottom: number, right: number}) | لا | iOS |
### `contentInsetAdjustmentBehavior`
تحدد هذه الخاصيّة طريقة استخدام منطقة الإدخال لتعديل منطقة المحتوى في عرض التمرير. والقيمة الافتراضية لها `never`, ومتوفرة فقط على منصة iOS إصدار 11 وما فوق.
| النوع | مطلوب | المنصة |
| :----------------------------------------------------------: | :---: | :----: |
| قيمة اسمية (enum('automatic', 'scrollableAxes', 'never', 'always')) | لا | iOS |
### `contentOffset`
تُستخدم لتحديد إزاحة بداية التمرير يدويًا, والقيمة الافتراضية لها `{x: 0, y: 0}`.
| النوع | مطلوب | المنصة |
| :-----------: | :---: | :----: |
| PointPropType | لا | iOS |
### `decelerationRate`
عبارة عن عدد عشري يحدد معدل تباطؤ التمرير بعد رفع الإصبع عن عرض التمرير, كما يمكن استخدام اختصارات السلاسل النصية `normal` و `fast` والتي تقابل الإعدادات `UIScrollViewDecelerationRateNormal` و `UIScrollViewDecelerationRateFast` على منصة iOS.
* `normal` (الافتراضية)- وتوافق القيمة 0.998 على منصة iOS والقيمة 0.985 على منصة Android.
* `fast` - وتوافق القيمة 0.99 على منصة iOS والقيمة 0.9 على منصة Android.
| النوع | مطلوب |
| :---------------------------------------------: | :---: |
| قيمة اسمية, عدد (enum('fast', 'normal'),number) | لا |
### `directionalLockEnabled`
إذا كانت قيمتها `true` فإنها تسمح بالتمرير فقط وفق الاتجاه العمودي أو الأفقي أثناء السحب. وقيمتها الافتراضية `false`.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `disableIntervalMomentum`
إذا كانت قيمتها `true` فإنها توقف عرض التمرير على الدليل (index) التالي (المتعلق بموقع التمرير عند التحرير) بغض النظر عن سرعة الإيماءة. ويمكن أن تستخدم للتصفح الأفقي عندما يكون عرض الصفحة أصغر من عرض ScrollView. وقيمتها الافتراضية `false`.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `disableScrollViewPanResponder`
إذا كانت قيمتها `true` فإنها تلغي عمل المكون [`PanResponder`](https://wiki.hsoub.com/ReactNative/panresponder) الافتراضي لعرض التمرير, ويُترك التحكم الكامل للمسات داخل عرض التمرير للمكونات الأبناء. وهذا مفيد عمليًا عندما تكون الخاصيّة `snapToInterval` مفعّلة كونها لا تتبع أنمط اللمسات النموذجية. يجب تجنب هذه الخاصيّة في الاستخدامات الاعتيادية لعرض التمرير من دون الخاصيّة `snapToInterval`, لأنها قد تسبب حدوث لمسات غير متوقعة أثناء التمرير. وقيمتها الافتراضية `false`.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `endFillColor`
تُستخدم هذه الخاصية لملء الفراغ المتبقي في عرض التمرير والذي يحدث أحيانا نتيجة أخذ عرض التمرير لحيز أكبر من الذي يشغله المحتوى, حيث تسمح هذه الخاصية بتجنب إعداد الخلفية. وتعد هذه الخاصيّة من التحسينات المتقدمة والتي لا تُستخدم في الحالات الاعتيادية.
| النوع | مطلوب | المنصة |
| :--------------------------------------------------: | :---: | :-----: |
| لون ([`color`](https://reactnative.dev/docs/colors)) | لا | Android |
### `fadingEdgeLength`
تُستخدم لتلاشي (Fade) حواف المحتوى الممرر. فإذا كانت قيمتها أكبر من الصفر, فإن تلاشي الحواف سيكون وفقا لاتجاه ومكان التمرير الحالي للدلالة فيما إذا كان هنالك مزيدًا من المحتوى لإظهاره.
| النوع | مطلوب | القيمة الافتراضية | المنصة |
| :----------: | :---: | :---------------: | :-----: |
| عدد (number) | لا | 0 | Android |
### `horizontal`
إذا كانت قيمتها `true` فإن المكونات الأبناء لعرض التمرير ستصطف أفقيًا في سطر بدل الاصطفاف عموديًا في عمود, وقيمتها الافتراضية `false`.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `indicatorStyle`
تُستخدم لتنسيق مؤشر التمرير, وقيمها:
* `default` (الافتراضية)- نفس `black`.
* `black` - يكون المؤشر أسود ويستخدم مع الخلفيات الفاتحة.
* `white` - يكون المؤشر أبيض ويستخدم مع الخلفيات الداكنة.
| النوع | مطلوب | المنصة |
| :--------------------------------------------: | :---: | :----: |
| قيمة اسمية (enum('default', 'black', 'white')) | لا | iOS |
### `invertStickyHeaders`
تجعل هذه الخاصية الترويسات الدبقة (sticky headers) تلتصق في أسفل عرض التمرير بدل الالتصاق في الأعلى, وعادة ما تستخدم مع عرض التمرير المقلوب.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `keyboardDismissMode`
تُستخدم لإبطال لوحة المفاتيح أثناء السحب, وقيمها:
على المنصات المتعددة (Cross platform):
* `none` (الافتراضية)- لا يبطل السحب لوحة المفاتيح.
* `on-drag` - تبطل لوحة المفاتيح عند بدء السحب.
على منصّة iOS:
* `interactive` - تبطل لوحة المفاتيح تفاعليًا مع السحب والحركات بالتزامن مع اللمس, وتفعّل بالسحب للأعلى. وهذه الخاصيّة غير مفعّلة على منصّة وتبقى كما لو أن قيمتها `none`.
| النوع | مطلوب |
| :---------------------------------------------: | :---: |
| قيمة اسمية (enum('none', 'on-drag', 'interactive')) | لا |
### `keyboardShouldPersistTaps`
تحدد فيما إذا كانت لوحة المفاتيح ستبقى ظاهرة بعد النقر (tap), وقيمها:
* `never` (الافتراضية)- إن النقر خارج إطار النص المركّز ولوحة المفاتيح مرفوعة, يؤدي إلى إبطالها. ولن تستقبل المكونات الأبناء لعرض التمرير النقر عند حدوث ذلك.
* `always` - لا تبطل لوحة المفاتيح تلقائيًا, ولن يستقبل عرض التمرير النقر لكن المكونات الأبناء تستطيع استقباله.
* `handled` - لا تبطل لوحة المفاتيح تلقائيًا عند معالجة النقر من قبل المكونات الأبناء لعرض التمرير (أو عند استقباله من قبل المكونات الأجداد).
* `false` (مهملة)- استخدم `never` بدلًا منها.
* `true` (مهملة)- استخدم `always` بدلًا منها.
| النوع | مطلوب |
| :----------------------------------------------------------: | :---: |
| قيمة اسمية (enum('always', 'never', 'handled', false, true)) | لا |
### `maintainVisibleContentPosition`
عند استخدام هذه الخاصيّة, فإن عرض التمرير يضبط موقع التمرير بحيث لا يتغير موقع المكون الابن الأول والظاهر حاليًا (عند القيمة `minIndexForVisible` أو ما بعدها). وهذا مفيد مع القوائم التي تحمّل المحتوى من كلا الاتجاهين كما هي الحال في الدردشة, حيث تمنع هذه الخاصية الرسائل الجديدة الواردة من إزاحة موقع التمرير. القيمة الاعتيادية لهذه الخاصية هي `0`, غير أنه يمكن استخدام قيم أخرى مثل `1` من أجل تجاهل تحميل المحتوى الذي قد يغيّر موقع التمرير.
يمكن استخدام القيمة الاختيارية `autoscrollToTopThreshold` لتمرير المحتوى تلقائيا للأعلى بعد ضبط موقع التمرير في حال كان المستخدم ضمن العتبة العليا قبل الضبط. وهذا مفيد في تطبيقات الدردشة من أجل رؤية الرسائل الجديدة الواردة بشكل تلقائي دون الحاجة للتمرير, في حال قام المستخدم بالتمرير بعيدًا عنها.
**تنبيه 1:** قد يؤدي إعادة ترتيب عناصر scrollview مع تمكين هذه الخاصيّة إلى حدوث تقفّز (jumpiness). ولا يوجد نيّة حاليًا لإصلاح هذا الخلل, لذا يجب حاليًا تجنّب إعادة ترتيب محتوى أي مكوّن scrollview أو Lists يستخدم هذه الخاصيّة.
**تنبيه 2:** تستخدم هذه الخاصيّة الخاصيتين `contentOffset` و `frame.origin` في الشفرة الأصيلة لحساب قدرة الإظهار (visibility). كما أنه لم يؤخذ في الاعتبار التحويلات وتعقيدات الإظهار الأخرى.
| النوع | مطلوب | المنصة |
| :----------------------------------------------------------: | :---: | :----: |
| كائن (object: { minIndexForVisible: number, autoscrollToTopThreshold: number }) | لا | iOS |
### `maximumZoomScale`
تحدد مقياس الرسم (scale) الأعظمي للتكبير. قيمتها الافتراضية 1.
| النوع | مطلوب | المنصة |
| :----------: | :---: | :----: |
| عدد (number) | لا | iOS |
### `minimumZoomScale`
تحدد مقياس الرسم (scale) الأصغري للتكبير. قيمتها الافتراضية 1.
| النوع | مطلوب | المنصة |
| :----------: | :---: | :----: |
| عدد (number) | لا | iOS |
### `nestedScrollEnabled`
تمكّن من التمرير المتداخل (nested), ومدعومة على واجهات منصة Android البرمجية من المستوى 21+. كما أنها مدعومة افتراضيًا على منصّة iOS.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :-----: |
| قيمة منطقية (bool) | لا | Android |
### `onContentSizeChange`
تُستدعى هذه الدالة عند تغيّر المحتوى الممرر في ScrollView, حيث يمرر لهذه الدالة عرض وارتفاع المحتوى على شكل معاملين: `contentWidth` و `contentHeight`.
صُممت هذه الدالة باستخدام المعالج `onLayout` والمرتبط بحاوية المحتوى الذي يظهره ScrollView.
| النوع | مطلوب |
| :-------------: | :---: |
| دالة (function) | لا |
### `onMomentumScrollBegin`
تُستدعى هذه الدالة عند بدء زخم (momentum) التمرير (حين يبدأ ScrollView بالانزلاق).
| النوع | مطلوب |
| :-------------: | :---: |
| دالة (function) | لا |
### `onMomentumScrollEnd`
تُستدعى هذه الدالة عند انتهاء زخم التمرير(حين يتوقف ScrollView عن الانزلاق).
| النوع | مطلوب |
| :-------------: | :---: |
| دالة (function) | لا |
### `onScroll`
تُطلق مرة واحدة على الأكثر لكل إطار (frame) أثناء التمرير. ويمكن التحكم بتردد الأحداث عن طريق الخاصيّة `scrollEventThrottle`, ولهذه الأحداث الشكل التالي (جميع القيم أعداد):
```
{
nativeEvent: {
contentInset: {bottom, left, right, top},
contentOffset: {x, y},
contentSize: {height, width},
layoutMeasurement: {height, width},
zoomScale
}
}
```
| النوع | مطلوب |
| :-------------: | :---: |
| دالة (function) | لا |
### `onScrollBeginDrag`
تُستدعى هذه الدالة عند بدء المستخدم بسحب عرض التمرير.
| النوع | مطلوب |
| :-------------: | :---: |
| دالة (function) | لا |
### `onScrollEndDrag`
تُستدعى هذه الدالة عند توقف المستخدم عن سحب عرض التمرير, وكذلك عندما يتوقف عرض التمرير أو يبدأ بالانزلاق.
| النوع | مطلوب |
| :-------------: | :---: |
| دالة (function) | لا |
### `onScrollToTop`
تُطلق عند تمرير عرض التمرير للأعلى بعد أن نُقر شريط الحالة.
| النوع | مطلوب | المنصة |
| :-------------: | :---: | :----: |
| دالة (function) | لا | iOS |
### `overScrollMode`
تُستخدم لتعديل القيمة الافتراضية لوضع التمرير الإضافي (overScroll), وقيمها:
* `auto` (الافتراضية)- تسمح للمستخدم بالتمرير الإضافي لهذا العرض فقط في حال كان حجم المحتوى كبير بشكل كافي لهذا النوع من التمرير.
* `always` - تسمح دائمًا للمستخدم بالتمرير الإضافي لهذا العرض.
* `never` - لا تسمح للمستخدم بالتمرير الإضافي لهذا العرض.
| النوع | مطلوب | المنصة |
| :------------------------------------------: | :---: | :-----: |
| قيمة اسمية (enum('auto', 'always', 'never')) | لا | Android |
### `pagingEnabled`
عندما تكون قيمة هذه الخاصيّة `true` فإن عرض التمرير يتوقف عند مضاعفات حجم عرض التمرير, حيث يمكن استخدام هذه الخاصيّة من أجل التصفح الأفقي. وقيمتها الافتراضية `false`.
**ملاحظة:** التصفح العمودي غير مدعوم على منصة Android.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `persistentScrollbar`
لا تسمح لأشرطة التمرير بأن تعود شفافة بعد الانتهاء منها. وقيمتها الافتراضية `false`.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :-----: |
| قيمة منطقية (bool) | لا | Android |
### `pinchGestureEnabled`
لا تسمح لأشرطة التمرير بأن تعود شفافة بعد الانتهاء منها. وقيمتها الافتراضية `false`.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `refreshControl`
يستخدم هذا المكوّن لتأمين وظيفة التحديث بالسحب (pull-to-refresh) لعرض التمرير, ويعمل مع عرض التمرير العمودي فقط (يجب أن تكون الخاصيّة `horizontal` بالقيمة `false`). ولمزيد من المعلومات حول هذا المكوّن يمكن الإطلاع على [`RefreshControl`](https://reactnative.dev/docs/refreshcontrol).
| النوع | مطلوب |
| :------------: | :---: |
| عنصر (element) | لا |
### `removeClippedSubviews`
**تجريبي:** عندما تكون القيمة `true` فإن عروض المكونات الأبناء (التي تكون فيها الخاصيّة `overflow` بالقيمة `hidden`) التي خارج الشاشة تُزال من العرض الرئيسي (superview), مما يحسّن من أداء التمرير في القوائم الطويلة.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `scrollBarThumbImage`
يمكن بشكل اختياري استخدام صورة كأيقونة لشريط التمرير, وهذا بدوره يلغي اللون عند وجود الصورة, غير أنه يبقى اللون أثناء تحميل الصورة أو عند فشل التحميل. كما يمكن إلغاء اللون أثناء تحميل الصورة بجعل قيمة المعامل `alpha` الخاص باللون مساوية للصفر.
* `uri` - سلسلة نصيّة تمثل معرّف مصدر الصورة, والذي هو عبارة عن مسار الملف المحلي للصورة أو اسم مصدر الصورة الثابت (static).
* `number` - نوع مبهم (Opaque) معاد من قبل شيء ما مثل `import IMAGE from'./image.jpg'`.
| النوع | مطلوب | المنصة |
| :----------: | :---: | :----: |
| عدد (number) | لا | VR |
### `scrollEnabled`
عندما تكون قيمتها `false` فإنه لا يمكن تمرير العرض باللمس. والقيمة الافتراضية `true`.
**ملاحظة:** يمكن تمرير العرض دائما باستدعاء `scrollTo`.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `scrollEventThrottle`
تتحكم بعدد مرات إطلاق أحداث التمرير أثناء التمرير (الفاصل الزمني بالميلي ثانية). وكلما كانت قيمتها أصغر كلما زادت دقة الشفرة البرمجية في تعقّب موقع التمرير, غير أن هذا قد يسبب مشاكل في الأداء بسبب كم المعلومات المرسل عبر الجسر, كما أنه لا يلاحظ الفرق عند تغيير القيم ضمن المجال 1- 16 بسبب تزامن حلقة JS مع معدل تحديث الشاشة. لذا يفضل عند عدم الحاجة للتعقب الدقيق لتعقب التمرير, وضع قيمة كبيرة لهذه الخاصيّة وذلك للتقليل من كمية المعلومات المرسلة عبر الجسر. إن القيمة الافتراضية لهذه الخاصيّة هي الصفر والذي يعني أن حدث التمرير يُرسل مرة واحدة فقط في كل مرة يمرر العرض.
| النوع | مطلوب | المنصة |
| :----------: | :---: | :----: |
| عدد (number) | لا | iOS |
### `scrollIndicatorInsets`
تحدد مقدار دخول مؤشرات عرض التمرير من أطرافه, وعادة ما تُضبط قيمة هذه الخاصيّة بشكل مماثل لقيمة للخاصيّة `contentInset`. وقيمتها الافتراضية `{0, 0, 0, 0}`.
| النوع | مطلوب | المنصة |
| :----------------------------------------------------------: | :---: | :----: |
| كائن (object: {top: number, left: number, bottom: number, right: number}) | لا | iOS |
### `scrollEventThrottle`
هي عبارة عن وسم (tag) يُستخدم لتسجيل أداء عرض التمرير الحالي, حيث يشغل أحداث الزخم (الخاصية `sendMomentumEvents`). هذا ولا تفعل هذه الخاصيّة أي شيء آخر, لذا نحتاج إلى تصميم مُنصت `FpsListener` أصيل للاستفادة من هذه الخاصيّة.
| النوع | مطلوب | المنصة |
| :-----------------: | :---: | :-----: |
| سلسلة نصية (string) | لا | Android |
### `scrollToOverflowEnabled`
عندما تكون قيمتها `true` فإنه يمكن برمجيًا تمرير عرض التمرير إلى خارج حدود حجم محتواه. وقيمته الافتراضية `false`.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `scrollsToTop`
عندما تكون قيمتها `true` فإن عرض التمرير يمرر للأعلى عند نقر شريط الحالة. وقيمتها الافتراضية `true`.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `sendUpdatedChildFrames`
**مهملة:** عندما تكون قيمتها `true` فإن عرض التمرير يرسل بيانات `updateChildFrames` في أحداث التمرير. أوجدت لدعم الإصدارات القديمة, وستُستخدم `onLayout` بدلًا منها لجلب بيانات الإطار. وقيمتها الافتراضية `false`.
| النوع | مطلوب | المنصة |
| :----------------: | :---: | :----: |
| قيمة منطقية (bool) | لا | iOS |
### `showsHorizontalScrollIndicator`
عندما تكون قيمتها `true` فإنها تظهر مؤشر التمرير الأفقي. وقيمتها الافتراضية `true`.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `showsVerticalScrollIndicator`
عندما تكون قيمتها `true` فإنها تظهر مؤشر التمرير العمودي. وقيمتها الافتراضية `true`.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `snapToAlignment`
تحدد هذه الخاصيّة علاقة الانجذاب (snapping) بعرض التمرير في حال كانت الخاصيّة `snapToInterval` مفعّلة. ولها القيم التالية:
* `start` (الافتراضية)- تحاذي الانجذاب لليسار في التمرير الأفقي, وللأعلى في التمرير العمودي.
* `center` - تحاذي الانجذاب للمنتصف.
* `end` - تحاذي الانجذاب لليمين في التمرير الأفقي, وللأسفل في التمرير العمودي.
| النوع | مطلوب | المنصة |
| :-----------------------------------------: | :---: | :----: |
| قيمة اسمية (enum('start', 'center', 'end')) | لا | iOS |
### `snapToEnd`
تعمل بالتعاون مع الخاصيّة `snapToOffsets`. حيث تعدّ نهاية القائمة كإزاحة للانجذاب عندما تكون قيمتها `true` (القيمة الافتراضية), ولتعطيل هذا السلوك يجب ضبطها بالقيمة `false` للسماح بالتمرير بحريّة بين نهاية القائمة وآخر إزاحة مضبوطة في الخاصيّة `snapToOffsets`.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `snapToInterval`
تسمح هذه الخاصيّة بإيقاف عرض التمرير على مضاعفات قيمتها, لذا تُستخدم للتصفح عبر المكونات الأبناء التي طولها أصغر من عرض التمرير. وتُستخدم نموذجيًا مع الخاصيتين `snapToAlignment` و `decelerationRate="fast"`, وتلغي الخاصيّة `pagingEnabled` الأقل قابلية للضبط.
| النوع | مطلوب |
| :----------: | :---: |
| عدد (number) | لا |
### `snapToOffsets`
تعمل هذه الخاصيّة على إيقاف عرض التمرير على الإزاحات المحددة, لذا تُستخدم للتصفح عبر المكونات الأبناء مختلفة الأحجام والتي طولها أصغر من عرض التمرير. وتُستخدم نموذجيًا مع الخاصيّة `decelerationRate="fast"`, وتلغي الخاصيتين `pagingEnabled` و `snapToInterval` الأقل قابلية للضبط.
| النوع | مطلوب |
| :----------------------------: | :---: |
| مصفوفة عددية (array of number) | لا |
### `snapToStart`
تعمل بالتعاون مع الخاصيّة `snapToOffsets`. حيث تعدّ بداية القائمة كإزاحة للانجذاب عندما تكون قيمتها `true` (القيمة الافتراضية), ولتعطيل هذا السلوك يجب ضبطها بالقيمة `false` للسماح بالتمرير بحريّة بين بداية القائمة وأول إزاحة مضبوطة في الخاصيّة `snapToOffsets`.
| النوع | مطلوب |
| :----------------: | :---: |
| قيمة منطقية (bool) | لا |
### `stickyHeaderIndices`
عبارة عن مصفوفة من أدلة المكونات الأبناء التي ستثبَّت بأعلى الشاشة عند التمرير, حيث يؤدي تمرير القيمة `stickyHeaderIndices={[0]}` إلى تثبيت الابن الأول بأعلى عرض التمرير. كما يمكن استخدام الإحداثيات `[x,y,z]` لجعل عدة عناصر دبقة (sticky) عند وصولها لأعلى الشاشة. لا تعمل هذه الخاصيّة مع الخاصيّة `horizontal={true}`.
| النوع | مطلوب |
| :----------------------------: | :---: |
| مصفوفة عددية (array of number) | لا |
### `zoomScale`
تحدد مقياس الرسم لعرض التمرير الحالي, وقيمتها الافتراضية `1`.
| النوع | مطلوب | المنصة |
| :----------: | :---: | :----: |
| عدد (number) | لا | iOS |
## التوابع (Methods)
### `flashScrollIndicators()`
```Javascript
flashScrollIndicators();
```
يُظهر مؤشرات التمرير لحظيًا.
### `scrollTo()`
```Javascript
scrollTo(
options?: {x?: number, y?: number, animated?: boolean} | number,
deprecatedX?: number,
deprecatedAnimated?: boolean,
);
```
يمرر نحو الإزاحة المعطاة (x,y) بحركة سريعة أو سلسة.
**مثال:**
```
scrollTo({x: 0, y: 0, animated: true})
```
**ملاحظة:** لهذا التابع توقيع (signature) غريب لكونه صُمم لدعم المنصات القديمة, حيث يقبل معاملات منفصلة كبديل عن كائن الخيارات, لذا فإن هذا الكائن مهمل لمنع الالتباس.
### `scrollToEnd()`
```Javascript
scrollToEnd(([options]: { animated: boolean, duration: number }));
```
يمرر للأسفل في حال كان عرض التمرير عموديًا, ويمرر لليمين في حال كان عرض التمرير أفقيًا. وله الخيار `scrollToEnd({animated: true})` من أجل التمرير السلس وهو الإفتراضي, والخيار `scrollToEnd({animated: false})` من أجل التمرير السريع. كما يمكن على منصة إضافة المدة الزمنية للتمرير `scrollToEnd({duration: 500})`. في حال عدم تمرير أي خيار لهذا لتابع فإن القيمة الافتراضية للخيار `animated` هي `true`.
### `scrollWithoutAnimationTo()`
```Javascript
scrollWithoutAnimationTo(y, x);
```
**مهمل:** استخدم التابع `scrollTo` بدلا منه.
## مصادر
* [صفحة scrollView في توثيق React Native الرسمي.](https://facebook.github.io/react-native/docs/scrollview)