`<list>`

<list> 组件是一个高性能的可滚动容器，通过元素回收和懒加载机制优化性能和内存使用。它支持横向和纵向滚动，可实现单列、网格和瀑布流布局，非常适合无限滚动的信息流等应用场景。

使用指南

单列布局

1. 设置宽高：<list> 的宽高代表了其可视区域的大小，因此需要是确定的值，不能由内部内容撑开，只有在可视区域内可见的子节点才会被渲染。

2. 设置滚动方向与布局形式：设置属性 scroll-orientation 指定布局与滚动方向，设置 list-type 与 span-count 指定布局形式。

3. 配置子节点：使用标签 <list-item> 作为 <list> 直接子节点，并且给 <list-item> 设置 item-key 与 key，并且需要保持一致。

多列布局

1. 设置布局方式与列数: 设置布局形式 list-type 为 flow (网格布局) 或者 waterfall (瀑布流布局)，并设置 span-count >= 2。

2. 多列布局下实现独占一行的子节点: 为 <list-item/> 设置 full-span 属性，可以使其在布局中独占一行或者一列。

网格布局案例：

瀑布流布局示例

List 相关 CSS 属性

Note

List 相关 CSS 属性是专门为 <list> 组件设计的，例如 list-main-axis-gap 和 list-cross-axis-gap，可以对 <list> 内元素的布局和间距进行精细控制。需要注意的是，这些属性只在 <list> 上生效，在其他任何组件上都将被忽略。

`list-main-axis-gap`

// DefaultValue: null
list-main-axis-gap?: ${number}px | ${number}rpx

<list
  style={{listMainAxisGap:'10px'}}
/>

指定了在主轴方向上，<list> 子节点的间距，需要写在 style 中。

`list-cross-axis-gap`

// DefaultValue: null
list-cross-axis-gap?: ${number}px | ${number}rpx

<list
  style={{listCrossAxisGap:'10px'}}
/>

指定了在副轴方向上，<list> 子节点的间距，需要写在 style 中。

属性

`list-type` Required

list-type: 'single' | 'flow' | 'waterfall'

控制 <list> 组件的布局类型，需要与 span-count 配合使用。

值	说明
`single`	单列/单行布局
`flow`	多列/多行网格布局。网格布局会充分体现其归整性，左右两列中，相邻位置子节点的 `top` 是一致的，因此使用场景通常为大小一致的子节点。子节点宽度由 `<list>` 的宽度和 `span-count` 决定
`waterfall`	多列/多行瀑布流布局。内容是连续填充的，子节点元件是从上到下填充到最短的列，实现视觉上的连续和动态性，因此使用场景通常为大小不一致的子节点。子节点宽度由 `<list>` 的宽度和 `span-count` 决定

你可以通过查看多列布局指南中的真实案例更清晰地看出 flow 和 waterfall 的布局差异。

`span-count` Required

span-count: number

设置 <list> 组件的布局列数或者行数。

`scroll-orientation` Required

// DefaultValue: "vertical"
scroll-orientation?: 'vertical' ｜ 'horizontal'

设置 <list> 组件的滚动方向与布局方向。

`item-key` Required

// DefaultValue: null
item-key: string

<list-item item-key="item"/>

item-key 是 <list-item> 上必须传入的属性。

Note

开发者需要为每一个 <list> 子节点设置唯一的 item-key，其会被用来帮助 <list> 识别哪些 <list> 子节点已更改、添加或删除。因此开发者需要保证正确设置 item-key，如设置有误，将会导致错乱、闪动问题。

`key` Required

// DefaultValue: null
key: string

<list-item
  item-key="item-0"
  key="item-0"
/>

使用 key 属性来帮助框架识别哪些元件已更改、添加或删除。

Note

在 list 场景下，key 和 item-key 保持一致。

`enable-scroll`

// DefaultValue: true
enable-scroll?: boolean

是否允许 <list> 组件滚动。

