# @wines/virtual-list

> The virtual-list @wines

Latest version **2.0.0** (published 2025-04-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @wines/virtual-list
pnpm add @wines/virtual-list
yarn add @wines/virtual-list
bun add @wines/virtual-list
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2025-04-01 |
| First published | 2021-04-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >=16.0.0 |
| Dependencies | 2 |
| Unpacked size | 54.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | tianyingchun |

## Links

- npm: https://www.npmjs.com/package/@wines/virtual-list
- Repository: https://gitlab.itcjf.com/wines/virtual-list
- npm.io page: https://npm.io/package/@wines/virtual-list

## Dependencies (2)

- [@wines/core](https://npm.io/package/@wines/core.md) 2.0.0
- [@wines/styles](https://npm.io/package/@wines/styles.md) 2.0.0

## Recent versions

- 2.0.0 (latest) — 2025-04-01
- 2.0.0-next.7 (next) — 2025-04-01
- 2.0.0-next.6 — 2025-03-06
- 2.0.0-next.5 — 2025-03-05
- 2.0.0-next.4 — 2025-03-05
- 2.0.0-next.3 — 2025-03-04
- 2.0.0-next.2 — 2025-02-28
- 2.0.0-next.1 — 2025-02-27
- 2.0.0-next.0 — 2025-02-27
- 1.5.1 — 2023-03-07
- 1.5.0 — 2022-11-22
- 1.4.0 — 2022-02-23
- 1.3.5 — 2021-12-03
- 1.3.2 — 2021-09-24
- 1.3.1 — 2021-04-25
- … 1 more at https://npm.io/package/@wines/virtual-list/versions

## README

# `@wines/virtual-list`

# VirtualList 虚拟列表

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

## 使用指南

### 在 page.json 中引入组件

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

### 示例

```xml
<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>


```

```ts
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 表示事件对象，启用页面滚动时需要手动设置

### 返回参数

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

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

---
_Source: https://npm.io/package/@wines/virtual-list · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._