SectionList

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

一个高性能的分区列表渲染接口，支持以下便捷功能：

• 完全跨平台

• 可配置的可见性回调

• 支持列表头部

• 支持列表尾部

• 支持项分隔符

• 支持分区头部

• 支持区分隔符

• 支持异构数据及项的渲染

• 下拉刷新

• 滚动加载

若不需要分区支持且希望使用更简单的接口，请使用 <FlatList>

示例

这是对 <VirtualizedList> 的便捷封装，因此会继承其属性（以及 <ScrollView> 的属性），此处未明确列出的属性也会被继承，同时需要注意以下事项：

• 当内容滚动出渲染窗口时，内部状态不会被保留。请确保所有数据都存储在项数据或外部状态库（如 Flux/Redux/Relay）中

• 这是 PureComponent，意味着如果 props 保持浅层相等（shallow-equal），则不会重新渲染。请确保 renderItem 函数依赖的所有内容都通过属性传递（如 extraData），且该属性在更新后不是 === 相等的，否则界面可能不会更新。这包括 data 属性以及父组件状态

• 为控制内存占用并确保滚动流畅，列表内容会在屏幕外异步渲染。这意味着用户可能快速滚动时暂时看到空白区域，这是为平衡性能所做的设计取舍。我们正在持续优化该体验。

• 默认情况下，列表会查找每个项目的 key 属性作为 React key。您也可以通过 keyExtractor 属性提供自定义键

---

参考

属性

VirtualizedList 属性

继承 VirtualizedList 属性

---

Required

renderItem

默认的项渲染函数，用于所有分区中的项。可基于分区单独覆盖。应返回 React 元素

Type
function

该渲染函数接收包含以下键的对象：

• 'item' (object) - 本分区 data 属性中指定的项对象

• 'index' (number) - 项在分区内的索引

• 'section' (object) - sections 中指定的完整分区对象

• 'separators' (object) - 包含以下键的对象：

  • 'highlight' (function) - () => void
  • 'unhighlight' (function) - () => void
  • 'updateProps' (function) - (select, newProps) => void
    • 'select' (enum) - 可选值为 'leading' 或 'trailing'
    • 'newProps' (object)

---

Required

sections

实际要渲染的数据，类似于 FlatList 中的 data 属性

Type
array of Sections

---

extraData

用于通知列表重新渲染的标记属性（因列表继承自 PureComponent）。若 renderItem、Header、Footer 等函数依赖 data 属性之外的任何数据，请将其置于此处并视为不可变数据。

Type
any

---

initialNumToRender

初始批次渲染的项目数量。应足以填满屏幕但不宜过多。注意：为提升滚动至顶部的感知性能，这些初始项目永远不会因窗口化渲染而被卸载。

Type	Default
number	10

---

inverted

反转滚动方向（使用 -1 的缩放变换实现）。

Type	Default
boolean	false

---

ItemSeparatorComponent

在每个项目之间渲染（但不在顶部或底部）。默认提供 highlighted、section 和 [leading/trailing][Item/Section] 属性。renderItem 提供的 separators.highlight/unhighlight 可更新 highlighted 属性，也可通过 separators.updateProps 添加自定义属性。可以是 React 组件（如 SomeComponent）或 React 元素（如 <SomeComponent />）。

Type
component, function, element

---

keyExtractor

用于为指定索引处的项目生成唯一键。该键用于缓存和作为 React 的键来跟踪项目重排序。默认提取器依次检查 item.key、item.id，最后回退使用索引（与 React 行为一致）。注意这会为每个项目设置键，但每个分区仍需自己的键。

Type
(item: object, index: number) => string

---

ListEmptyComponent

列表为空时渲染。可以是 React 组件（如 SomeComponent）或 React 元素（如 <SomeComponent />）

Type
component, element

---

ListFooterComponent

在列表最末尾渲染。可以是 React 组件（如 SomeComponent）或 React 元素（如 <SomeComponent />）。

Type
component, element