`enable-nested-scroll`

// DefaultValue: true
enable-nested-scroll?: boolean

是否允许 <list> 与其他滚动容器实现嵌套滚动，开启后先滚动内层容器，再滚动外层容器。

`sticky`

// DefaultValue: false
sticky?: boolean

声明在 <list> 组件上，控制 <list> 组件整体是否允许吸顶或者吸底。

`sticky-offset`

// DefaultValue: 0
sticky-offset?: number

吸顶或者吸底位置距离 <list> 顶部或者底部的偏移，单位为 px。

`sticky-top`

// DefaultValue: false
sticky-top?: boolean

声明在子节点 <list-item> 上，控制该节点是否会吸顶。

`sticky-bottom`

// DefaultValue: false
sticky-bottom?: boolean

声明在子节点 <list-item> 上，控制该节点是否会吸底。

`recyclable`

// DefaultValue: true
recyclable?: boolean

"dependencies": {
  "@lynx-js/react": "^0.112.2"
}

声明在子节点 <list-item> 上，控制该节点是否会被回收，如果 recyclable 设置为 false，则 <list-item> 被滑出 <list> 可视区域后不会被回收。

`bounces`

// DefaultValue: true
bounces?: boolean

开启边缘回弹效果。

`initial-scroll-index`

// DefaultValue: 0
initial-scroll-index?: number

指定 <list> 在渲染后自动定位到的节点位置，仅首次生效。

`need-visible-item-info`

// DefaultValue: false
need-visible-item-info?: boolean

控制滚动事件回调参数中是否包含当前正在渲染节点的位置信息，这里滚动事件包含：scroll，scrolltoupper，scrolltolower。

滚动事件回调参数格式：

interface ListScrollInfo {
  // 距上次滚动的横向滚动偏移量，单位 px
  deltaX: number;
  // 距上次滚动的纵向滚动偏移量，单位 px
  deltaY: number;
  // 当前横向滚动偏移量，单位 px
  scrollLeft: number;
  // 当前纵向滚动偏移量，单位 px
  scrollTop: number;
  // 当前内容区域宽度，单位 px
  scrollWidth: number;
  // 当前内容区域高度，单位 px
  scrollHeight: number;
  // `<list>`宽度，单位 px
  listWidth: number;
  // `<list>`高度，单位 px
  listHeight: number;
  // 滚动事件源
  eventSource: ListEventSource;
  // 当前正在渲染节点的位置信息
  attachedCells: [
    {
      id: number; // 节点 id
      itemKey: string; // 节点 item-key
      index: number; // 节点在 list 中的 index
      left: number; // 节点左边界相对于 list 的位置，单位 px
      top: number; // 节点上边界相对于 list 的位置，单位 px
      right: number; // 节点右边界相对于 list 的位置，单位 px
      bottom: number; // 节点下边界相对于 list 的位置，单位 px
    },
  ];
}

`upper-threshold-item-count`

// DefaultValue: 0
upper-threshold-item-count?: number

当 <list> 顶部剩余可展示的子节点个数首次小于 upper-threshold-item-count 时，触发一次 scrolltoupper 事件。

`lower-threshold-item-count`

// DefaultValue: 0
lower-threshold-item-count?: number

当 <list> 底部剩余可展示的子节点个数首次小于 lower-threshold-item-count 时，触发一次 scrolltolower 事件。

`scroll-event-throttle`

// DefaultValue: 200
scroll-event-throttle?: number

用于设置 <list> 回调 scroll 事件的时间间隔，单位为毫秒（ms）。其默认 200 ms 回调一次滚动事件。

Note

当 engineVersion 版本小于

3.4，该属性无法生效，因此不会拦截 scroll 事件回调。当 engineVersion 版本大于等于

3.4，如果不设置改属性，则使用默认值 200 ms。

`item-snap`

// defaultValue: undefined
'item-snap'?: ListItemSnapAlignment;

