npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@just4/virtual-list

v2.0.0

Published

Just for making scrollable list rendering more efficiently.

Downloads

97

Readme

虚拟滚动列表

本模块提供基于原生 DOM 操作的高性能虚拟滚动列表工作流,适用于无限上拉/下拉数据列表、聊天记录等功能场景。

使用

安装

npm i @just4/virtual-list

调用

import { VirtualList } from '@just4/virtual-list';

const virtualList = new VirtualList({
  // 初始化参数
});

初始化参数说明:

| 参数名 | 类型 | 说明 | | --- | --- | --- | | container | HTMLElement | 滚动容器(HTML 元素)。 | | itemKey | string | 数据项的 key 属性。 | | maxItemCount | number | 最大渲染的节点数,默认为 100 | | prefetchDistance | number | 预加载距离,为滚动容器高度的倍数,默认为 2。 | | defaultView | 'head' | 'foot' | 默认视图,'head' 表示开头,'foot' 表示末尾。 | | dataSource | Object | 数据源(详见下文说明)。 | | renderer | Object | 渲染器(详见下文说明)。 |

数据源(dataSource)

VirtualList 对象会调用数据源去加载所需的数据,包括初始数据、下一页数据和上一页数据。数据源应包含以下异步方法

  • loadInitialData():加载初始数据。
  • loadNextData(ref):加载下一页数据,其中 ref 是当前最后一条数据的 key 值。
  • loadPreviousData(ref):加载上一页数据,其中 ref 是当前第一条数据的 key 值。

以下为数据源对象的示例:

// 假设 allData 中包含所有数据
const allData = [
  // ...
];

// 分页的页大小
const PAGE_SIZE = 50;

const dataSource = {
  loadInitialData() {
    return new Promise((resolve) => {
      // setTimeout 用于模拟数据加载的延迟
      setTimeout(function() {
        resolve(
          {
            data: allData.slice(0, PAGE_SIZE),
            reachedFootBoundary: false,
            reachedHeadBoundary: true
          }
        );
      }, 500);
    });
  },

  loadNextData(ref) {
    return new Promise((resolve) => {
      setTimeout(function() {
        for (let i = 0; i < allData.length; i++) {
          if (allData[i].id.toString() === String(ref)) {
            resolve(allData.slice(i + 1, i + 1 + PAGE_SIZE));
            break;
          }
        }
        resolve([]);
      }, 500);
    });
  },

  loadPreviousData(ref) {
    return new Promise((resolve) => {
      setTimeout(function() {
        for (let i = 0; i < allData.length; i++) {
          if (allData[i].id.toString() === String(ref)) {
            resolve(allData.slice(Math.max(0, i - PAGE_SIZE), i));
            break;
          }
        }
        resolve([]);
      }, 500);
    });
  }
};

如果返回的是空数组,则表示数据已到达边界,不会在该方向上继续加载。特别地,如果 loadInitialData 返回的是空数组,则表示当前没有数据,不会再触发 loadNextDataloadPreviousData

渲染器(renderer)

模块内部会把数据传入渲染器,并把渲染器返回的 DOM 节点渲染到容器内,渲染器是一个包含以下方法的对象:

  • renderItems:渲染数据项,需返回一个 DOM 节点的类数组或数组
  • renderLoading:渲染加载中界面,需返回 DOM 节点;
  • renderError:渲染加载异常界面,需返回 DOM 节点;
  • renderBoundary:渲染数据边界界面,需返回 DOM 节点;
  • renderEmpty:渲染空数据提示,需返回 DOM 节点。

其中 renderLoadingrenderErrorrenderBoundary 的第一个参数为渲染位置、第二个参数为虚拟滚动列表的实例。渲染位置包括:

  • RenderPosition.Main:主位置,指的是没有数据时的状态。
  • RenderPosition.Head:开头位置。
  • RenderPosition.Foot:结尾位置。

例如,如果只想在列表的结尾位置渲染边界界面,可以这么做:

import { RenderPosition } from '@just4/virtual-list/types';
const renderer = {
  // ...

  renderBoundary(position, instance) {
    if (position === RenderPosition.Foot) {
      const div = document.createElement('div');
      div.className = 'list-end';
      div.innerHTML = '没有更多数据了';
      div.onclick = function() {
        // instance 即为虚拟滚动列表实例
        instance.retryFetch();
      };
      return div;
    }
  }
};

事件

单次渲染完成

virtualList.on('rendered', function(args) {
  console.dir(args);
});

args 的类型说明见文档

点击数据项节点

virtualList.on('item-click', function(args) {
  console.dir(args);
});

args 的类型说明见文档

更新数据项

virtualList.on('item-update', function(args) {
  console.dir(args);
});

args 的类型说明见文档

移除数据项

以下两种情况都会触发数据项的移除:

  • 数据量超出 maxItemCount
  • 调用 removeItemremoveItems 移除数据。
virtualList.on('item-remove', function(args) {
  console.dir(args);
});

args 的类型说明见文档

获取当前数据项

可通过 items 属性获取当前数据项的集合。

// 第一个数据项
virtualList.items.first();
// 最后一个数据项
virtualList.items.last();
// 遍历所有数据项
for (let i = 0; i < virtualList.items.length; i++) {
  console.dir(virtualList.items.get(i));
}

异常重试

如果在加载数据的过程中出现异常(Promise 返回 rejected 状态),那么在该方向上的滚动加载将会停止。此时可以通过界面上的交互引导用户手动点击重试。在重试操作中调用 retryFetch 这个方法。

注意:retryFetch 方法仅在加载异常和到达边界两种状态下可用,其他状态下将不会执行任何操作。

其他

Changelog

v2.0.0

  • 事件发布/订阅机制更换为通过 @just4/util/event 中的 PubSub 实现。
  • VirtualListEvent 不再是枚举类型,事件名通过字符串指定即可。

v1.0.0

  • 允许通过 setOptions 更改 defaultView 选项。
  • loadNextDataloadPreviousData 新增第二个参数,返回数据项的拷贝。
  • 组件内的数据项列表为空时,不调用 loadNextDataloadPreviousData,而不是传入 null 去调用它们。
  • scrollToHeadscrollToFoot 新增 exceptState 参数,用于指定是否排除状态节点。
  • 新增 removeItems 方法,用于移除多个数据项。
  • 移除数据项后,会检查当前是否处于预加载的范围内。
  • 如果所有数据项都被清空,会先触发刷新,而不是直接显示空状态。
  • 在空状态下,调用 resetBoundaryState 会触发刷新,重新请求初始数据。
  • 执行 resetBoundaryState 重置状态之后,会检查当前是否处于预加载的范围内。
  • 优化预加载范围检查的执行频率。
  • 其他代码优化。

v0.12.0

  • 修复容器不可见时节点不会被渲染的问题。

v0.11.0

  • 优化位置检查逻辑的触发时机和频率。