Console

Settings

Sign out

Notifications

Alexa

亚马逊应用商店

AWS

文档

Support

My Cases

Console

Vega开发者文档

主页

新手入门

设计和开发

应用发布

参考

支持

shopify-flash-list

开放Beta测试文档 作为预发布开放Beta测试的一项内容，亚马逊提供了此技术文档。随着亚马逊收到反馈并对功能进行迭代，所描述的这些功能可能会发生变化。有关最新功能的信息，请参阅发布说明。

@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的库的版本。

安装
示例
API参考
- 组件
- 属性
实现详情
- key属性的使用
支持的版本
其他资源

安装

在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`	添加对`FlashList`的`Animated` 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 OS内部版本号	Vega SDK版本	发布说明
`@amazon-devices/shopify__flash-list`	2.0.1+1.6.3	`OS 1.1 (201010438050)`	0.20

其他资源

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

Last updated: 2025年10月3日