interface ListItemSnapAlignment {
  factor: number;
  offset: number;
}

控制 <list> 实现分页滚动的效果。

分页参数

factor: 分页定位锚定位置的参数，取值范围 [0, 1]
- 取值为 0 代表分页滚动的 <list> 子节点和 <list> 顶部对齐
- 取值为 1 代表分页滚动的 <list> 子节点和 <list> 底部对齐
offset: 额外增加偏移参数，在 factor 的基础之上再进一步添加偏移量

Note

当 engineVersion 版本小于 3.2 时，列表滚动速率会存在不一致问题。

`update-animation`

update-animation?: "default" | "none"

该属性用于控制在数据源更新时，列表是否运行动画。当前支持插入、删除和更新动画。

delete

update

insert

Note

当前 update-animation 只能在 list-type 为 single 或 flow 时生效。

`need-layout-complete-info`

控制 layoutcomplete 事件中是否包含本次 layout 前后的节点排版信息，触发本次排版的 <list> Diff 信息，以及当前 <list> 的滚动状态信息。

export interface LayoutCompleteEvent extends BaseEvent<'layoutcomplete', {}> {
  detail: {
    'layout-id': number;
    // 开启 need-layout-complete-info
    scrollInfo: ListScrollInfo;
    // 开启 need-layout-complete-info
    diffResult?: {
      insertions: number[];
      move_from: number[];
      move_to: number[];
      removals: number[];
      update_from: number[];
      update_to: number[];
    };
    // 开启 need-layout-complete-info
    visibleCellsAfterUpdate?: ListItemInfo[];
    // 开启 need-layout-complete-info
    visibleCellsBeforeUpdate?: ListItemInfo[];
  };
}

`layout-id`

// defaultValue: -1
layout-id?: number

用于标记本次数据源更新的唯一标识，会在 layoutcomplete 事件回调中返回这个 id。

`preload-buffer-count`

// DefaultValue: 0
preload-buffer-count?: number

该属性可以控制 <list> 提前加载 <list> 外节点的个数。

Note

preload-buffer-count 的值越大，可以提前加载的屏外节点越多，但是也会增加 <list> 内存占用。
preload-buffer-count 的取值建议为占满 <list> 一屏的节点个数。
仅 list-type='single'/'flow' 时生效。

`scroll-bar-enable`

// DefaultValue: true
scroll-bar-enable?: boolean

是否显示 <list> 组件滚动条

`harmony-scroll-edge-effect`

// DefaultValue: true
harmony-scroll-edge-effect: boolean

在 Harmony 上，当 contentSize 小于自身容器大小，设置是否开启滑动效果。

`reuse-identifier`

// DefaultValue: null
reuse-identifier: string

<list>
  <list-item
    reuse-identifier="type1"
  >
  <list-item
    reuse-identifier="type2"
  >
</list>

设置 <list-item> 复用 id，<list> 组件在渲染子节点时，会根据 <list-item> 的 reuse-identifier 属性值对 <list-item> 进行复用，只有设置了相同的 reuse-identifier 属性值的 <list-item> 才会被复用。

默认情况下，开发者不提供需要 reuse-identifier，而是由框架在编译阶段确定，比如：当 <list-item> 处于循环内（例如 Array.prototype.map 等）时，由于它们在编译阶段的形态和位置相同，我们会为它们生成相同的 reuse-identifier，我们会认为这一组 <list-item> 可以互相复用。

Note

使用场景：结构差异非常大的 <list-item> 在复用时性能比较差，因此建议为它们设置不同的 reuse-identifier，以避免它们之前被相互复用。

`full-span`

// DefaultValue: false
full-span?: boolean

<list>
  <list-item full-span={true}/>
</list>

属性 full-span 用于标识 <list-item> 独占一行或者一列。

`estimated-main-axis-size-px`

// DefaultValue: -1
estimated-main-axis-size-px?: number

<list-item
  estimated-main-axis-size-px={100}