---

ListHeaderComponent

在列表最开头渲染。可以是 React 组件（如 SomeComponent）或 React 元素（如 <SomeComponent />）。

Type
component, element

---

onRefresh

提供此函数可添加标准 RefreshControl 实现"下拉刷新"功能。需同时正确设置 refreshing 属性。若需控制刷新控件与顶部的偏移（如 100 点），请使用 progressViewOffset={100}。

Type
function

---

onViewableItemsChanged

当行项目的可见性发生变化时触发（可见性规则由 viewabilityConfig 属性定义）。

Type
(callback: {changed: ViewToken[], viewableItems: ViewToken[]}) => void

---

refreshing

在等待刷新数据时将此属性设为 true。

Type	Default
boolean	false

---

removeClippedSubviews

注意：某些情况下可能存在 bug（内容缺失）—— 请自行承担使用风险

此属性可能提升大型列表的滚动性能。

Type	Default
boolean	false

---

renderSectionFooter

在每个分区底部渲染。

Type
(info: {section: Section}) => element ｜ null

---

renderSectionHeader

在每个分区顶部渲染。在 iOS 上默认会粘附在 ScrollView 顶部（参见 stickySectionHeadersEnabled）。

Type
(info: {section: Section}) => element ｜ null

---

SectionSeparatorComponent

在每个分节的顶部和底部渲染（注意：这与 ItemSeparatorComponent 不同，后者仅在分节之间渲染）。这些分隔符旨在将分节与上方和下方的标题区分开，并且通常具有与 ItemSeparatorComponent 相同的高亮响应特性。同时还会接收 highlighted、[leading/trailing][Item/Section] 以及来自 separators.updateProps 的任何自定义属性。

Type
component, element

---

stickySectionHeadersEnabled

使分节标题（section header）固定在屏幕顶部，直到下一个标题将其推出。默认仅在 iOS 平台启用，因为这是该平台的标准行为。

Type	Default
boolean	false Android true iOS

方法

flashScrollIndicators()

iOS

tsx

flashScrollIndicators();

暂时显示滚动指示器。

---

recordInteraction()

tsx

recordInteraction();

通知列表发生了交互事件（例如当 waitForInteractions 为 true 且用户尚未滚动时），这会触发可见性计算。通常由点击列表项或导航操作触发。

---

scrollToLocation()

tsx

scrollToLocation(params: SectionListScrollParams);

滚动到指定 sectionIndex（分节索引）和 itemIndex（分节内项目索引）位置的项目：当 viewPosition 为 0 时项目置于顶部（可能被固定标题覆盖），为 1 时置于底部，为 0.5 时居中显示。

注意：若不指定 getItemLayout 或 onScrollToIndexFailed 属性，则无法滚动到渲染窗口之外的位置。

参数:

Name	Type
params Required	object

有效的 params 键如下：

• 'animated' (boolean) - 是否启用滚动动画。默认为 true。

• 'itemIndex' (number) - 要滚动到的项目在分节内的索引（必需）。

• 'sectionIndex' (number) - 包含目标项目的分节索引（必需）。

• 'viewOffset' (number) - 最终目标位置的像素偏移量（例如用于补偿固定标题的高度）。

• 'viewPosition' (number) - 目标位置：0（顶部）、1（底部）或 0.5（居中）。

类型定义

Section

用于标识特定分节待渲染数据的对象。

Type
any

属性：

Name	Type	Description
data Required	array	The data for rendering items in this section. Array of objects, much like FlatList's data prop.
key	string	Optional key to keep track of section re-ordering. If you don't plan on re-ordering sections, the array index will be used by default.
renderItem	function	Optionally define an arbitrary item renderer for this section, overriding the default renderItem for the list.
ItemSeparatorComponent	component, element	Optionally define an arbitrary item separator for this section, overriding the default ItemSeparatorComponent for the list.
keyExtractor	function	Optionally define an arbitrary key extractor for this section, overriding the default keyExtractor.