shopify-flash-list - Amazon Vega Docs

@amazon-devices/shopify__flash-list提供一个高速度、高性能的列表组件。FlashList和React Native提供的FlatList类似。FlatList所支持的属性，FlashList也支持。您可以通过替换FlatList组件并添加estimatedItemSize属性来尝试FlashList。此外，FlashList通过添加其他属性来扩展支持的属性的列表，以帮助实现最佳性能。这是一个系统部署的库，可供适用于Vega的React Native应用使用，无需单独的安装过程。它作为自动链接库进行部署，您的应用在运行时会链接到该库。只能在库和为其构建的适用于Vega的React Native版本之间保证兼容性。在升级构建应用所依据的适用于Vega的React Native版本时，最佳实践是同时升级依赖于适用于Vega的React Native的库的版本。

安装

在package.json文件中添加JavaScript库依赖项。选择适用于您的React Native版本的选项卡。

React Native 0.72
React Native 0.83

"dependencies": {
...
"@amazon-devices/shopify__flash-list": "~2.0.0"
}

"dependencies": {
...
"@amazon-devices/shopify__flash-list": "~2.0.9000000000"
}

使用npm install命令重新安装依赖项。

示例

以下示例使用常见的数据集和组件。为了避免示例中的重复，已删除一些项目。

import React from "react";
import { Text, TouchableOpacity } from "react-native";

export const randomColor = () => `#${Math.floor(Math.random() * 16777215).toString(16)}`;

export const DATA = Array.from({ length: 1000 }, (_, i) => ({
  title: `项目${i + 1}`,
  bgColor: randomColor(),
  height: Math.floor(Math.random() * (140 - 60) + 60),
}))

interface ItemProps {
  item: {
    bgColor: string;
    title: string;
    height?: number;
    width?: number;
  }
}

export const Item = (props: ItemProps) => (
  <TouchableOpacity style={{ backgroundColor: props.item.bgColor, flex: 1 }}>
    <Text style={{ height: props.item.height, width: props.item.width, fontSize: 20, fontWeight: "500" }}>{props.item.title}</Text>
  </TouchableOpacity>
)

FlashList组件示例

import { FlashList } from "@amazon-devices/shopify__flash-list";
import React from "react";
import { Dimensions, Text, View } from "react-native";

import { DATA, Item } from "./common";

export const App = () => (
    <FlashList
      data={DATA}
      renderItem={({ item }) => <Item item={item} />}
      ListHeaderComponent={
        <View style={{ flex: 1, height: 100, backgroundColor: 'white', justifyContent: 'center', alignItems: 'center' }}>
          <Text style={{ fontSize: 24, fontWeight: "600" }}>FlashList Demo</Text>
        </View>
      }
      estimatedFirstItemOffset={100}
      estimatedItemSize={100}
      estimatedListSize={{
        height: Dimensions.get('screen').height,
        width: Dimensions.get('screen').width
      }}
    />
  )

带有无限滚动功能的FlashList示例

import { FlashList } from "@amazon-devices/shopify__flash-list";
import React, { useState } from "react";
import { Dimensions, Text, View } from "react-native";

import { Item } from "./common";

const randomColor = () => `#${Math.floor(Math.random() * 16777215).toString(16)}`;

export const App = () => {
  const [data, setData] = useState(Array.from({ length: 20 }, (_, i) => ({
    title: `项目${i + 1}`,
    bgColor: randomColor(),
    height: Math.floor(Math.random() * (140 - 60) + 60),
  })));

  const loadMoreData = () => {
    const newData = Array.from({ length: 20 }, (_, i) => ({
      title: `Item ${data.length + i + 1}`,
      bgColor: randomColor(),
      height: Math.floor(Math.random() * (140 - 60) + 60),
    }))
    setData(items => items.concat(newData));
  }

  return (
    <FlashList
      data={data}
      renderItem={({ item }) => <Item item={item} />}
      ListHeaderComponent={
        <View style={{ flex: 1, height: 100, backgroundColor: 'white', justifyContent: 'center', alignItems: 'center' }}>
          <Text style={{ fontSize: 24, fontWeight: "600" }}>InfiniteScroll Demo</Text>
        </View>
      }
      estimatedFirstItemOffset={100}
      estimatedItemSize={100}
      estimatedListSize={{
        height: Dimensions.get('screen').height,
        width: Dimensions.get('screen').width
      }}
      onEndReached={loadMoreData}
    />
  )
}

MasonryFlashList示例

MasonryFlashList是包含许多列的FlashList组件。

import { MasonryFlashList } from "@amazon-devices/shopify__flash-list";
import React from "react";
import { Dimensions, Text, View } from "react-native";

import { DATA, Item } from "./common";

export const App = () => (
    <MasonryFlashList
      data={DATA}
      numColumns={3}
      renderItem={({ item }) => <Item item={item} />}
      estimatedFirstItemOffset={100}
      estimatedItemSize={100}
      estimatedListSize={{
        height: Dimensions.get('screen').height,
        width: Dimensions.get('screen').width
      }}
      ListHeaderComponent={
        <View style={{ flex: 1, height: 100, backgroundColor: 'white', justifyContent: 'center', alignItems: 'center' }}>
          <Text style={{ fontSize: 24, fontWeight: "600" }}>MasonryList Demo</Text>
        </View>
      }
    />
  );

