vue3 version virtual list, refer to vue-virtual-scroll-list.
npm install vue-virtual-list-v3js
import VirtualList from 'vue-virtual-list-v3';
app.use(VirtualList);
`
在线示例
1、点我查看完整在线示例
2、pageMode live demo
基本用法
`html
:data-key="'id'"
:data-sources="items"
:estimate-size="80"
:item-class="'list-item-dynamic'"
ref="virtualList"
>
# {{ source.index }}
{{ source.name }}
{{ source.desc }}
`
items 数据示例:
`json
[
{
"index":1,
"name":"0.8952834111006784",
"id":"1$d9ec7a",
"desc":"html5",
"size":150
}
]
`
响应式数据配置示例:
`javascript
let items = ref([]);
const addItem = () => {
items.value.push({
index: Math.random() * 1000 + 1,
name: "Brad" + Math.random() * 1000 + 1,
id: Date.now(),
desc: "html5",
size: 150,
});
};
`
更新日志
1.5.5 版本修复dataSources变化时,列表不更新的问题
1.5.4 版本修复非pageMode模式下数据不更新问题
1.5.2 版本新增pageMode模式
1.5.0 版本新增 container-class 属性,用户可以自主设置高度/宽度
虚拟列表属性和方法
$3
| 属性 | 类型 | 描述 |
|------------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| data-key | String\|Function | 从data-sources中的每个数据对象获取唯一键。或者使用每个数据源调用函数并返回其唯一键。其值在数据源中必须是唯一的,用于标识每一项的尺寸。 |
| data-sources | Array[Object] | 为列表生成的源数组,每个数组数据必须是一个对象,并且具有唯一的key get或generate fordata key属性。 |
$3
属性
类型
默认值
描述
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。
$3
方法
描述
reset()
将所有状态重置回初始状态。
scrollToBottom()
手动将滚动位置设置为底部。
scrollToIndex(index)
手动将滚动位置设置为指定索引。
scrollToOffset(offset)
手动将滚动位置设置为指定的偏移量。
getSize(id)
按id(从data-key)获取指定的项目大小。如果已渲染列表中没有该项,则返回undefined。
getSizes()
获取存储(渲染)项的总数。
getOffset()
获取当前滚动偏移量。
getClientSize()
获取包装器元素客户端视口大小(宽度或高度)。
getScrollSize()
获取所有滚动大小(滚动高度或滚动宽度)。
## Props type
$3
| 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. |
| 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. |
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. |