@wines/virtual-list

VirtualList 虚拟列表

适用于显示同类的长列表数据类型，对渲染性能有一定的优化效果。

使用指南

在 page.json 中引入组件

{
  "navigationBarTitleText": "VirtualList",
  "enablePullDownRefresh": true,
  "usingComponents": {
    "wux-virtual-list": "@wines/virtual-list",
    "wux-virtual-item": "@wines/virtual-list/item"
  }
}

示例

<wux-virtual-list
 id="wux-virtual-list"
 enablePageScroll
 height="{{ height }}"
 itemHeight="100"
 itemBuffer="30"
 disableScroll="{{ disableScroll }}"
 bind:change="onChange"
>
	<wux-virtual-item wx:for="{{ virtual.items }}" wx:key="item">
		<view class="item">
			<view class="index">{{ '#' + item }}</view>
			<view class="desc">Wux NB</view>
		</view>
	</wux-virtual-item>
</wux-virtual-list>

import './page-scroll.less';
import { PageCustom, PageData } from '@wines/core';
import {
  $wuxVirtualList,
  VirtualListExports,
  VirtualListOnChangeParam,
} from '@wines/virtual-list';

let itemCount = 1000;
const height = wx.getSystemInfoSync().windowHeight;
const getItems = (count: number = itemCount): number[] => {
  const items: number[] = [];
  for (let i = 0; i < count; i++) {
    items.push(i);
  }
  return items;
};
Page<PageData, PageCustom>({
  data: {
    disableScroll: false,
    height,
  },
  onLoad() {
    this.virtualList = $wuxVirtualList('#wux-virtual-list');
    this.updated(getItems());
  },
  updated(items: unknown[]) {
    const startTime = Date.now();
    const virtualList = this.virtualList as VirtualListExports;
    virtualList.render(items, (param: VirtualListOnChangeParam) => {
      const diffTime = Date.now() - startTime;
      console.log(`onSuccess - render time: ${diffTime}ms`, param);
    });
  },
  loadData() {
    if (itemCount >= 10000) return;
    if (this.data.disableScroll) return;
    this.setData({ disableScroll: true });
    void wx.showLoading({
      title: '数据加载中',
    });
    setTimeout(() => {
      itemCount += 1000;
      this.updated(getItems(itemCount));
      this.setData({ disableScroll: false });
      void wx.hideLoading();
      void wx.stopPullDownRefresh();
    }, 3000);
    console.log('loadData');
  },
  onChange(e) {
    const { startIndex, endIndex } = e.detail as VirtualListOnChangeParam;
    if (
      this.data.startIndex !== startIndex ||
      this.data.endIndex !== endIndex
    ) {
      this.setData(e.detail);
      console.log('onChange', e.detail);
    }
  },
  onPageScroll(e) {
    // 当页面滚动时调用组件 scrollHandler 方法
    const virtualList = this.virtualList as VirtualListExports;
    virtualList.scrollHandler({ detail: e });
    // console.log('onPageScroll', e)
  },
  onReachBottom() {
    this.loadData();
    console.log('onReachBottom');
  },
  onPullDownRefresh() {
    itemCount = 0;
    this.loadData();
    console.log('onPullDownRefresh');
  },
});

API

VirtualList props

| 参数 | 类型 | 描述 | 默认值 | | ------------------- | ---------- | --------------------------------------------------------------- | ---------------- | | prefixCls | string | 自定义类名前缀 | wux-virtual-list | | itemHeight | number | 子元素高度 | 50 | | itemBuffer | number | 可视容器外加载的元素个数，值越大性能越高 | 0 | | scrollToIndex | number | 设置滚动条到对应子元素的位置 | 0 | | upperThreshold | number | 距顶部多远时，触发 scrolltoupper 事件 | 50 | | lowerThreshold | number | 距底部多远时，触发 scrolltolower 事件 | 50 | | scrollWithAnimation | boolean | 在设置滚动条位置时使用动画过渡 | false | | enableBackToTop | boolean | iOS点击顶部状态栏、安卓双击标题栏时，滚动条返回顶部，只支持竖向 | false | | disableScroll | boolean | 是否禁用滚动 | false | | enablePageScroll | boolean | 是否启用页面滚动，默认使用 <scroll-view/> 滚动 | false | | height | number | 可视容器高度 | 300 | | debounce | number | 是否防抖 | 0 | | bind:change | function | 数据变化时的回调函数 | - | | bind:scroll | function | 滚动时触发 | - | | bind:scrolltoupper | function | 滚动到顶部时触发 | - | | bind:scrolltolower | function | 滚动到底部时触发 | - |

VirtualList externalClasses

| 名称 | 描述 | | --------- | ------------ | | wux-class | 根节点样式类 |

VirtualItem props

| 参数 | 类型 | 描述 | 默认值 | | --------- | -------- | -------------- | ---------------- | | prefixCls | string | 自定义类名前缀 | wux-virtual-item |

VirtualItem slot

| 名称 | 描述 | | ---- | ---------- | | - | 自定义内容 |

VirtualItem externalClasses

| 名称 | 描述 | | --------- | ------------ | | wux-class | 根节点样式类 |

外部方法

• VirtualList.render(items, success) items 表示实际数据列表，用于动态加载数据
• VirtualList.scrollTo(scrollOffset, success) scrollOffset 表示滚动条位置，滚动到指定的位置
• VirtualList.scrollToIndex(index, success) index 表示子元素索引，根据索引值滚动到指定的位置
• VirtualList.scrollHandler(e) e 表示事件对象，启用页面滚动时需要手动设置

返回参数

// `VirtualItem` 遍历值必须是 `change` 事件返回的数据，格式如下

{
  "direction": "", // 滚动方向，可选值为 Up、Down
  "startIndex": "", // 第一个元素的索引值
  "endIndex": "", // 最后一个元素的索引值
  "scrollOffset": "", // 滚动条实际位置
  "virtual": { "items": [] } // 用于遍历渲染 `VirtualItem` 元素
}