مراجعة 15:48، 18 ديسمبر 2020

SectionList

وهي واجهة عالية الأداء مستخدمة لإظهار القوائم المقسمة، وتمتاز بما يلي:

دعم كامل للمنصات المتعددة (cross-platform).
تدعم ضبط استجابات الإظهار.
تدعم تذييل (footer) القائمة.
تدعم فاصل العناصر.
تدعم ترويسة القسم.
تدعم فاصل الأقسام.
تدعم إظهار العناصر والمعطيات الغير متجانسة (Heterogeneous).
تدعم السحب للتحديث (Pull to Refresh).
تدعم تحميل التمرير (Scroll loading).

يمكن استخدام واجهة أبسط مثل FlatList عند عدم الحاجة لدعم الأقسام.

مثال

مثال لمكوِّن دالّي (Function Component)

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

const DATA = [
  {
    title: "Main dishes",
    data: ["Pizza", "Burger", "Risotto"]
  },
  {
    title: "Sides",
    data: ["French Fries", "Onion Rings", "Fried Shrimps"]
  },
  {
    title: "Drinks",
    data: ["Water", "Coke", "Beer"]
  },
  {
    title: "Desserts",
    data: ["Cheese Cake", "Ice Cream"]
  }
];

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

const App = () => (
  <SafeAreaView style={styles.container}>
    <SectionList
      sections={DATA}
      keyExtractor={(item, index) => item + index}
      renderItem={({ item }) => <Item title={item} />}
      renderSectionHeader={({ section: { title } }) => (
        <Text style={styles.header}>{title}</Text>
      )}
    />
  </SafeAreaView>
);

const styles = StyleSheet.create({
  container: {
    flex: 1,
    marginTop: Constants.statusBarHeight,
    marginHorizontal: 16
  },
  item: {
    backgroundColor: "#f9c2ff",
    padding: 20,
    marginVertical: 8
  },
  header: {
    fontSize: 32,
    backgroundColor: "#fff"
  },
  title: {
    fontSize: 24
  }
});

export default App;

مثال لمكوِّن صنفي (Class Component)

import React, { Component } from "react";
import {
  StyleSheet,
  Text,
  View,
  SafeAreaView,
  SectionList
} from "react-native";
import Constants from "expo-constants";

const DATA = [
  {
    title: "Main dishes",
    data: ["Pizza", "Burger", "Risotto"]
  },
  {
    title: "Sides",
    data: ["French Fries", "Onion Rings", "Fried Shrimps"]
  },
  {
    title: "Drinks",
    data: ["Water", "Coke", "Beer"]
  },
  {
    title: "Desserts",
    data: ["Cheese Cake", "Ice Cream"]
  }
];

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

class App extends Component {
  render() {
    return (
      <SafeAreaView style={styles.container}>
        <SectionList
          sections={DATA}
          keyExtractor={(item, index) => item + index}
          renderItem={({ item }) => <Item title={item} />}
          renderSectionHeader={({ section: { title } }) => (
            <Text style={styles.header}>{title}</Text>
          )}
        />
      </SafeAreaView>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    marginTop: Constants.statusBarHeight,
    marginHorizontal: 16
  },
  item: {
    backgroundColor: "#f9c2ff",
    padding: 20,
    marginVertical: 8
  },
  header: {
    fontSize: 32,
    backgroundColor: "#fff"
  },
  title: {
    fontSize: 24
  }
});

export default App;

يعد هذا المكون تغليف ملائمة (convenience wrapper) حول المكون الأساسي VirtualizedList، لذا فإن خاصياته موروثة منه (كذلك من المكوّن ScrollView) مع مراعاة ما يلي:

إن الحالة الداخلية غير محفوظة عند تمرير المحتوى خارج نافذة الإظهار، لذا يجب التأكد من حفظ البيانات ضمن عنصر البيانات أو في المخازن الخارجية مثل Flux أو Redux أو Relay.
إن هذا المكوّن من النوع الصافي PureComponent، مما يعني أنه لن يتم تحديث الإظهار في حال بقيت قيمة الخاصيات مساوية سطحيًا (shallow-equal) لقيمها السابقة. لذا يجب التأكد من أن كل شيء يتم تمريره كخاصيّة للدالة renderItem لا يحتوي على المساواة السطحية === بعد التحديثات، وإلا فإن الواجهة لن تُحدّث أثناء التغيير. ويتضمن هذا الخاصيّة data ومكوّن الحالة الأب.
يظهر المحتوى بشكل غير متزامن خارج نافذة الإظهار، وذلك لتقييد الذاكرة ولتأمين سلاسة في التمرير. مما يعني أنه يمكن التمرير أسرع من معدّل التعبئة (fill rate) مما يؤدي لظهور محتوى فارغ لحظيًا. وهذا عبارة عن مقايضة (tradeoff) يمكن تعديلها لتناسب احتياجات كل تطبيق.
تبحث القائمة بشكل افتراضي عن الخاصيّة key ضمن كل عنصر لتستخدمها كمفتاح React، غير أنه يمكن بشكل بديل استخدام الخاصيّة keyExtractor لإدخال مفتاح شخصي.

الخاصيّات (Props)

موروثة من الخاصيّات ScrollView.

`renderItem`

المُظهِر الافتراضي لكل عنصر في كل قسم، وهذا المظهر هو عبارة عن دالة تعيد عنصر React.

النوع	مطلوب
كائن (object)	لا

يُمرَّر لدالة الإظهار كائن مع المفاتيح التالية:

item (كائن) - كائن العنصر والمحدد في data الخاصة بالقسم.
index (عدد) - دليل العنصر داخل القسم.
section (كائن) - كائن القسم الكامل والمحدد في sections.
separator (كائن) - كائن له المفاتيح التالية:
- highlight (دالة) - () => void.
- unhighlight (دالة) - () => void.
- updateProps (دالة) - (select، newProps) => void.
  - select (قيمة اسمية) - قيمها المحتملة leading أو trailing.
  - newProps (كائن).

`sections`

تمثّل البيانات الفعلية للإظهار، كما هو الحال مع الخاصيّة data في FlatList.

النوع	مطلوب
مصفوفة من الأقسام (array of sections)	نعم

`extraData`

تتضمن البيانات الإضافية التي تحتاجها دوال الإظهار (renderItem والترويسة والتذييل وغيرها) والغير موجودة في data.

النوع	مطلوب
أي شيء (any)	لا

`initialNumToRender`

تحدد عدد العناصر الواجب إظهارها في الدفعة الأولى لتملأ الشاشة لا أكثر.

ملاحظة: لن يتم استبدال عناصر الإظهار الأولى في الإظهار بالنوافذ (يتم فيه استبدال عناصر نافذة الإظهار الحالية بعناصر النافذة التالية أثناء التمرير وذلك لتحسين الأداء)، وذلك للمحافظة على فاعلية التمرير للأعلى.

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

`inverted`

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

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

`ItemSeparatorComponent`

يُظهَر هذا المكوّن بين العناصر ولكن ليس في الأعلى أو الأسفل، ويزوَّد بشكل افتراضي بالخاصيات highlighted و section و [leading/trailing][Item/Section]. كما تتضمن دالة الإظهار renderItem على separators.highlight و separators.unhighlight والمستخدمة لتحديث الخاصيّة highlighted، غير أنه من الممكن إضافة خاصيات شخصية مع separators. updateProps.

النوع	مطلوب
عنصر، دالة، مكون (component, function, element)	لا

`keyExtractor`

تُستخدم لاستخراج مفتاح فريد للعنصر المعطى وفق الدليل المحدد، حيث يُستخدم هذا المفتاح من أجل التخزين المؤقت (caching) ومن أجل تعقّب إعادة ترتيب العنصر. يتفحّص المستخرج الافتراضي item.key ثم يعود لاستخدام الدليل، بشكل مماثل لتوثيق React.

