Skip to main content

SectionList

用于渲染分段列表的高性能界面，支持最方便的功能：

¥A performant interface for rendering sectioned lists, supporting the most handy features:

  • 完全跨平台。

    ¥Fully cross-platform.

  • 可配置的可见度回调。

    ¥Configurable viewability callbacks.

  • 列表标题支持。

    ¥List header support.

  • 列表页脚支持。

    ¥List footer support.

  • 项目分隔符支持。

    ¥Item separator support.

  • 节标题支持。

    ¥Section header support.

  • 节分隔符支持。

    ¥Section separator support.

  • 异构数据和项目渲染支持。

    ¥Heterogeneous data and item rendering support.

  • 拉动刷新。

    ¥Pull to Refresh.

  • 滚动加载。

    ¥Scroll loading.

如果你不需要部分支持并想要一个更简单的界面，请使用 <FlatList>。

¥If you don't need section support and want a simpler interface, use <FlatList>.

示例​

¥Example

这是 <VirtualizedList> 的便捷封装，因此继承了此处未明确列出的属性（以及 <ScrollView> 的属性），并附带以下注意事项：

¥This is a convenience wrapper around <VirtualizedList>, and thus inherits its props (as well as those of <ScrollView>) that aren't explicitly listed here, along with the following caveats:

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

    ¥Internal state is not preserved when content scrolls out of the render window. Make sure all your data is captured in the item data or external stores like Flux, Redux, or Relay.

  • 这是 PureComponent，这意味着如果 props 保持浅层相等，它将不会重新渲染。确保 renderItem 函数所依赖的所有内容都作为 prop（例如 extraData）传递，而更新后不是 ===，否则你的 UI 可能不会因更改而更新。这包括 data 属性和父组件状态。

    ¥This is a PureComponent which means that it will not re-render if props remain shallow-equal. Make sure that everything your renderItem function depends on is passed as a prop (e.g. extraData) that is not === after updates, otherwise your UI may not update on changes. This includes the data prop and parent component state.

  • 为了限制内存并实现平滑滚动，内容在屏幕外异步渲染。这意味着滚动速度可能快于填充速度，并暂时看到空白内容。这是一个可以调整以适应每个应用的需求的权衡，我们正在幕后努力改进它。

    ¥In order to constrain memory and enable smooth scrolling, content is rendered asynchronously offscreen. This means it's possible to scroll faster than the fill rate and momentarily see blank content. This is a tradeoff that can be adjusted to suit the needs of each application, and we are working on improving it behind the scenes.

  • 默认情况下，列表会在每个项目上查找 key 属性并将其用作 React 键。或者，你可以提供自定义 keyExtractor 属性。

    ¥By default, the list looks for a key prop on each item and uses that for the React key. Alternatively, you can provide a custom keyExtractor prop.

参考

¥Reference

属性​

¥Props

VirtualizedList 属性​

¥VirtualizedList Props

继承 VirtualizedList 属性。

¥Inherits VirtualizedList Props.

​

每个部分中每个项目的默认渲染器。可以在每个部分的基础上覆盖。应该返回一个 React 元素。

¥Default renderer for every item in every section. Can be over-ridden on a per-section basis. Should return a React element.

类型
function

渲染函数将传递一个具有以下键的对象：

¥The render function will be passed an object with the following keys:

  • 'item'（对象） - 本节的 data 键中指定的项目对象

    ¥'item' (object) - the item object as specified in this section's data key

  • 'index'（号码） - 该部分中项目的索引。

    ¥'index' (number) - Item's index within the section.

  • 'section'（对象） - sections 中指定的完整节对象。

    ¥'section' (object) - The full section object as specified in sections.

  • 'separators'（对象） - 具有以下键的对象：

    ¥'separators' (object) - An object with the following keys:

    • 'highlight'（功能） - () => void

      ¥'highlight' (function) - () => void

    • 'unhighlight'（功能） - () => void

      ¥'unhighlight' (function) - () => void

    • 'updateProps'（功能） - (select, newProps) => void

      ¥'updateProps' (function) - (select, newProps) => void

      • 'select'（枚举） - 可能的值为 'leading'、'trailing'

        ¥'select' (enum) - possible values are 'leading', 'trailing'

      • 'newProps'（对象）

        ¥'newProps' (object)