/>

用于指定 <list-item> 还未渲染完成时，在主轴方向上的占位大小，单位为 px，如果不设置，默认值为 <list> 在主轴方向上的大小。

Note

强烈建议开发者设置与子节点真实大小相近的 estimated-main-axis-size-px。

`experimental-recycle-sticky-item`

// DefaultValue: true
experimental-recycle-sticky-item?: boolean

<list> 中存在多个吸顶或者吸底的节点时，当吸顶或吸底的节点被其他吸顶或吸底的节点推出 <list> 区域后回收该节点，以解决吸顶或者吸底的节点过多导致的内存开销问题。此优化在 engineVersion 版本大于等于

3.4 时默认开启。

吸顶的节点不回收，<list-item> 数量会不断增长吸顶的节点回收，<list-item> 会被复用，数量不会增长

事件

前端可以在元件上绑定相应事件回调来监听元件的运行时行为，使用方法如下。

`scroll`

bindscroll?: EventHandler<ListScrollEvent>;

interface ListScrollEvent {
  // 距上次滚动的横向滚动偏移量，单位 px
  deltaX: number;
  // 距上次滚动的纵向滚动偏移量，单位 px
  deltaY: number;
  // 当前横向滚动偏移量，单位 px
  scrollLeft: number;
  // 当前纵向滚动偏移量，单位 px
  scrollTop: number;
  // 当前内容区域宽度，单位 px
  scrollWidth: number;
  // 当前内容区域高度，单位 px
  scrollHeight: number;
  // `<list>`宽度，单位 px
  listWidth: number;
  // `<list>`高度，单位 px
  listHeight: number;
  // 滚动事件源
  eventSource: ListEventSource;
  // 当前正在渲染节点的位置信息
  attachedCells: [
    {
      "id": number,        // 节点 id
      "itemKey": string,   // 节点 item-key
      "index": number,     // 节点在 list 中的 index
      "left": number,      // 节点左边界相对于 list 的位置，单位 px
      "top": number,       // 节点上边界相对于 list 的位置，单位 px
      "right": number,     // 节点右边界相对于 list 的位置，单位 px
      "bottom": number,    // 节点下边界相对于 list 的位置，单位 px
    },
  ];
}

enum ListEventSource {
  DIFF = 0,
  LAYOUT = 1,
  SCROLL = 2,
}

<list> 滚动事件。

Note

滚动事件触发频率可由 scroll-event-throttle 控制。
如果 <list> 开启 need-visible-item-info，则回调参数中才会包含当前渲染子节点的位置信息。

`scrolltoupper`

bindscrolltoupper?: EventHandler<ListScrollEvent>;

滚动到 <list> 顶部时触发的回调。该回调触发的位置可以由 upper-threshold-item-count 控制。

`scrolltolower`

bindscrolltolower?: EventHandler<ListScrollEvent>;

滚动到 <list> 底部时触发的回调。该回调触发的位置可以由 lower-threshold-item-count 控制。

`scrollstatechange`

bindscrollstatechange?: EventHandler<ListScrollStateChangeEvent>;

interface ScrollStateChangeEvent extends CustomEvent {
  detail: {
    // 本次滑动的滑动状态，取值说明
    //   1 - 静止
    //   2 - 拖拽
    //   3 - 惯性滚动
    //   4 - 动画滚动
    state: number;
  };
}

<list> 滚动状态变化时触发的回调。事件参数的字段 detail 里的 state 分别取值: 1、2、3、4，分别表示 <list> 滚动状态为：静止、拖拽、惯性滚动、动画滚动。

`layoutcomplete`

bindlayoutcomplete?: EventHandler<ListLayoutFinishEvent>;