ملاحظة: يضع هذا المستخرج مفتاح لكل عنصر، غير أن كل قسم كامل مازال بحاجة لمفتاحه الخاص.

النوع	مطلوب
سلسلة نصية (`(item: Item, index: number) => string`)	نعم

`ListEmptyComponent`

يُظهَر هذا المكوّن عندما تكون القائمة فارغة، ويمكن أن يكون صنف مكوّن React أو دالة إظهار أو العنصر المُظهَر.

النوع	مطلوب
عنصر، دالة، مكون (component, function, element)	لا

`ListFooterComponent`

يُظهَر هذا المكوّن في آخر القائمة، ويمكن أن يكون صنف مكوّن React أو دالة إظهار أو العنصر المُظهَر.

النوع	مطلوب
عنصر، دالة، مكون (component, function, element)	لا

`ListHeaderComponent`

يُظهَر هذا المكوّن في بداية القائمة، ويمكن أن يكون صنف مكوّن React أو دالة إظهار أو العنصر المُظهَر.

النوع	مطلوب
عنصر، دالة، مكون (component, function, element)	لا

`onEndReached`

تُستدعى عند وصول موقع التمرير إلى العتبة onEndReachedThreshold في المحتوى المُظهَر.

النوع	مطلوب
معلومات (`(info: {distanceFromEnd: number}) => void`)	لا

`onEndReachedThreshold`

تحدد مسافة أسفل المحتوى المرئي عن أسفل القائمة نسبة إلى طول القسم المرئي من القائمة والتي يجب عندها إطلاق الاستجابة onEndReached، لذا ستُطلق القيمة 0.5 الاستجابة onEndReached عندما تصبح نهاية المحتوى الظاهر ضمن منتصف الطول المرئي من القائمة.

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

`onRefresh`

تُضيف التحكم بالتحديث المعياري (standard RefreshControl) لوظيفة السحب للتحديث (Pull to Refresh)، كما يجب ضبط الخاصيّة refreshing بشكل صحيح. فمثلا توضع القيمة progressViewOffset={100} لجعل إزاحة التحكم بالتحديث 100 نقطة (pt) من أعلى القائمة.

النوع	مطلوب
`[() => void]`	لا

`onViewableItemsChanged`

تُستدعى هذه الدالة عند تغيّر قابلية إظهار السطور والمعرّفة بالخاصيّة viewabilityConfig.

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

يُمرر لهذه الدالة كائن له المفاتيح التالية:

viewableItems (مصفوفة من ViewToken)
changed (مصفوفة من ViewToken)

يُصدَّر النوع ViewToken عن طريق ViewabilityHelper.js:

الاسم	النوع	مطلوب
`item`	أي نوع (any)	نعم
`key`	سلسلة نصية (string)	نعم
`index`	عدد (number)	لا
`isViewable`	قيمة منطقية (boolean)	نعم
`section`	أي نوع (any)	لا

refreshing

تُضبط بالقيمة true لانتظار البيانات الجديدة من أجل التحديث.

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

`removeClippedSubview`

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

تنبيه: تظهر فيها أحيانًا بعض العيوب مثل المحتوى مفقود، لذا استخدمها على مسؤوليتك الشخصية.

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

`renderSectionFooters`

يُظهَر أسفل كل قسم.

النوع	مطلوب
عنصر (`(info: {section: SectionT}) => ?React.Element<any>`)	لا

`renderSectionHeader`

يُظهَر أعلى كل قسم. كما تلتصق بأعلى عرض التمرير (ScrollView) بشكل افتراضي على منصّة iOS، انظر الخاصيّة stickySectionHeadersEnabled.

النوع	مطلوب
عنصر (`(info: {section: SectionT}) => ?React.Element<any>`)	لا