​

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

¥The actual data to render, akin to the data prop in FlatList.

类型
部分 数组

extraData​

用于告诉列表重新渲染的标记属性（因为它实现了 PureComponent）。如果你的任何 renderItem、页眉、页脚等功能依赖于 data 属性之外的任何内容，请将其粘贴在这里并以不变的方式对待它。

¥A marker property for telling the list to re-render (since it implements PureComponent). If any of your renderItem, Header, Footer, etc. functions depend on anything outside of the data prop, stick it here and treat it immutably.

类型
any

initialNumToRender​

初始批次中要渲染的项目数。这应该足以填满屏幕，但不能太多。请注意，这些项目永远不会作为窗口渲染的一部分被卸载，以提高滚动到顶部操作的感知性能。

¥How many items to render in the initial batch. This should be enough to fill the screen but not much more. Note these items will never be unmounted as part of the windowed rendering in order to improve perceived performance of scroll-to-top actions.

类型默认
number10

inverted​

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

¥Reverses the direction of scroll. Uses scale transforms of -1.

类型默认
booleanfalse

ItemSeparatorComponent​

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

¥Rendered in between each item, but not at the top or bottom. By default, highlighted, section, and [leading/trailing][Item/Section] props are provided. renderItem provides separators.highlight/unhighlight which will update the highlighted prop, but you can also add custom props with separators.updateProps. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

类型
组件、函数、元素

keyExtractor​

用于提取指定索引处给定项目的唯一键。Key 用于缓存并作为 React 键来跟踪项目重新排序。默认提取器检查 item.key，然后回退到使用索引，就像 React 所做的那样。请注意，这为每个项目设置了键，但每个整体部分仍然需要自己的键。

¥Used to extract a unique key for a given item at the specified index. Key is used for caching and as the React key to track item re-ordering. The default extractor checks item.key, then falls back to using the index, like React does. Note that this sets keys for each item, but each overall section still needs its own key.

类型
（项目：对象，索引：数字）=> 字符串

ListEmptyComponent​

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

¥Rendered when the list is empty. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

类型
组件、元素

ListFooterComponent​

渲染在列表的最后。可以是 React 组件（例如 SomeComponent），或 React 元素（例如 <SomeComponent />）。

¥Rendered at the very end of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

类型
组件、元素

ListHeaderComponent​

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

¥Rendered at the very beginning of the list. Can be a React Component (e.g. SomeComponent), or a React element (e.g. <SomeComponent />).

类型
组件、元素

onRefresh​

如果提供，将为 "拉动刷新" 功能添加标准 RefreshControl。确保正确设置 refreshing 属性。要从顶部偏移 RefreshControl（例如 100 点），请使用 progressViewOffset={100}。

¥If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. To offset the RefreshControl from the top (e.g. by 100 pts), use progressViewOffset={100}.

类型
function

onViewableItemsChanged​

当行的可见性发生变化时调用，如 viewabilityConfig 属性所定义。

¥Called when the viewability of rows changes, as defined by the viewabilityConfig prop.

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

refreshing​

在等待刷新的新数据时将其设置为 true。

¥Set this true while waiting for new data from a refresh.

类型默认
booleanfalse

removeClippedSubviews​

注意：在某些情况下可能会出现错误（缺少内容） - 使用风险由你自行承担。

¥Note: may have bugs (missing content) in some circumstances - use at your own risk.

这可以提高大型列表的滚动性能。

¥This may improve scroll performance for large lists.

类型默认
booleanfalse

renderSectionFooter​

渲染在每个部分的底部。

¥Rendered at the bottom of each section.

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

renderSectionHeader​

渲染在每个部分的顶部。在 iOS 上，它们默认粘在 ScrollView 的顶部。参见 stickySectionHeadersEnabled。

