vue-virtual-list-v3

VirtualList 虚拟列表 vue3 版本

当列表的数据量很大时，使用虚拟列表呈现内容。

更新日志

1.5.0版本新增 container-class 属性，用户可以自主设置高度/宽度

组件注册

import VirtualList from 'vue-virtual-list-v3';

app.use(VirtualList);

在线示例

点我查看完整在线示例

基本用法

<div class="container">
     <VirtualList class="list-dynamic scroll-touch"
          :data-key="'id'"
          :data-sources="items"
          :estimate-size="80"
          :item-class="'list-item-dynamic'"
          ref="virtualList"
        >
        <template #={source}>
            <div class="item-inner">
                <div class="head">
                    <span># {{ source.index }}</span>
                    <span>{{ source.name }}</span>
                </div>
                <div class="desc">{{ source.desc }}</div>
            </div>
        </template>
      </VirtualList>
</div>

items 数据示例：

[
  {
    "index":1,
    "name":"0.8952834111006784",
    "id":"1$d9ec7a",
    "desc":"html5",
    "size":150
  }
]

响应式数据配置示例：

let items = ref(DataItems); // DataItems is origin data
const addItem = () => {
    DataItems.push({
        index: Math.random() * 1000 + 1,
        name: "Brad" + Math.random() * 1000 + 1,
        id: Date.now(),
        desc: "html5",
        size: 150,
    });
    items.value = JSON.parse(JSON.stringify(DataItems));
};

虚拟列表属性和方法

必须的属性

属性	类型	描述
data-key	String|Function	从data-sources中的每个数据对象获取唯一键。或者使用每个数据源调用函数并返回其唯一键。其值在数据源中必须是唯一的，用于标识每一项的尺寸。
data-sources	Array[Object]	为列表生成的源数组，每个数组数据必须是一个对象，并且具有唯一的key get或generate fordata key属性。

其他属性

属性	类型	默认值	描述
keeps	Number	30	您期望虚拟列表在真实 dom 中保持渲染的项目数量。
extra-props	Object	{}	分配给组件一些不在data-sources中的属性. 注意: index 和 source 都被内部占用了.
estimate-size	Number	50	每个Item的估计大小，如果它更接近平均大小，滚动条长度看起来更准确。建议指定自己计算的平均值。
start	Number	0	设置滚动位置保持开始索引。
offset	Number	0	设置滚动位置保持偏移。
scroll	Event		滚动时触发, 参数 (event, range)。
totop	Event		当滚动到顶部或者左边时触发, 无参数。
tobottom	Event		当滚动到底部或者右边时触发，无参数。
resized	Event		当大小改变时触发 (mounted), 参数 (id, size)。
direction	String	vertical	滚动的方向, 可选值为 vertical 和 horizontal。
top-threshold	Number	0	发出totop 事件的阈值, 注意多个调用。
bottom-threshold	Number	0	发出tobottom 事件的阈值, 注意多个调用。
container-class	String		容器的类名，一般需要添加高度/或者宽度来让内容滚动，1.5.0版本新增
root-tag	String	div	根节点的名称。
wrap-tag	String	div	列表包裹元素名称(role=group)。
wrap-class	String		列表包裹元素类名。
wrap-style	Object	{}	列表包裹元素内联样式。
item-tag	String	div	项目包裹元素名称。
item-class	String		项目包裹元素类名。
item-class-add	Function		一个函数，您可以将额外的类（字符串）返回给项包装器元素， 参数 (index)。
item-style	Object	{}	项目包裹元素内联样式。
item-scoped-slots	Object	{}	Item组件的 slot。

公共方法

方法	描述
reset()	将所有状态重置回初始状态。
scrollToBottom()	手动将滚动位置设置为底部。
scrollToIndex(index)	手动将滚动位置设置为指定索引。
scrollToOffset(offset)	手动将滚动位置设置为指定的偏移量。
getSize(id)	按id（从data-key）获取指定的项目大小。如果已渲染列表中没有该项，则返回undefined。
getSizes()	获取存储（渲染）项的总数。
getOffset()	获取当前滚动偏移量。
getClientSize()	获取包装器元素客户端视口大小（宽度或高度）。
getScrollSize()	获取所有滚动大小（滚动高度或滚动宽度）。

Props type

Required props

Prop	Type	Description
data-key	String|Function	The unique key get from data-sources in each data object. Or a function called with each data-source and return their unique key. Its value must be unique in data-sources, it is used for identifying item size.
data-sources	Array[Object]	The source array built for list, each array data must be an object and has an unique key get or generate for data-key property.

Optional props

Prop	Type	Default	Description
keeps	Number	30	How many items you are expecting the virtual list to keep rendering in the real dom.
extra-props	Object	{}	Extra props assign to item component that are not in data-sources. Notice: index and source are both occupied inner.
estimate-size	Number	50	The estimate size of each item, if it is closer to the average size, the scrollbar length looks more accurately. It is recommended to assign the average that calculate by yourself.
start	Number	0	Setting scroll position stay start index.
offset	Number	0	Setting scroll position stay offset.
scroll	Event		Emited when scrolling, param (event, range).
totop	Event		Emited when scrolled to top or left, no param.
tobottom	Event		Emited when scrolled to bottom or right, no param.
resized	Event		Emited when item resized (mounted), param (id, size).
direction	String	vertical	Scroll direction, available values are vertical and horizontal
page-mode	Boolean	false	Let virtual list using global document to scroll through the list.
top-threshold	Number	0	The threshold to emit totop event, attention to multiple calls.
bottom-threshold	Number	0	The threshold to emit tobottom event, attention to multiple calls.
root-tag	String	div	Root element tag name.
wrap-tag	String	div	List wrapper element (role=group) tag name.
wrap-class	String		List wrapper element class name.
wrap-style	Object	{}	List wrapper element inline style.
item-tag	String	div	Item wrapper element (role=item) tag name.
item-class	String		Item wrapper element class name.
item-class-add	Function		A function that you can return extra class (String) to item wrapper element, param (index).
item-style	Object	{}	Item wrapper element inline style.
item-scoped-slots	Object	{}	The $scopedSlots for item component.
header-tag	String	div	For using header slot, header slot wrapper element (role=header) tag name.
header-class	String		For using header slot, header slot wrapper element class name.
header-style	Object	{}	For using header slot, header slot wrapper element inline style.
footer-tag	String	div	For using footer slot, footer slot wrapper element (role=footer) tag name.
footer-class	String		For using footer slot, footer slot wrapper element class name.
footer-style	Object	{}	For using using footer slot, footer slot wrapper element inline style.

Public methods

Usefull public methods

You can call these methods via ref:

Method	Description
reset()	Reset all state back to initial.
scrollToBottom()	Manual set scroll position to bottom.
scrollToIndex(index)	Manual set scroll position to a designated index.
scrollToOffset(offset)	Manual set scroll position to a designated offset.
getSize(id)	Get the designated item size by id (from data-key value).
getSizes()	Get the total number of stored (rendered) items.
getOffset()	Get current scroll offset.
getClientSize()	Get wrapper element client viewport size (width or height).
getScrollSize()	Get all scroll size (scrollHeight or scrollWidth).
updatePageModeFront()	When using page mode and virtual list root element offsetTop or offsetLeft change, you need call this method manually.