interface LayoutCompleteEvent extends BaseEvent<'layoutcomplete', {}> {
  detail: {
    'layout-id': number;
    // 需要开启 need-layout-complete-info
    scrollInfo: ListScrollInfo;
    // 需要开启 need-layout-complete-info
    diffResult?: {
      insertions: number[];
      move_from: number[];
      move_to: number[];
      removals: number[];
      update_from: number[];
      update_to: number[];
    };
    // 需要开启 need-layout-complete-info
    visibleCellsAfterUpdate?: ListItemInfo[];
    // 需要开启 need-layout-complete-info
    visibleCellsBeforeUpdate?: ListItemInfo[];
  };
}

interface ListItemInfo {
  // 子节点高度
  height: number;
  // 子节点宽度
  width: number;
  // 子节点 itemKey
  itemKey: string;
  // 子节点是否处于渲染状态
  isBinding: boolean;
  // 子节点相对于全部滚动区域的 x 坐标位置
  originX: number;
  // 子节点相对于全部滚动区域的 y 坐标位置
  originY: number;
  // 子节点是否存被更新
  updated: boolean;
}

<list> 布局完成后触发回调。

`snap`

bindsnap?: EventHandler<ListSnapEvent>;

interface ListSnapEvent extends common.BaseEvent<'snap', {}> {
  detail: {
    // 将会分页滚动到的节点索引
    position: number;
    // 当前横向滚动偏移量，单位 px
    currentScrollLeft: number;
    // 当前纵向滚动偏移量，单位 px
    currentScrollTop: number;
    // 分页滚动的目标横向滚动偏移量，单位 px
    targetScrollLeft: number;
    // 分页滚动的目标纵向滚动偏移量，单位 px
    targetScrollTop: number;
  };
};

即将发生分页滚动时的回调。

方法

`scrollToPosition`

this.createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'scrollToPosition',
    params: {
      position: 10,
      offset: 100,
      alignTo: 'top',
      itemKey: `${itemKey}`,
      smooth: true,
    },
    success: function (res) {},
    fail: function (res) {},
  })
  .exec();

将 <list> 组件滚动到指定的位置，参数说明：

参数名	类型	默认值	必填	简介
position	number	无	是	指定要滚动到的节点的 index, 取值范围为`[0, 数据源个数)`
offset	number	无	否	在应用 `alignTo` 对齐后，继续滚动 `offset` 长度
alignTo	string	null	是	滚动后目标节点在视图中的位置. `"bottom"`: 滑动至该节点在 `<list>` 中完全可见，且该节点的底部和 `<list>` 的底部对齐 `"top"`: 滑动至该节点在 `<list>` 中完全可见，且该节点的顶部和 `<list>` 的顶部对齐 `"middle"`: 滑动至该节点在 `<list>` 中完全可见，且该节点在 `<list>` 中垂直居中
itemKey	string	null	否	指定要滚动到的节点的 `item-key`，如果同时设置了 `item-key` 和 `position` 参数，则优先滚动到 `item-key` 对应的节点
smooth	boolean	false	否	滑动过程中是否有动画

`autoScroll`

this.createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'autoScroll',
    params: {
      rate: '60px', //  每一秒滚动的间距，支持正负。间距支持单位"px/rpx/ppx" default->null (iOS 取值必须大于 1/screen.scale px)
      start: true, //  开始/暂停自动滚动 default->false
      autoStop: true, // 滑到底部是否自动停止 default->true
    },
    success: function (res) {},
    fail: function (res) {},
  })
  .exec();

触发 <list> 自动滚动，参数说明：

参数名	类型	默认值	必填	简介
rate	string	无	null	每一秒滚动的间距，支持正负，可设置单位：`px/rpx/ppx`
start	bool	无	false	开始或者暂停自动滚动，`true`: 开始自动滚动，`false`: 暂停自动滚动
autoStop	bool	无	true	滑到底部是否自动停止

`getVisibleCells`

lynx
  .createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'getVisibleCells',
    success(res) {
      console.log('succ ');
    },
    fail(res) {
      console.log('err ');
    },
  })
  .exec();

获取当前展示的所有 <list> 子节点的信息。返回信息如下：

