ReactNative/sectionlist

وهي واجهةٌ عالية الأداء لتصيير القوائم المقسّمة، ومن أهمّ ميّزاتها:

• منصّةٌ متعدّدةٌ (cross-platform).
• ردود نداءٍ قابلةٌ للضبط والعرض.
• تدعم ترويسة (header) القائمة.
• تدعم تذييل (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;

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

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

لصارمة === بعد التحديثات، وإلا فلن تُحدّث الواجهة عند التّغيير، وهذا يتضمّن الخاصيّة data وحالة المكوّن الأب.

• يصيّر المحتوى بشكلٍ غير متزامنٍ خارج نافذة الواجهة، وذلك لتقييد الذاكرة وتأمين تمريرٍ سلسٍ، مما يعني أنه يمكن التمرير أسرع من معدّل التعبئة (fill rate) مما يؤدي لظهور محتوىً فارغٍ للحظة، وهذا عبارة عن مقايضة (tradeoff) يمكن تعديلها لتناسب احتياجات كلّ تطبيق، ونعمل على تحسينه حاليًّأ.
• تبحث القائمة -بشكلٍ افتراضيٍّ- عن الخاصيّة key لكل عنصر لتستخدمها كمفتاح React، غير أنه يمكن استخدام الخاصيّة keyExtractor المخصّصة بشكلٍ بديلٍ.

الخاصيات

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

renderItem

المُصيّر الافتراضي لكل عنصرٍ في كلّ قسمٍ، ويمكن تجاوزها عل أساس كلّ قسم، ويجب أن تعيد عنصر React.

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

تمرَّر دالة التصيير ككائن له المفاتيح التالية:

• '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

خاصّيّةٌ تبيّن للقائمة حاجتها لإعادة التصيير (على اعتبار أنها تنفّذ PureComponent)، وتوضع فيها المعلومات التي تحتاجها الدوال (renderItem والترويسة والتذييل وغيرها) وهي غير موجودةٍ في الخاصية data.

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

initialNumToRender

تحدد عدد العناصر المصيّرة في الدفعة الأولى، والتي ستكون كافيةً لملء الشاشة لا أكثر، مع ملاحظة أن لن يتم استبدال عناصر الواجهة الأولى كجزء من عملية التصيير بالنوافذ (windowed rendering، يتم فيه استبدال عناصر نافذة الواجهة الحالية بعناصر النافذة التالية أثناء التمرير لتحسين الأداء)، وذلك للمحافظة على فاعلية التمرير للأعلى.

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

inverted

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

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

ItemSeparatorComponent

يُصيّر بين العناصر، ولكن لا في الأعلى أو الأسفل، ويزوَّد بشكلٍ افتراضيٍّ بالخاصيات highlighted و section و [leading/trailing][Item/Section]، كما تحتوي الدالة renderItem الخاصة بالواجهة View على 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 بشكلٍ صحيحٍ، فمثلًا لإزاحة التحكم بالتحديث 100 نقطة (pt) من أعلى القائمة نضع القيمة progressViewOffset={100}.

النوع	مطلوب
[() => 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)	لا

التوابع

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 فقط.

تعريفات النمط

Section

كائن معرّف للمعطيات التي ستُصير في قسمٍ معطىً.

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

الخصائص

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

مصادر

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