Movatterモバイル変換

tangbc/vue-virtual-scroll-listPublic

NotificationsYou must be signed in to change notification settings
Fork606
Star4.5k

⚡️A vue component support big amount data list with high render performance and efficient.

tangbc.github.io/vue-virtual-scroll-list

License

MIT license

4.5k stars 606 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 549 Commits
.github		.github
dist		dist
docs		docs
example		example
scripts		scripts
src		src
test		test
.babelrc		.babelrc
.eslintrc.json		.eslintrc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json

Repository files navigation

Advantages

Only 3 required props, simple and very easy to use.
Big data list with high render performance and efficient.
You don't have to care about item size, it will calculate automatic.

Live demo

https://tangbc.github.io/vue-virtual-scroll-list

https://codesandbox.io/s/live-demo-virtual-list-e1ww1

Simple usage

npm install vue-virtual-scroll-list --save

Root component:

<template>  <div>    <virtual-liststyle="height:360px;overflow-y:auto;" //makelistscrollable:data-key="'uid'":data-sources="items":data-component="itemComponent"    />  </div></template><script>importItemfrom'./Item'importVirtualListfrom'vue-virtual-scroll-list'exportdefault {    name:'root',data () {return {        itemComponent: Item,        items: [{uid:'unique_1', text:'abc'}, {uid:'unique_2', text:'xyz'},...]      }    },    components: {'virtual-list': VirtualList }  }</script>

Item component:

<template>  <div>{{ index }} - {{ source.text }}</div></template><script>exportdefault {    name:'item-component',    props: {      index: {// index of current item        type:Number      },      source: {// here is: {uid: 'unique_1', text: 'abc'}        type:Object,default () {return {}        }      }    }  }</script>

More usages or getting start you can refer to these clearlyexamples.

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 valuemust 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.
`data-component`	Component	The render item component created / declared by vue, and it will use the data object in`data-sources` as render prop and named:`source`.

Optional props

Commonly used

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 isrecommended to assign the average that calculate by yourself.

Uncommonly used

Prop	Type	Default	Description
`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 viaref:

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.

Attentions

This component use anin-place patch strategy to render list instead ofv-for and:key. This way achieves the best efficient, but only suitable when your list output does not rely on item component inner state or temporary DOM state (e.g. form input values).

But how to deal with such a situation? Without maintaining inner state, recommend to use props and dispatch (stateless component), here is an examplekeep-state.