¥Rendered at the top of each section. These stick to the top of the ScrollView by default on iOS. See stickySectionHeadersEnabled.

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

SectionSeparatorComponent​

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

¥Rendered at the top and bottom of each section (note this is different from ItemSeparatorComponent which is only rendered between items). These are intended to separate sections from the headers above and below and typically have the same highlight response as ItemSeparatorComponent. Also receives highlighted, [leading/trailing][Item/Section], and any custom props from separators.updateProps.

类型
组件、元素

stickySectionHeadersEnabled​

使节标题粘在屏幕顶部，直到下一个节标题将其推出。仅在 iOS 上默认启用，因为这是那里的平台标准。

¥Makes section headers stick to the top of the screen until the next one pushes it off. Only enabled by default on iOS because that is the platform standard there.

类型默认
booleanfalse
Android
true
iOS

方法​

¥Methods

flashScrollIndicators()
iOS
​

flashScrollIndicators();

暂时显示滚动指示器。

¥Displays the scroll indicators momentarily.

recordInteraction()​

recordInteraction();

告诉列表发生了交互，这应该触发可见度计算，例如 如果 waitForInteractions 为 true 并且用户尚未滚动。这通常是通过点击项目或导航操作来调用的。

¥Tells the list an interaction has occurred, which should trigger viewability calculations, e.g. if waitForInteractions is true and the user has not scrolled. This is typically called by taps on items or by navigation actions.

scrollToLocation()​

scrollToLocation(params: SectionListScrollParams);

滚动到位于可视区域中的指定 sectionIndex 和 itemIndex（在该部分内）处的项目，以便 viewPosition 0 将其置于顶部（并且可能被粘性标头覆盖），1 置于底部，0.5 置于居中 中间。

¥Scrolls to the item at the specified sectionIndex and itemIndex (within the section) positioned in the viewable area such that viewPosition 0 places it at the top (and may be covered by a sticky header), 1 at the bottom, and 0.5 centered in the middle.

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

¥Note: Cannot scroll to locations outside the render window without specifying the getItemLayout or onScrollToIndexFailed prop.

参数：

¥Parameters:

名称类型
参数
必填
object

有效的 params 键为：

¥Valid params keys are:

  • 'animated'（布尔值） - 列表是否应该在滚动时播放动画。默认为 true。

    ¥'animated' (boolean) - Whether the list should do an animation while scrolling. Defaults to true.

  • 'itemIndex'（号码） - 要滚动到的项目的部分内的索引。必需的。

    ¥'itemIndex' (number) - Index within section for the item to scroll to. Required.

  • 'sectionIndex'（号码） - 包含要滚动到的项目的部分的索引。必需的。

    ¥'sectionIndex' (number) - Index for section that contains the item to scroll to. Required.

  • 'viewOffset'（号码） - 用于偏移最终目标位置的固定数量的像素，例如 以补偿粘性标头。

    ¥'viewOffset' (number) - A fixed number of pixels to offset the final target position, e.g. to compensate for sticky headers.

  • 'viewPosition'（号码） - 值 0 会将索引指定的项目放在顶部，1 放在底部，0.5 放在中间居中。

    ¥'viewPosition' (number) - A value of 0 places the item specified by index at the top, 1 at the bottom, and 0.5 centered in the middle.

类型定义​

¥Type Definitions

部分​

¥Section

标识要为给定部分渲染的数据的对象。

¥An object that identifies the data to be rendered for a given section.

类型
any

属性：

¥Properties:

名称类型描述
数据
必填
array用于渲染本节中的项目的数据。对象数组，很像 FlatList 的数据属性。
keystring用于跟踪部分重新排序的可选键。如果你不打算重新排序部分，则默认情况下将使用数组索引。
renderItemfunction可以选择为此部分定义任意项目渲染器，覆盖列表的默认 renderItem。
项目分隔符组件组件、元素可以选择为此部分定义任意项目分隔符，覆盖列表的默认 ItemSeparatorComponent。
keyExtractorfunction可以选择为此部分定义任意密钥提取器，覆盖默认的 keyExtractor。