`SectionSeparatorComponent`

يُظهَر هذا المكوّن في أعلى وأسفل كل قسم (يختلف عن المكوّن ItemSeparatorComponent الذي يُظهَر بين العناصر فقط)، ومخصص لفصل الأقسام عن الترويسات التي في الأعلى والأسفل، ولها نفس استجابة الإبراز (highlight) كما هو الحال مع المكوّن ItemSeparatorComponent. كما يستقبل الخاصيات highlighted و [leading/trailing][Item/Section]، وأية خاصيات شخصية من separators.updateProps.

النوع	مطلوب
صنف React	لا

`stickySectionHeadersEnabled`

تجعل ترويسة القسم تلتصق بأعلى الشاشة حتى تأتي الترويسة التالية وتزيحها، ومفعّلة بشكل افتراضي على منصّة iOS.

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

التوابع (Methods)

`()scrollToLocation`

scrollToLocation(params);

يمرَّر إلى العنصر المحدد بالخاصيتين sectionIndex و itemIndex (ضمن القسم)، والمتوضّع في المنطقة المرئية بناء على الخاصيّة viewPosition، فإذا كانت قيمتها 0 فإن العنصر يتوضّع في الأعلى وإذا كانت قيمتها 1 فإنه يتوضّع في الأسفل وإن كانت 0.5 فإنه يتوضّع في المنتصف.

ملاحظة: لا يمكن التمرير لموقع خارج نافذة الإظهار من دون تحديد الخاصيّة getItemLayout أو onScrollToIndexFailed.

الاسم	النوع	مطلوب	الوصف
`params`	كائن (object)	نعم	انظر في الأسفل

مفاتيح الكائن params:

animated (قيمة منطقية) - تحدد فيما إذا كانت القائمة ستتحرك أثناء التمرير، وقيمتها الافتراضية true.
itemIndex (عدد) - دليل العنصر الذي سيُمرر إليه داخل القسم. مطلوب.
sectionIndex (عدد) - دليل القسم الذي يحتوي على العنصر الذي سيُمرر إليه. مطلوب.
viewOffset (عدد) - عدد ثابت من البكسلات لتحديد إزاحة عن الموقع المطلوب.
viewPosition (عدد) - إذا كانت قيمتها 0 فإن العنصر المطلوب يتوضع في الأعلى وإذا كانت قيمتها 1 فإنه يتوضّع في الأسفل وإن كانت 0.5 فإنه يتوضّع في المنتصف.

`()recordInteraction`

recordInteraction();

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

`()flashScrollIndicators`

flashScrollIndicators();

يُظهر مؤشرات التمرير لحظيًا، ويعمل على منصًة iOS فقط.

تعريفات النوع (Type Definitions)

`Section`

كائن معرّف للمعطيات التي ستُظهَر في القسم.

النوع
أي نوع (any)

الخصائص (Properties)

الاسم	النوع	الوصف
`data`	مصفوفة (array)	معطيات لإظهار العناصر في القسم، وهي مصفوفة من الكائنات مثل الخاصية `FlatList's data prop`
`[key]`	سلسلة نصية (string)	مفتاح اختياري لتعقب إعادة ترتيب الأقسام، ويستخدم دليل الأقسام بشكل افتراضي عند عدم استخدام هذا المفتاح
`[renderItem]`	عنصر، دالة، مكون (component, function element)	لتحديد مُظهر اختياري لعناصر القسم بدل المُظهر الافتراضي `renderItem`
`[ItemSeparatorComponent]`	قيمة منطقية (boolean)	لتحديد فاصل اختياري لعناصر القسم بدل الفاصل الافتراضي `ItemSeparatorComponent`
`[keyExtractor]`	دالة (function)	لتحديد مستخرج مفتاح اختياري للقسم بدل المستخرج الافتراضي `keyExtractor`

مصادر

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