attachedCells: [
  {
    id: number, // 节点 id
    itemKey: string, // 节点 item-key
    index: number, // 节点在 list 中的 index
    left: number, // 节点左边界相对于 list 的位置，单位 px
    top: number, // 节点上边界相对于 list 的位置，单位 px
    right: number, // 节点右边界相对于 list 的位置，单位 px
    bottom: number, // 节点下边界相对于 list 的位置，单位 px
  },
];

`scrollBy`

lynx
  .createSelectorQuery()
  .select('#id_of_list')
  .invoke({
    method: 'scrollBy',
    params: {
      offset: 100,
    },
    success(res) {
      console.log('succ ');
    },
    fail(res) {
      console.log('err ');
    },
  })
  .exec();

在现有偏移量的基础上继续滚动 offset 指定的距离，单位 px，返回的信息如下：

{
  "consumedX" : number,  // 水平方向滚动的距离，单位 px
  "consumedY" : number,  // 竖直方向滚动的距离，单位 px
  "unconsumedX" : number,  // 水平方向未滚动的距离，单位 px
  "unconsumedY" : number,  // 竖直方向未滚动的距离，单位 px
}

兼容性

`<list>`

LCD tables only load in the browser

`<list-item>`

LCD tables only load in the browser

#<list>

#使用指南

#单列布局

#多列布局

#List 相关 CSS 属性

#list-main-axis-gap

#list-cross-axis-gap

#属性

#list-type Required

#span-count Required

#scroll-orientation Required

#item-key Required

#key Required

#enable-scroll

#enable-nested-scroll

#sticky

#sticky-offset

#sticky-top

#sticky-bottom

#recyclable

#bounces

#initial-scroll-index

#need-visible-item-info

#upper-threshold-item-count

#lower-threshold-item-count

#scroll-event-throttle

#item-snap

#update-animation

#need-layout-complete-info

#layout-id

#preload-buffer-count

#scroll-bar-enable

#harmony-scroll-edge-effect

#reuse-identifier

#full-span

#estimated-main-axis-size-px

#experimental-recycle-sticky-item

#事件

#scroll

#scrolltoupper

#scrolltolower

#scrollstatechange

#layoutcomplete

#snap

#方法

#scrollToPosition

#autoScroll

#getVisibleCells

#scrollBy

#更多功能

#实现节点吸顶或者吸底

#实现滚动到底部加载更多数据

#利用 item-snap 实现分页滚动

#使用 z-index

#实现 <list-item> 不回收

#兼容性

#<list>

#<list-item>

`<list>`

使用指南

单列布局

多列布局

List 相关 CSS 属性

`list-main-axis-gap`

`list-cross-axis-gap`

属性

`list-type` Required

`span-count` Required

`scroll-orientation` Required

`item-key` Required

`key` Required

`enable-scroll`

`enable-nested-scroll`

`sticky`

`sticky-offset`

`sticky-top`

`sticky-bottom`

`recyclable`

`bounces`

`initial-scroll-index`

`need-visible-item-info`

`upper-threshold-item-count`

`lower-threshold-item-count`

`scroll-event-throttle`

`item-snap`

`update-animation`

`need-layout-complete-info`

`layout-id`

`preload-buffer-count`

`scroll-bar-enable`

`harmony-scroll-edge-effect`

`reuse-identifier`

`full-span`

`estimated-main-axis-size-px`

`experimental-recycle-sticky-item`

事件

`scroll`

`scrolltoupper`

`scrolltolower`

`scrollstatechange`

`layoutcomplete`

`snap`

方法

`scrollToPosition`

`autoScroll`

`getVisibleCells`

`scrollBy`

更多功能

实现节点吸顶或者吸底

实现滚动到底部加载更多数据

利用 `item-snap` 实现分页滚动

使用 `z-index`

实现 `<list-item>` 不回收

兼容性

`<list>`

`<list-item>`