From 4690274e16c3f70cd81bb4331b8a4a4f6cbeda13 Mon Sep 17 00:00:00 2001 From: Chanry Date: Fri, 30 Jan 2026 14:37:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20[Issues:=20#IDNCNU]=E4=BF=AE=E6=94=B9fl?= =?UTF-8?q?ash-list=E7=9A=84=E4=B8=AD=E8=8B=B1=E6=96=87=E6=8C=87=E5=AF=BC?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Chanry --- en/shopify-flash-list.md | 97 ++++++++++++++++++++++++++------- zh-cn/shopify-flash-list.md | 103 ++++++++++++++++++++++++++++-------- 2 files changed, 160 insertions(+), 40 deletions(-) diff --git a/en/shopify-flash-list.md b/en/shopify-flash-list.md index 5721184d..ad1bba80 100644 --- a/en/shopify-flash-list.md +++ b/en/shopify-flash-list.md @@ -18,11 +18,12 @@ Please refer to the Releases page of the third-party library for the corresponding version information -| Third-party Library Version | Release Information | Supported RN Version | -| ---------- | ------------------------------------------------------------ | ---------- | -| <= 1.6.3-0.2.9@deprecated | [@react-native-oh-tpl/flash-list Releases(deprecated)](https://github.com/react-native-oh-library/flash-list/releases) | 0.72 | -| 1.6.4 | [@react-native-ohos/flash-list Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.72 | -| 1.8.3 | [@react-native-ohos/flash-list Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.77 | +| Name | Version | Release Information | Supported RN Version | Supported Autolink | Compile API Version | Community Baseline Version | npm Address +| ------------ |--------|---------------------------------------------------------------------------------------------|----------------------|--------------------|---------|--------|----------------------------------| +|@react-native-ohos/flash-list| ~2.1.1 | [GitCode Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.82.* | 否 | API12+ | 2.1.0 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/flash-list)| +|@react-native-ohos/flash-list| ~1.8.3 | [GitCode Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.77.* | 否 | API12+ | 1.8.2 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/flash-list)| +|@react-native-ohos/flash-list| ~1.6.4 | [GitCode Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.72.* | 否 | API12+ | 1.6.3 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/flash-list) | +|@react-native-oh-tpl/flash-list| 1.6.3-0.2.9@deprecated | [Github Releases](https://github.com/react-native-oh-library/flash-list/releases) | 0.72 | 否 | API12+ | 1.6.3 | [Npm Address](https://www.npmjs.com/package/@react-native-oh-tpl/flash-list) | For older versions that are not published to npm, please refer to the [installation guide](/en/tgz-usage-en.md) to install the tgz package. @@ -63,7 +64,6 @@ const MyList = () => { {item.title}} - estimatedItemSize={200} /> ); }; @@ -73,6 +73,7 @@ const MyList = () => { | | Is supported autolink | Supported RN Version | |--------------------------------------|-----------------------|----------------------| +| ~2.1.1 | No | 0.82 | | ~1.8.3 | No | 0.77 | | ~1.6.4 | Yes | 0.72 | | <= 1.6.3-0.2.9@deprecated | No | 0.72 | @@ -99,6 +100,8 @@ First, use DevEco Studio to open the HarmonyOS project `harmony` in the project ### 2. Introducing Native Code +> [!TIP] version>=v2.1.1 does not involve native code and this step can be skipped. + Currently, two methods are available: @@ -214,6 +217,7 @@ Verified in the following versions. 1. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; 2. RNOH: 0.72.33; SDK: HarmonyOS NEXT B1; IDE: DevEco Studio: 5.0.3.900; ROM: Next.0.0.71; 3. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; +4. RNOH: 0.82.1; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM:6.0.0.130 SP8; ## Properties @@ -223,16 +227,16 @@ Verified in the following versions. | Name | Description | Type | Required | Platform | HarmonyOS Support | | ---- | ----------- | ---- | -------- | -------- | ------------------ | -| contentContainerStyle | You can use contentContainerStyle to apply padding that will be applied to the whole content itself. | ContentStyle | No | All | Yes | -| estimatedListSize | Estimated visible height and width of the list. It is not the scroll content size. Defining this prop will enable the list to be rendered immediately. Without it, the list first needs to measure its size, leading to a small delay during the first render. | object | No | All | Yes | +| contentContainerStyledeprecated from 2.1.1 | You can use contentContainerStyle to apply padding that will be applied to the whole content itself. | ContentStyle | No | All | Yes | +| estimatedListSizedeprecated from 2.1.1 | Estimated visible height and width of the list. It is not the scroll content size. Defining this prop will enable the list to be rendered immediately. Without it, the list first needs to measure its size, leading to a small delay during the first render. | object | No | All | Yes | | horizontal | If true, renders items next to each other horizontally instead of stacked vertically. Default is false. | boolean | No | All | Yes | | keyExtractor | Used to extract a unique key for a given item at the specified index. Key is used for optimizing performance. | function | No | All | Yes | | numColumns | Multiple columns can only be rendered with horizontal={false} and will zig-zag like a flexWrap layout. Items should all be the same height - masonry layouts are not supported. | number | No | All | Yes | | extraData | A marker property for telling the list to re-render (since it implements PureComponent) | any | No | All | Yes | | drawDistance | Draw distance for advanced rendering (in dp/px). | number | No | All | Yes | -| estimatedItemSize | estimatedItemSize is a single numeric value that hints FlashList about the approximate size of the items before they're rendered. | number | No | All | Yes | +| estimatedItemSizedeprecated from 2.1.1 | estimatedItemSize is a single numeric value that hints FlashList about the approximate size of the items before they're rendered. | number | No | All | Yes | | viewabilityConfig | viewabilityConfig is a default configuration for determining whether items are viewable. | object | No | All | Yes | -| renderItem | Takes an item from data and renders it into the list. | function | Yes | All | Yes | +| renderItemchanged in 2.1.1 | Takes an item from data and renders it into the list. In v2, the `Measurement` value in the `target` parameter is deprecated. | function | Yes | All | Yes | | data | For simplicity, data is a plain array of items of a given type. | ItemT[] | Yes | All | Yes | | CellRendererComponent | Each cell is rendered using this element. Can be a React Component Class, or a render function | JXS Element | No | All | Yes | | ListFooterComponent | Rendered at the bottom of all the items | JXS Element | No | All | Yes | @@ -243,26 +247,67 @@ Verified in the following versions. | onEndReachedThreshold | How far from the end (in units of visible length of the list) the bottom edge of the list must be from the end of the content to trigger the onEndReached callback | number | No | All | Yes | | onViewableItemsChanged | Called when the viewability of rows changes, as defined by the viewabilityConfig prop. | callback | No | All | Yes | | getItemType | Allows developers to specify item types. | function | No | All | Yes | -| overrideItemLayout | This method can be used to provide explicit size estimates or change column span of an item. | function | No | All | Yes | +| overrideItemLayoutchanged in 2.1.1 | Used to change item column span. In v1, supports both `layout.span` and `layout.size`; in v2, only `layout.span` is supported, size estimates are no longer read. | function | No | All | Yes | | ItemSeparatorComponent | Rendered in between each item, but not at the top or bottom. | JXS Element | No | All | Yes | | ListEmptyComponent | Rendered when the list is empty | JXS Element | No | All |Yes | | ListFooterComponentStyle | Styling for internal View for ListFooterComponent. | React.ComponentType | No | All | Yes | | ListHeaderComponentStyle | Styling for internal View for ListHeaderComponent. | StyleProp | No | All | Yes | -| disableAutoLayout | FlashList applies some fixes to layouts of its children which can conflict with custom CellRendererComponent implementations. You can disable this behavior by setting this to true. | boolean | No | All | Yes | -| disableHorizontalListHeightMeasurement | When set to true the list's rendered size needs to be deterministic (i.e., height and width greater than 0) as FlashList will skip rendering the extra item for measurement. Default value is false. | boolean | No | All | Yes | -| estimatedFirstItemOffset | estimatedFirstItemOffset specifies how far the first item is drawn from start of the list window or offset of the first item of the list (not the header). | number | No | All | Yes | +| disableAutoLayoutdeprecated from 2.1.1 | FlashList applies some fixes to layouts of its children which can conflict with custom CellRendererComponent implementations. You can disable this behavior by setting this to true. | boolean | No | All | Yes | +| disableHorizontalListHeightMeasurementdeprecated from 2.1.1 | When set to true the list's rendered size needs to be deterministic (i.e., height and width greater than 0) as FlashList will skip rendering the extra item for measurement. Default value is false. | boolean | No | All | Yes | +| estimatedFirstItemOffsetdeprecated from 2.1.1 | estimatedFirstItemOffset specifies how far the first item is drawn from start of the list window or offset of the first item of the list (not the header). | number | No | All | Yes | | initialScrollIndex | Instead of starting at the top with the first item, start at initialScrollIndex | number | No | All | Yes | -| inverted | Reverses the direction of scroll. Uses scale transforms of -1. | boolean | No | All | Yes | -| onBlankArea | FlashList computes blank space that is visible to the user during scrolling or the initial loading of the list. | callback | No | All | Yes | +| inverteddeprecated from 2.1.1 | Reverses the direction of scroll. Uses scale transforms of -1. | boolean | No | All | Yes | +| onBlankAreadeprecated from 2.1.1 | FlashList computes blank space that is visible to the user during scrolling or the initial loading of the list. | callback | No | All | Yes | | onLoad | This event is raised once the list has drawn items on the screen. | callback | No | All | Yes | | onRefresh | If provided, a standard RefreshControl will be added for "Pull to Refresh" functionality. Make sure to also set the refreshing prop correctly. | callback | No | All | Yes | | onScroll | Fires at most once per frame during scrolling. Inherited from ScrollView. | callback | No | All | Yes | | overrideProps | We do not recommend using this prop for anything else than debugging. Internal props of the list will be overriden with the provided values. | object | No | All | Yes | -| progressViewOffset | Set this when offset is needed for the loading indicator to show correctly. | number | No | All | Yes | +| progressViewOffset | Set this when offset is needed for the loading indicator to show correctly. | number | No | Android | Yes | | refreshing | Set this true while waiting for new data from a refresh. | boolean | No | All | Yes | | viewabilityConfigCallbackPairs | List of ViewabilityConfig/onViewableItemsChanged pairs. A specific onViewableItemsChanged will be called when its corresponding ViewabilityConfig's conditions are met. | object | No | All | Yes | +| ContentStyledeprecated from 2.1.1 | Type for defining the style of the list content container | object | No | All | Yes | +| CellContainerdeprecated from 2.1.1 | Cell container component | React.Component | No | All | Yes | +| useOnNativeBlankAreaEventsdeprecated from 2.1.1 | Hook for listening to native blank area events, triggers callback when blank areas appear in the list | function | No | All | Yes | +| BlankAreaEventHandlerdeprecated from 2.1.1 | Type for blank area event handler function | function | No | All | Yes | +| BlankAreaEventdeprecated from 2.1.1 | Blank area event object | object | No | All | Yes | +| useBlankAreaTrackerdeprecated from 2.1.1 | Hook for tracking visible blank areas in the list for production environments | function | No | All | Yes | +| BlankAreaTrackerResultdeprecated from 2.1.1 | Blank area tracker result object | object | No | All | Yes | +| BlankAreaTrackerConfigdeprecated from 2.1.1 | Configuration options for the blank area tracker | object | No | All | Yes | +| MasonryFlashListdeprecated from 2.1.1 | Masonry (waterfall) layout variant of FlashList component | React.Component | No | All | Yes | +| MasonryFlashListPropsdeprecated from 2.1.1 | Props type for the masonry list component | object | No | All | Yes | +| MasonryFlashlistScrollEventdeprecated from 2.1.1 | Scroll event type for masonry list | object | No | All | Yes | +| MasonryFlashListRefdeprecated from 2.1.1 | Ref type for masonry list | object | No | All | Yes | +| MasonryListItemdeprecated from 2.1.1 | Wrapper type for masonry list item | object | No | All | Yes | +| MasonryListRenderItemdeprecated from 2.1.1 | Render function type for masonry list item | function | No | All | Yes | +| MasonryListRenderItemInfodeprecated from 2.1.1 | Render info for masonry list item | object | No | All | Yes | +| FlashListRef 2.1.1| Provides a reference to the FlashList instance, enabling direct list manipulation. | React.RefObject> | No | All | Yes | +| onStartReached2.1.1| Callback triggered once when the scroll position gets close to the content start position. | callback | No | All | Yes | +| onStartReachedThreshold2.1.1| Threshold distance between the top edge of the list and the content start position (in units of visible length of the list) when triggering the onStartReached callback. | number | No | All | Yes | +| maintainVisibleContentPosition2.1.1| Configuration for maintaining scroll position when content changes. Supports configuring sub-properties like `disabled`, `autoscrollToTopThreshold`, `autoscrollToBottomThreshold`, `animateAutoScrollToBottom`, and `startRenderingFromBottom`. | object | No | All | Yes | +| masonry2.1.1| Enable masonry (waterfall) layout mode. | boolean | No | All | Yes | +| maxItemsInRecyclePool2.1.1| Maximum number of items cached in the recycle pool. Items are cached in the recycle pool when scrolled off-screen. Setting to 0 will disable the recycle pool, and items will be unmounted directly after scrolling off-screen. | number | No | All | Yes | +| onCommitLayoutEffect2.1.1| Callback invoked when layout commit is complete. | function | No | All | Yes | +| LayoutCommitObserver2.1.1| Component for observing when FlashList commits layout. | React.Component | No | All | Yes | +| LayoutCommitObserverProps2.1.1| Define the properties of LayoutCommitObserver, including the callback function. | object | No | All | Yes | +| initialScrollIndexParams2.1.1| Additional configuration for `initialScrollIndex`. Use `viewOffset` to apply an offset to the initial scroll position. Only takes effect when `initialScrollIndex` is set. | object | No | All | Yes | +| optimizeItemArrangement2.1.1| When enabled, MasonryFlashList will reduce column height differences by adjusting item order. Only available in masonry layout mode. | boolean | No | All | Yes | +| style2.1.1| Style for the RecyclerView parent container. | StyleProp | No | All | Yes | +| props2.1.1 | Get access to current props. | RecyclerViewProps | No | All | Yes | + +## HOOKS + +> [!TIP] The **Platform** column indicates the platform where the properties are supported in the original third-party library. + +> [!TIP] If the value of **HarmonyOS Support** is **yes**, it means that the HarmonyOS platform supports this property; **no** means the opposite; **partially** means some capabilities of this property are supported. The usage method is the same on different platforms and the effect is the same as that of iOS or Android. + +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| ---- | ----------- | ---- | -------- | -------- | ------------------ | +| useLayoutState2.1.1| A custom Hook that combines state management with RecyclerView layout updates. State changes automatically trigger layout recalculation. Returns the current state value and a setter function that optionally skips parent layout updates. | Hook | No | All | Yes | +| useRecyclingState2.1.1| A state management Hook with automatic reset functionality. Similar to useState, but automatically resets state when specified dependencies change. Useful for scenarios where state needs to be reset during item recycling, avoiding extra setState calls and improving performance. | Hook | No | All | Yes | +| useMappingHelper2.1.1| Returns a helper function for creating mapping keys. Used when performing .map operations on items to create component lists. | Hook | No | All | Yes | +| useFlashListContext2.1.1| Hook for accessing the current FlashList context. Provides access to methods like `layout()`, `getRef()`, `getParentRef()`, `getScrollViewRef()`, and `getParentScrollViewRef()`. | Hook | No | All | Yes | -## Static Methods +## Methods > [!TIP] The **Platform** column indicates the platform where the properties are supported in the original third-party library. @@ -276,10 +321,24 @@ Verified in the following versions. | scrollToIndex | Scroll to a given index. | function | No | All | Yes | | scrollToItem | Scroll to a given item. | function | No | All | Yes | | scrollToOffset | Scroll to a specific content pixel offset in the list. | function | No | All | Yes | -| recomputeViewableItems1.8.2 | Retriggers viewability calculations. Useful to imperatively trigger viewability calculations. | function | No | All | Yes | +| recomputeViewableItems1.8.3 2.1.1 | Retriggers viewability calculations. Useful to imperatively trigger viewability calculations. | function | No | All | Yes | +| getLayout | Gets layout information for the item at the specified index, including x, y coordinates and dimensions. Returns an RVLayout object. | function | No | All | Yes | +| getChildContainerDimensions | Returns the dimensions of the child container, containing `width` and `height` properties. | function | No | All | Yes | +| getScrollableNode | Returns the underlying scrollable node. | function | No | All | Yes | +| getFirstItemOffset | Returns the offset of the first item (including header/padding). | function | No | All | Yes | +| getWindowSize | Returns the current viewport dimensions, containing `width` and `height` properties. | function | No | All | Yes | +| getFirstVisibleIndex | Returns the index of the first visible item. | function | No | All | Yes | +| getAbsoluteLastScrollOffset | Returns the absolute offset of the last scroll. | function | No | All | Yes | +| clearLayoutCacheOnUpdate | Clears the layout cache on update. | function | No | All | Yes | +| computeVisibleIndices2.1.1 | Returns the index range of currently visible items, containing `startIndex` and `endIndex` properties. | function | No | All | Yes | +| flashScrollIndicators2.1.1 | Briefly flashes the scroll indicators. | function | No | All | Yes | +| getNativeScrollRef2.1.1 | Returns the underlying native scroll view reference. | function | No | All | Yes | +| getScrollResponder2.1.1 | Returns the scroll responder reference. | function | No | All | Yes | +| scrollToTop2.1.1 | Scrolls to the top (or start position) of the list. Supports the `animated` parameter to control whether to use animation. | function | No | All | Yes | ## Known Issues +- [ ] RNOH's `maintainVisibleContentPosition` implementation does not account for FlashList's element recycling mechanism, causing list scrolling jumps.[Issue#19](https://gitcode.com/openharmony-sig/rntpc_flash-list/issues/19) ## Others ## License diff --git a/zh-cn/shopify-flash-list.md b/zh-cn/shopify-flash-list.md index e04bd9b4..d9f3ff1b 100644 --- a/zh-cn/shopify-flash-list.md +++ b/zh-cn/shopify-flash-list.md @@ -18,11 +18,12 @@ 请到三方库的 Releases 发布地址查看配套的版本信息： -| 三方库版本 | 发布信息 | 支持RN版本 | -|--------| ------------------------------------------------------------ | ---------- | -| <= 1.6.3-0.2.9@deprecated | [@react-native-oh-tpl/flash-list Releases(deprecated)](https://github.com/react-native-oh-library/flash-list/releases) | 0.72 | -| 1.6.4 | [@react-native-ohos/flash-list Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.72 | -| 1.8.3 | [@react-native-ohos/flash-list Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.77 | +| 三方库名称 | 三方库版本 | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | npm地址 +| ------------ |--------|---------------------------------------------------------------------------------------------|----------------------|--------------------|---------|--------|----------------------------------| +|@react-native-ohos/flash-list| ~2.1.1 | [GitCode Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.82.* | 否 | API12+ | 2.1.0 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/flash-list)| +|@react-native-ohos/flash-list| ~1.8.3 | [GitCode Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.77.* | 否 | API12+ | 1.8.2 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/flash-list)| +|@react-native-ohos/flash-list| ~1.6.4 | [GitCode Releases](https://gitcode.com/openharmony-sig/rntpc_flash-list/releases) | 0.72.* | 否 | API12+ | 1.6.3 | [Npm Address](https://www.npmjs.com/package/@react-native-ohos/flash-list) | +|@react-native-oh-tpl/flash-list| 1.6.3-0.2.9@deprecated | [Github Releases](https://github.com/react-native-oh-library/flash-list/releases) | 0.72 | 否 | API12+ | 1.6.3 | [Npm Address](https://www.npmjs.com/package/@react-native-oh-tpl/flash-list) | 对于未发布到npm的旧版本，请参考[安装指南](/zh-cn/tgz-usage.md)安装tgz包。 @@ -63,7 +64,6 @@ const MyList = () => { {item.title}} - estimatedItemSize={200} /> ); }; @@ -73,6 +73,7 @@ const MyList = () => { | | 是否支持autolink | RN框架版本 | |--------------------------------------|-----------------|------------| +| ~2.1.1 | No | 0.82 | | ~1.8.3 | No | 0.77 | | ~1.6.4 | Yes | 0.72 | | <= 1.6.3-0.2.9@deprecated | No | 0.72 | @@ -100,6 +101,8 @@ const MyList = () => { ### 2.引入原生端代码 +> [!TIP] version>=v2.1.1不涉及原生端代码，可跳过此步骤。 + 目前有两种方法： 1. 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）； @@ -217,6 +220,7 @@ ohpm install 1. RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; 2. RNOH: 0.72.33; SDK: HarmonyOS NEXT B1; IDE: DevEco Studio: 5.0.3.900; ROM: Next.0.0.71; 3. RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112; +4. RNOH: 0.82.1; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM:6.0.0.130 SP8; ## 属性 @@ -226,16 +230,16 @@ ohpm install | Name | Description | Type | Required | Platform | HarmonyOS Support | | ---- | ----------- | ---- | -------- | -------- | ------------------ | -| contentContainerStyle | 可通过 contentContainerStyle 为整个内容区域设置内边距。 | ContentStyle | No | All | Yes | -| estimatedListSize | 列表的预估可见高度和宽度（非滚动内容尺寸）。定义该属性可让列表立即渲染，否则列表需先测量自身尺寸，导致首次渲染稍有延迟。 | object | No | All | Yes | +| contentContainerStyledeprecated from 2.1.1 | 可通过 contentContainerStyle 为整个内容区域设置内边距。 | ContentStyle | No | All | Yes | +| estimatedListSizedeprecated from 2.1.1 | 列表的预估可见高度和宽度（非滚动内容尺寸）。定义该属性可让列表立即渲染，否则列表需先测量自身尺寸，导致首次渲染稍有延迟。 | object | No | All | Yes | | horizontal | 设置为 true 时，项目将水平并列排列而非垂直堆叠。默认为 false。 | boolean | No | All | Yes | | keyExtractor | 用于为指定索引位置的项生成唯一键值。键值用于优化性能。 | function | No | All | Yes | -| numColumns | Multiple columns can only be rendered with horizontal={false} and will zig-zag like a flexWrap layout. Items should all be the same height - masonry layouts are not supported. | number | No | All | Yes | +| numColumns | 多列布局只能在 horizontal={false} 的情况下渲染，并且会像 flexWrap 布局一样呈现“之”字形排列。所有子项的高度必须一致——不支持瀑布流（masonry）布局。 | number | No | All | Yes | | extraData | 用于指示列表重新渲染的标记属性（因列表实现为 PureComponent）。 | any | No | All | Yes | | drawDistance | 预渲染的绘制距离。 | number | No | All | Yes | -| estimatedItemSize | 用于在项目渲染前向 FlashList 提示项目近似尺寸的单个数值。 | number | No | All | Yes | +| estimatedItemSizedeprecated from 2.1.1 | 用于在项目渲染前向 FlashList 提示项目近似尺寸的单个数值。 | number | No | All | Yes | | viewabilityConfig | 用于判定项目可见性的默认配置。 | object | No | All | Yes | -| renderItem | 从 data 中获取项目并渲染至列表 | function | Yes | All | Yes | +| renderItemchanged in 2.1.1 | 从 data 中获取项目并渲染至列表。v2 版本中 `target` 参数的 `Measurement` 值已弃用。 | function | Yes | All | Yes | | data | 数据源，为指定类型的简单项目数组。 | ItemT[] | Yes | All | Yes | | CellRendererComponent | 每个单元格的渲染元素。可以是 React 类组件或渲染函数。 | JXS Element | No | All | Yes | | ListFooterComponent | 在列表底部渲染的组件。 | JXS Element | No | All | Yes | @@ -243,29 +247,71 @@ ohpm install | refreshControl | 自定义下拉刷新控件元素。 | JXS Element | No | All | Yes | | renderScrollComponent | 作为主滚动视图渲染的组件。 | JXS Element | No | All | Yes | | onEndReached | 当滚动位置接近渲染内容末尾（距离阈值为 onEndReachedThreshold）时触发一次 。 | callback | No | All | Yes | -| onEndReachedThreshold | 触发 onEndReached 回调时，列表底部边缘与内容末尾的距离阈值（以列表可见长度为单位。 | number | No | All | Yes | +| onEndReachedThreshold | 触发 onEndReached 回调时，列表底部边缘与内容末尾的距离阈值（以列表可见长度为单位。） | number | No | All | Yes | | onViewableItemsChanged | 当项目的可见性发生变化时触发（可见性由 viewabilityConfig 属性定义）。 | callback | No | All | Yes | | getItemType | 允许开发者指定项目类型。 | function | No | All | Yes | -| overrideItemLayout | 用于显式指定项目尺寸估算值或更改项目列跨度。 | function | No | All | Yes | +| overrideItemLayoutchanged in 2.1.1 | 用于更改项目列跨度。v1 版本支持设置 `layout.span` 和 `layout.size`；v2 版本仅支持 `layout.span`，不再读取尺寸估算值。 | function | No | All | Yes | | ItemSeparatorComponent | 在每项之间（不包括顶部和底部）渲染的分隔组件。 | JXS Element | No | All | Yes | | ListEmptyComponent | 列表为空时渲染的组件。 | JXS Element | No | All |Yes | | ListFooterComponentStyle | 列表底部组件内部容器的样式。 | React.ComponentType | No | All | Yes | | ListHeaderComponentStyle | 列表顶部组件内部容器的样式。 | StyleProp | No | All | Yes | -| disableAutoLayout | FlashList 会对子项布局应用某些修复，这可能与自定义 CellRendererComponent 实现冲突。设置为 true 可禁用此行为。 | boolean | No | All | Yes | -| disableHorizontalListHeightMeasurement | 设置为 true 时，列表的渲染尺寸需确定（即高度和宽度大于0），FlashList 将跳过用于测量的额外项目渲染。默认值为 false。 | boolean | No | All | Yes | -| estimatedFirstItemOffset | 指定列表窗口中首个项目的绘制偏移量（非列表头部偏移量）。 | number | No | All | Yes | +| disableAutoLayoutdeprecated from 2.1.1 | FlashList 会对子项布局应用某些修复，这可能与自定义 CellRendererComponent 实现冲突。设置为 true 可禁用此行为。 | boolean | No | All | Yes | +| disableHorizontalListHeightMeasurementdeprecated from 2.1.1 | 设置为 true 时，列表的渲染尺寸需确定（即高度和宽度大于0），FlashList 将跳过用于测量的额外项目渲染。默认值为 false。 | boolean | No | All | Yes | +| estimatedFirstItemOffsetdeprecated from 2.1.1 | 指定列表窗口中首个项目的绘制偏移量（非列表头部偏移量）。 | number | No | All | Yes | | initialScrollIndex | 不从首项开始显示，而是从 initialScrollIndex 指定位置开始。 | number | No | All | Yes | -| inverted | 反转滚动方向（使用 -1 缩放变换实现）。 | boolean | No | All | Yes | -| onBlankArea | 滚动或列表初始加载时，FlashList 会计算用户可见的空白区域。 | callback | No | All | Yes | +| inverteddeprecated from 2.1.1 | 反转滚动方向（使用 -1 缩放变换实现）。 | boolean | No | All | Yes | +| onBlankAreadeprecated from 2.1.1 | 滚动或列表初始加载时，FlashList 会计算用户可见的空白区域。 | callback | No | All | Yes | | onLoad | 当列表在屏幕上完成项目绘制后触发。 | callback | No | All | Yes | | onRefresh | 提供此回调可添加标准 RefreshControl 实现"下拉刷新"功能。需确保同时正确设置 refreshing 属性。 | callback | No | All | Yes | | onScroll | 滚动期间每帧最多触发一次（继承自 ScrollView）。 | callback | No | All | Yes | | overrideProps | 除调试外不建议使用此属性。列表的内部属性将被提供值覆盖。 | object | No | All | Yes | -| progressViewOffset | 当加载指示器需要偏移量时才需设置此属性。 | number | No | All | Yes | +| progressViewOffset | 当加载指示器需要偏移量时才需设置此属性。 | number | No | Android | Yes | | refreshing | 在等待刷新数据时设置为 true。 | boolean | No | All | Yes | | viewabilityConfigCallbackPairs | ViewabilityConfig/onViewableItemsChanged 配置对集合。当对应 ViewabilityConfig 的条件满足时，会触发特定的 onViewableItemsChanged 回调 。 | object | No | All | Yes | +| ContentStyledeprecated from 2.1.1 | 用于定义列表内容容器样式的类型 | object | No | All | Yes | +| CellContainerdeprecated from 2.1.1 | 单元格容器组件 | React.Component | No | All | Yes | +| useOnNativeBlankAreaEventsdeprecated from 2.1.1 | 用于监听原生空白区域事件的 Hook，当列表出现空白区域时触发回调 | function | No | All | Yes | +| BlankAreaEventHandlerdeprecated from 2.1.1 | 空白区域事件处理函数类型 | function | No | All | Yes | +| BlankAreaEventdeprecated from 2.1.1 | 空白区域事件对象 | object | No | All | Yes | +| useBlankAreaTrackerdeprecated from 2.1.1 | 用于在生产环境中追踪列表可见空白区域的 Hook | function | No | All | Yes | +| BlankAreaTrackerResultdeprecated from 2.1.1 | 空白区域追踪结果对象 | object | No | All | Yes | +| BlankAreaTrackerConfigdeprecated from 2.1.1 | 空白区域追踪器配置项 | object | No | All | Yes | +| MasonryFlashListdeprecated from 2.1.1 | 瀑布流布局的 FlashList 变体组件 | React.Component | No | All | Yes | +| MasonryFlashListPropsdeprecated from 2.1.1 | 瀑布流列表组件的属性类型 | object | No | All | Yes | +| MasonryFlashlistScrollEventdeprecated from 2.1.1 | 瀑布流列表的滚动事件类型 | object | No | All | Yes | +| MasonryFlashListRefdeprecated from 2.1.1 | 瀑布流列表的 Ref 类型 | object | No | All | Yes | +| MasonryListItemdeprecated from 2.1.1 | 瀑布流列表项的包装类型 | object | No | All | Yes | +| MasonryListRenderItemdeprecated from 2.1.1 | 瀑布流列表项渲染函数类型 | function | No | All | Yes | +| MasonryListRenderItemInfodeprecated from 2.1.1 | 瀑布流列表项渲染信息 | object | No | All | Yes | +| FlashListRef 2.1.1| 提供对FlashList实例的引用，支持直接操作列表 | React.RefObject> | No | All | Yes | +| onStartReached2.1.1| 当滚动位置接近内容起始位置时触发一次的回调。 | callback | No | All | Yes | +| onStartReachedThreshold2.1.1| 触发 onStartReached 回调时，列表顶部边缘与内容起始位置的距离阈值（以列表可见长度为单位）。 | number | No | All | Yes | +| maintainVisibleContentPosition2.1.1| 用于在内容变化时维持滚动位置的配置。支持配置 `disabled`、`autoscrollToTopThreshold`、`autoscrollToBottomThreshold`、`animateAutoScrollToBottom` 和 `startRenderingFromBottom` 等子属性。 | object | No | All | Yes | +| masonry2.1.1| 启用瀑布流布局模式。 | boolean | No | All | Yes | +| maxItemsInRecyclePool2.1.1| 回收池中缓存的最大项目数。当项目滚动出屏幕时会被缓存在回收池中。设置为 0 将禁用回收池，项目滚出屏幕后将直接卸载。 | number | No | All | Yes | +| onCommitLayoutEffect2.1.1| 当布局提交完成时调用的回调。 | function | No | All | Yes | +| LayoutCommitObserver2.1.1| 用于观察 FlashList 何时提交布局的组件。 | React.Component | No | All | Yes | +| LayoutCommitObserverProps2.1.1| 定义Layoutcommitobserver的属性接口，包含回调函数 | object | No | All | Yes | +| initialScrollIndexParams2.1.1| `initialScrollIndex` 的附加配置。可使用 `viewOffset` 对初始滚动位置应用偏移量。仅当设置了 `initialScrollIndex` 时生效。 | object | No | All | Yes | +| optimizeItemArrangement2.1.1| 启用后，MasonryFlashList 将通过调整项目顺序来减少列高差异。仅在瀑布流布局下可用。 | boolean | No | All | Yes | +| style2.1.1| RecyclerView 父容器的样式。 | StyleProp | No | All | Yes | +| props2.1.1 | 获取当前列表的 props 配置。 | RecyclerViewProps\ | No | All | Yes | + + + +## HOOKS +> [!TIP] "Platform"列表示该属性在原三方库上支持的平台。 + +> [!TIP] "HarmonyOS Support"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。 -## 静态方法 +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| ---- | ----------- | ---- | -------- | -------- | ------------------ | +| useLayoutState2.1.1| 将状态管理与 RecyclerView 布局更新结合的自定义 Hook。状态变化时会自动触发布局重新计算。返回当前状态值和一个可选择性跳过父布局更新的 setter 函数。 | Hook | No | All | Yes | +| useRecyclingState2.1.1| 提供自动重置功能的状态管理 Hook。类似 useState，但在指定依赖项变化时会自动重置状态。适用于项目回收时需要重置状态的场景，避免额外的 setState 调用并提升性能。 | Hook | No | All | Yes | +| useMappingHelper2.1.1| 返回一个帮助创建映射键的函数。在对项目进行 .map 操作创建组件列表时使用。 | Hook | No | All | Yes | +| useFlashListContext2.1.1| 获取当前 FlashList 上下文的 Hook。可访问 `layout()`、`getRef()`、`getParentRef()`、`getScrollViewRef()` 和 `getParentScrollViewRef()` 等方法。 | Hook | No | All | Yes | + +## 方法 > [!TIP] "Platform"列表示该属性在原三方库上支持的平台。 @@ -279,10 +325,25 @@ ohpm install | scrollToIndex | 滚动至指定索引位置。 | function | No | All | Yes | | scrollToItem | 滚动至指定项目。 | function | No | All | Yes | | scrollToOffset | 滚动至列表内特定的内容像素偏移量。 | function | No | All | Yes | -| recomputeViewableItems1.8.3 | 重新触发可见性计算。适用于需要强制触发可见性计算的场景。 | function | No | All | Yes | +| recomputeViewableItems1.8.3 2.1.1 | 重新触发可见性计算。 | function | No | All | Yes | +| getLayout | 获取指定索引项目的布局信息，包括 x、y 坐标和宽高等。返回 RVLayout 对象。 | function | No | All | Yes | +| getChildContainerDimensions | 返回子容器的尺寸，包含 `width` 和 `height` 属性。 | function | No | All | Yes | +| getScrollableNode | 返回底层可滚动节点。 | function | No | All | Yes | +| getFirstItemOffset | 返回第一个项目的偏移量（包含头部/内边距）。 | function | No | All | Yes | +| getWindowSize | 返回当前视口尺寸，包含 `width` 和 `height` 属性。 | function | No | All | Yes | +| getFirstVisibleIndex | 返回第一个可见项目的索引。 | function | No | All | Yes | +| getAbsoluteLastScrollOffset | 返回最后一次滚动的绝对偏移量。 | function | No | All | Yes | +| clearLayoutCacheOnUpdate | 在更新时清除布局缓存。 | function | No | All | Yes | +| computeVisibleIndices2.1.1 | 返回当前可见项目的索引范围，包含 `startIndex` 和 `endIndex` 属性。 | function | No | All | Yes | +| flashScrollIndicators2.1.1 | 使滚动指示器短暂闪烁显示。 | function | No | All | Yes | +| getNativeScrollRef2.1.1 | 返回底层原生滚动视图引用。 | function | No | All | Yes | +| getScrollResponder2.1.1 | 返回滚动响应器引用。 | function | No | All | Yes | +| scrollToTop2.1.1 | 滚动至列表顶部（或起始位置）。支持 `animated` 参数控制是否使用动画。 | function | No | All | Yes | ## 遗留问题 +- [ ] RNOH 的 `maintainVisibleContentPosition` 实现未考虑 FlashList 元素复用机制，导致列表滑动时出现跳跃。[Issue#19](https://gitcode.com/openharmony-sig/rntpc_flash-list/issues/19) + ## 其他 ## 开源协议 -- Gitee