test-common-yuan-fang

测试

Usage no npm install needed!

<script type="module">
  import testCommonYuanFang from 'https://cdn.skypack.dev/test-common-yuan-fang';
</script>

README

基于Taro3的虚拟列表

安装

npm i -D taro-virtual-list

使用方法

试用场景一：一次性请求到所有数据（即listType="single"）

import { TaroVirtualList } from 'taro-virtual-list'

export default function Demo(): JSX.Element {
  // 渲染列表Item
  const renderFunc = (item, index, pageIndex) => {
    return (
      <View className="el">{`当前是第${item}个元素，是第${pageIndex}屏的数据`}</View>
    )
  }
  const handleBottom = () => {
    console.log('触底了')
  }
  const handleComplete = () => {
    console.log('加载完成')
  }
  return (
    <View>
      <TaroVirtualList
        list={list}
        onRender={renderFunc}
        onBottom={handleBottom}
        onComplete={handleComplete}
        scrollViewProps={{
          style: {
            "height": '100vh',
          },
        }}
      />
    </View>
  )

}

试用场景二：数据是分页请求（即listType="multi"）

import { TaroVirtualList } from 'taro-virtual-list'

export default function Demo(): JSX.Element {
  // 渲染列表Item
  const renderFunc = (item, index, pageIndex) => {
    return (
      <View className="el">{`当前是第${item}个元素，是第${pageIndex}屏的数据`}</View>
    )
  }
  const onPageScrollToLower = () => {
    // 执行分页数据请求
  }
  return (
    <View>
      <TaroVirtualList
        autoScrollTop={false}
        listType="multi"
        list={list}
        pageNum={页码}
        segmentNum={每页的数据量}
        onRender={renderFunc}
        scrollViewProps={{
          onScrollToLower: onPageScrollToLower,
          lowerThreshold: 50,
          style: {
            "height": '100vh',
          },
        }}
      />
    </View>
  )

}

参数说明

Props

参数 类型 默认值 必填 说明
list Array - 是 列表数据
listId String "zt-virtial-list" 否 虚拟列表唯一id（防止同一个页面有多个虚拟列表导致渲染错乱）
listType String "single" 否 传入组件内的list类型
single：一次性传入列表所有数据
multi：从服务端分页请求，合并之后传入组件
pageNum Number 1 否 当前页码，当list是通过服务端分页获取的时候必传，最小值是1
segmentNum Number 10 否 自定义二维数组每一维度的数量，默认10，当list是通过服务端分页获取的时候，推荐传每页的数据量，且必传
autoScrollTop Boolean true 否 组件内部是否需要根据list数据变化自动滚动至列表顶部
screenNum Number 2 否 指定监听页面显示区域基准值，例如2，则组件会监听 2 * scrollHeight高度的上下区域范围(该值会影响页面真实节点的渲染数量，值越大，白屏几率越小，但是页面性能也就越差)
scrollViewProps Object - 否 自定义scrollView的参数，会合并到组件内部的scrollView的参数里

Events

参数 回调参数 默认值 必填 说明
onRender (item, index, segmentIndex) => {}
item: 列表的单个数据项的值;
index：列表的单个数据项的index;
segmentIndex：当前二维数组维度的index		 - 列表的渲染回调，用于自定义列表Item -
onBottom - - 否 列表是否已经触底回调，注：只有在listType=single时有效
onComplete - - 否 列表是否已经把全部数据加载完成的回调
onRenderTop - - 否 列表上部分内容渲染回调，用于渲染插入虚拟列表上边的内容
onRenderBottom - - 否 列表下部分内容渲染回调，用于渲染插入虚拟列表下边的内容
onRenderLoad - - 否 用于上拉到底部渲染底部loading样式的回调
onGetScrollData (res) => {} - 否 获取滚动信息，以传入的listId作为key，默认key是“zt-virtial-list”，目的是让用户可以自定义组件的滚动高度，以此解决https://github.com/NervJS/taro/issues/8466的问题

注意事项

  1. 当listType="single"时，组件默认当外部传入的list引用发生变更的话，会重新渲染整个列表，如果不想重新渲染，则外部只需要修改list内部对象的属性值即可，不要更换list的引用地址
  2. 如果想禁止组件内部自动滚动至顶部的功能，将autoScrollTop置为false，此时需要用户手动控制列表滚动高度，可通过onGetScrollData回调获取当前列表滚动数据，注意该数据结构有所不同噢
  3. 当遇到服务端分页请求获得list的情况，listType，pageNum，segmentNum必传，autoScrollTop置为false，在scrollViewProps中传入onScrollToLower函数
  4. onRenderBottom渲染的内容会在虚拟列表所有数据渲染完成之后才会调用
  5. 该组件默认支持拿到全部数据进行渲染，如果用户的数据是分页请求的，需要将autoScrollTop参数置为false，否则每请求一次数据，列表就会默认置顶
  6. 设置scrollViewProps参数的时候请注意：
  • 最好给个容器高度
  • 当listType=single,如果想触发onScrollToLower方法，可以尝试使用onBottom回调代替（因为组件内部已经使用了onScrollToLower方法，如果外部再定义，会导致代码冲突，组件上拉加载失效）

感谢

如果用着感觉还不错，欢迎赐予一枚star，以此来激励作者输出更多优质代码，造福一方😄

为啥要开发该组件

  1. 列表页数据量过多，一次性渲染完成后页面节点数量过大，造成页面渲染卡顿，渲染完成之后操作页面数据也会异常卡顿；
  2. 官方虚拟列表（3.2.1）存在一定的渲染bug，特别是针对列表节点不等高，存在诸多问题，比如节点闪动、滚动过快造成无限加载、白屏率较高等；

该组件适用场景

  1. 页面节点渲染较多（主要是列表页）；
  2. 针对列表页节点不等高具有更好的支持；

版本

1.0.6

  • 支持服务端分页获取数据渲染

1.0.4

  • 添加onGetScrollData回调获取列表滚动数据

1.0.3

  • 添加autoScrollTop控制列表内部滚动逻辑

原理

  1. 处理数据：将传入的list分割成二维数组，初始化的时候只加载二维数组的第一项，随着页面滚动，会依次加入对应维度的数据（加快了初始化渲染速度）；
  2. 可视区域监听：利用Taro.createIntersectionObserver监听当前可视区域，将不在可视区域内的那一维度的数据改成该维度数据所占的视图高度（进而减少了setState的数据量）；
  3. 渲染：将不在可视区域内的数据利用一个节点占高（减少了节点渲染数量）；