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, StatusBar } from "react-native";

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,
    paddingTop: StatusBar.currentHeight,
    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, StatusBar } from "react-native";

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>
);

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,
    paddingTop: StatusBar.currentHeight,
    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 .

renderItem

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

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

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

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

sections

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

النوع	مطلوب
مصفوفة من النوع Section (انظر في الأسفل)	نعم

extraData

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

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

initialNumToRender

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

القيمة الافتراضية: 10.

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

inverted

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

القيمة الافتراضية false.

النوع	مطلوب
(boolean)	لا

ItemSeparatorComponent

يُصيّر بين العناصر ولكن لا في الأعلى أو الأسفل، ويزوَّد افتراضيًّا بالخاصيات التالية:

• highlighted
• section
• [leading/trailing][Item/Section]،

كما تحتوي الدالة renderItem الخاصة بالواجهة View على separators.highlight، و separators.unhighlight والمستخدمة لتحديث الخاصيّة highlighted، كما يمكن إضافة خاصيات مخصّصةٌ في separators.updateProps.

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

keyExtractor

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

النوع	مطلوب
item: Item, index: number) => string)	نعم

ListEmptyComponent

تصيّر عندما تكون القائمة فارغةً، ويمكن أن يكون مكوّن React (مثل SomeComponent) أو عنصر React (مثل <SomeComponent /‎>).

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

ListFooterComponent

يصيّر في آخر القائمة، ويمكن أن يكون مكوّن React (مثل SomeComponent) أو عنصر React (مثل <SomeComponent /‎>).

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

ListHeaderComponent

يُصيّر في بداية القائمة، ويمكن أن يكون مكوّن React (مثل SomeComponent) أو عنصر React (مثل <SomeComponent /‎>).

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

onEndReached

تُستدعى عند وصول موقع التمرير إلى الخاصّية onEndReachedThreshold في المحتوى المُصيّر.

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

onEndReachedThreshold

تحدّد كم يجب أن يكون بعد الحافة السفلى للقائمة (بوحدات طول القائمة المرئيّ) عن نهاية المحتوى والتي سيطلق عندها رد النداء onEndReached، لذا ستُطلق القيمة 0.5 الاستجابة onEndReached عندما تكون نهاية المحتوى في حدود منتصف طول القائمة المرئيّ.

القيمة الافتراضية 2.

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

onRefresh

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

النوع	مطلوب
دالة	لا

onViewableItemsChanged

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

النوع	مطلوب
‎(callback: { changed: array of ViewTokens, viewableItems: array of ViewTokens }) => void	لا

refreshing

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

النوع	مطلوب
(bool)	لا

removeClippedSubview

تنبيه: قد تواجهة خطأ (محتوى مفقود) في بعض الحالات، لذا لا ننصح باستعمالها إلا إن أحببت المخاطرة على مسؤوليتك.

تُستخدم لتحسين أداء التمرير في القوائم الطويلة، مع ملاحظة إمكانية ظهور بعض العيوب أحيانًا (مثل المحتوى مفقود) لذا استخدمها على مسؤوليّتك الشخصيّة.

القيمة الافتراضية false.

النوع	مطلوب
(bool)	لا

renderSectionFooter

يُصيّر أسفل كلّ قسم.

النوع	مطلوب
‎(info: { section: Section }) => element, null	لا

renderSectionHeader

يُصيّر أعلى كلّ قسمٍ، كما تثبت أعلى واجهة التمرير (ScrollView) افتراضيًا على منصّة iOS، يمكن مراجعة الخاصيّة stickySectionHeadersEnabled.

النوع	مطلوب
‎(info: { section: Section }) => element, null	لا

SectionSeparatorComponent

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

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

stickySectionHeadersEnabled

تثبّت ترويسة القسم أعلى الشاشة حتى تأتي الترويسة التالية وتحلّ محلّها، ومفعّلة افتراضيًّا على منصّة iOS أي قيمتها true بينما قيمتها الافتراضية false على منصة Android.

النوع	مطلوب
(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
key	لا	سلسلة نصية (string)	مفتاح اختياري لتعقب إعادة ترتيب الأقسام، ويستخدم دليل الأقسام بشكلٍ افتراضيٍ عند عدم استخدام هذا المفتاح
renderItem	لا	دالة (function)	لتحديد مُصيرٍ اختياريٍّ لعناصر القسم بدل المُصير الافتراضي renderItem
ItemSeparatorComponent	لا	عنصر، مكون (component, element)	لتحديد فاصل اختياري لعناصر القسم بدل الفاصل الافتراضي ItemSeparatorComponent
keyExtractor	لا	دالة (function)	لتحديد مستخرج مفتاح اختياري للقسم بدل المستخرج الافتراضي keyExtractor

مصادر

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