API参考

查看专门文档页面（仅提供英文版），了解有关此库、API参考等的信息。 FlashList库涵盖了FlatList组件支持的所有属性。它如下文所列，增加了用于优化性能的额外属性。

组件

组件	描述
`FlashList`	与React Native `FlatList`等效，带有额外的属性以优化性能。
`AnimatedFlashList`	添加对`Animated`的`FlashList` API的支持。
`MasonryFlashList`	包含列的`FlashList`，这些列也是`FlashList`组件
`AutoLayoutView`	在`FlashList`中使用的原生组件，负责重新计算布局。
`CellContainer`	代表列表中单个单元格的原生组件。

属性

属性	描述
`estimatedItemSize`	一个单一数值，在渲染项目之前向`FlashList`提示相应项目的大致大小。然后，`FlashList`可以使用此信息来决定在初始加载之前和滚动时需要在屏幕上绘制多少项目。
`disableAutoLayout`	`FlashList`默认布局可能会与自定义`CellRendererComponent`实现发生冲突，因为该布局对子组件进行了一些修复。您可以通过将`disableAutoLayout`设置为`true`来禁用此行为。
`disableHorizontalListHeightMeasurement`	`FlashList`尝试通过提前绘制额外的列表项目来测量水平列表的大小。在内容很少的列表中与`initialScrollIndex`一起使用时，这样有时会导致问题。您可以禁用此行为。
`drawDistance`	高级渲染的绘制距离。
`estimatedFirstItemOffset`	此项指定绘制第一个项目时与列表窗口起点的距离或与列表第一项（不是标题）的偏移量。如果您使用`initialScrollIndex`属性，则为必需项。
`estimatedListSize`	列表的估计可见高度和宽度。不是滚动内容大小。定义此属性会使列表能够立即渲染。如果没有此属性，列表首先需要测量自身大小，这会导致第一次渲染时出现轻微延迟。
`onBlankArea`	`FlashList`计算在滚动或初始加载列表期间用户可见的空白空间。
`onLoad`	一旦列表在屏幕上绘制了项目，就会引发事件。它还报告`elapsedTimeInMs`，即绘制项目所花费的时间。
`getItemType`	允许您指定项目类型。如果列表中有不同类型的项目，将改善再循环。
`overrideItemLayout`	用于提供明确的尺寸估计值或更改项目的列跨度。
`overrideProps`	建议仅用于调试。列表的内部属性由提供的值覆盖。

FlashList在后台使用ScrollView，这和FlatList一样，因此继承了其属性。

实现详情

并非React Native FlatList中支持的所有属性都在FlashList中有等效属性。请参见下面FlashList不支持的React Native属性列表。

不支持的属性
- columnWrapperStyle
- debug
- listKey
- onScrollToIndexFailed
- windowSize
不支持的方法
- flashScrollIndicators()
- hasMore
- getChildContext
- getNativeScrollRef()
- getScrollRef
- getScrollResponder()
由于底层实现的差异，在移植到FlashList时不会有任何作用的属性
- disableVirtualization
- getItemLayout
- initialNumToRender
- maxToRenderPerBatch
- recordInteraction
- setNativeProps
- updateCellsBatchingPeriod
Vega目前不支持的属性
- refreshControl
- refreshing

ItemItemSeparatorComponent已知问题 使用ItemItemSeparatorComponent时，在基于Perfetto轨迹进行滚动时，JS线程可能会出现问题。

key属性的使用

从React Native FlatList迁移到Flashlist时，您应该从项目组件及其嵌套组件中移除所有key属性。如果您使用key属性，FlashList无法再循环视图，这会移除Flashlist的性能优化。例如，下面的代码片段在Text和View组件中使用了key属性。

const MyNestedComponent = ({ item }) => {
  return <Text key={item.id}>我是嵌套项！</Text>;
};

const MyItem = ({ item }) => {
  return (
    <View key={item.id}>
      <MyNestedComponent item={item} />
      <Text>{item.title}</Text>
    </View>
  );
};

要优化Flashlist，请移除key属性，如下所示。

const MyNestedComponent = ({ item }) => {
  return <Text>我是嵌套项！</Text>;
};

const MyItem = ({ item }) => {
  return (
    <View>
      <MyNestedComponent item={item} />
      <Text>{item.title}</Text>
    </View>
  );
};

有关key属性的更多详细信息，请参阅Shopify文档（仅提供英文版）。

支持的版本

NPM程序包版本	Vega SDK版本	Vega OS版本	React Native版本
~2.0.0	0.23及更早版本	`OS 1.1 (1401010009820)`及更早版本	0.72
~2.0.9000000000	0.24	`OS 1.2 (2101020054720)`	0.83

其他资源

有关其他库的信息，请参阅支持的第三方库和服务。

​安装

​示例

​FlashList组件示例

​带有无限滚动功能的FlashList示例

​MasonryFlashList示例

​API参考

​组件

​属性

​实现详情

​key属性的使用

​支持的版本

​其他资源

安装

示例