shopify-flash-list

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

安装

在package.json文件中添加JavaScript库依赖项。

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

使用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

ItemSeparatorComponent已知问题

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

`key`属性的使用

如果您使用key属性，FlashList无法再循环视图，这会移除Flashlist的性能优化。因此，从React Native FlatList迁移到Flashlist时，您应该从项目组件及其嵌套组件中移除所有key属性。例如，下面的代码片段在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 OS内部版本号	Vega SDK版本	发布说明
`@amazon-devices/shopify__flash-list`	2.0.1+1.6.3	`OS 1.1 (201010438050)`	0.20

Vega 库和服务

安装

示例

FlashList组件示例

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

MasonryFlashList示例

API参考

组件

属性

已知问题和限制

ItemSeparatorComponent已知问题

`key`属性的使用

支持的版本

相关主题

​安装

​示例

​FlashList组件示例

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

​MasonryFlashList示例

​API参考

​组件

​属性

​已知问题和限制

​ItemSeparatorComponent已知问题

​key属性的使用

​支持的版本

​相关主题

安装

示例

FlashList组件示例

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

MasonryFlashList示例

API参考

组件

属性

已知问题和限制

ItemSeparatorComponent已知问题

`key`属性的使用

支持的版本

相关主题