Commit e6b4297e authored by Rivaldo Junior's avatar Rivaldo Junior 💬
Browse files

init

parents
MIT License
Copyright (c) 2017 TANG
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
\ No newline at end of file
<p>
<a href="https://travis-ci.org/tangbc/vue-virtual-scroll-list">
<img alt="Travis CI Status" src="https://travis-ci.org/tangbc/vue-virtual-scroll-list.svg?branch=master"/>
</a>
<a href="https://codecov.io/gh/tangbc/vue-virtual-scroll-list">
<img alt="Code Coverage" src="https://codecov.io/gh/tangbc/vue-virtual-scroll-list/branch/master/graph/badge.svg"/>
</a>
<a href="https://npmjs.com/package/vue-virtual-scroll-list">
<img alt="NPM downloads" src="https://img.shields.io/npm/dm/vue-virtual-scroll-list.svg">
</a>
<a href="http://packagequality.com/#?package=vue-virtual-scroll-list">
<img alt="Package quality" src="https://npm.packagequality.com/shield/vue-virtual-scroll-list.svg">
</a>
<a href="https://npmjs.com/package/vue-virtual-scroll-list">
<img alt="NPM version" src="https://img.shields.io/npm/v/vue-virtual-scroll-list.svg"/>
</a>
<a href="https://vuejs.org/">
<img alt="Vue version" src="https://img.shields.io/badge/vue-%3E=2.3.0-brightgreen.svg"/>
</a>
<a href="https://opensource.org/licenses/MIT">
<img alt="License" src="https://img.shields.io/npm/l/vue-virtual-scroll-list.svg">
</a>
</p>
## Table of contents
* [Advantages](#advantages)
* [Live demos](#live-demos)
* [How it works](#how-it-works)
* [Simple usage](#simple-usage)
* [vfor-mode](#vfor-mode)
* [item-mode](#item-mode)
* [variable height](#variable-height)
* [Performance comparison](#performance-comparison)
* [Build time wasted](#build-time-wasted)
* [Total memory used](#total-memory-used)
* [Attentions](#attentions)
* [**Props type**](#props-type)
* [Public methods](#public-methods)
* [Contributions](#contributions)
* [Changelogs](#changelogs)
## Advantages
* Items are independent.
* Tiny and very easy to use.
* Big data list with high performance.
## Live demos
* [Build 100,000 items with vfor-mode](https://tangbc.github.io/vue-virtual-scroll-list/demos/vfor-mode).
* [Build 100,000 items with item-mode](https://tangbc.github.io/vue-virtual-scroll-list/demos/item-mode).
* [Build 100,000 items with variable height](https://tangbc.github.io/vue-virtual-scroll-list/demos/variable-height).
The main difference between `item-mode` and `vfor-mode` is that: `item-mode` make a higher performance but not very convenient to handle changing data frequently; however, `vfor-mode` is just the opposite.
Besides, you can also compare the experience which without using virtual-list here: [without-virtual-list](https://tangbc.github.io/vue-virtual-scroll-list/demos/without-virtual-list).
## How it works
<img src="https://tangbc.github.io/github-images/virtual-scroll-list-how-works.gif">
## Simple usage
```console
npm install vue-virtual-scroll-list --save
```
### vfor-mode
All you need to care about is only data!
```vue
<template>
<div>
<virtual-list :size="40" :remain="8">
<item v-for="item of items" :key="item.id" />
</virtual-list>
</div>
</template>
<script>
import item from '../item.vue'
import virtualList from 'vue-virtual-scroll-list'
export default {
data () {
return {
items: [ {id: 1}, {id: 2}, {id: 3}, ... ]
}
},
components: { item, 'virtual-list': virtualList }
}
</script>
```
### item-mode
This mode can save a considerable amount of memory and performance. Props `item`, `itemcount` and `itemprops` are both required, you don't need put `<item/>` with a v-for directive inside `virtual-list`, just assign it as prop `item`:
```vue
<template>
<div>
<virtual-list :size="40" :remain="8"
:item="item"
:itemcount="100000"
:itemprops="getItemprops"
/>
</div>
</template>
<script>
import itemComponent from '../item.vue'
import virtualList from 'vue-virtual-scroll-list'
export default {
data () {
return {
item: itemComponent,
}
},
methods: {
getItemprops (itemIndex) {
// <item/> will render with following data object:
// https://vuejs.org/v2/guide/render-function.html#The-Data-Object-In-Depth
return {
props: itemProps,
attrs: itemAttrs,
...
}
}
},
components: { 'virtual-list': virtualList }
}
</script>
```
Whenever you want to change any item data from list in this mode, you need call public method `forceRender()` after source data change. Increase or decrease items, you need to keep `itemcount` and call `forceRender()` together.
### variable height
Using variable height, props `remain` and `size` is still required. All the index variable height and scroll offset will be cached by virtual-list after the binary-search calculate, if you want to change anyone `<item/>` height from data, you need call public method `updateVariable(index)` to clear the offset cache.
If you assign `variable` as `true`, **do not** set inline style height inside `<item/>` component, you **must** set inline style height on `<item/>` component outside directly, such as:
```vue
<template>
<div>
<virtual-list :size="40" :remain="8" :variable="true">
<item v-for="item of items" :key="item.id" :style="{ height: item.height + 'px' }" />
</virtual-list>
</div>
</template>
```
**More use ways or getting start you can refer to these clearly [demos](https://github.com/tangbc/vue-virtual-scroll-list/tree/master/demos) or [test suites](https://github.com/tangbc/vue-virtual-scroll-list/tree/master/test).**
## Performance comparison
According to the demos above, here are lists of approximate statistics:
#### Build time wasted
| Build amount | item-mode | vfor-mode | *without virtual list* |
|-------------:|-----------|-----------|------------------------|
| **1,000** | 8 ms | 35 ms | 220 ms |
| **10,000** | 10 ms | 170 ms | 1500 ms |
| **100,000** | 20 ms | 1300 ms | Browser crash! |
#### Total memory used
| Build amount | item-mode | vfor-mode | *without virtual list* |
|-------------:|-----------|-----------|------------------------|
| **1,000** | 10 MB | 80 MB | 200 MB |
| **10,000** | 25 MB | 120 MB | 220 MB |
| **100,000** | 55 MB | 550 MB | Browser crash! |
## Attentions
* Must assign the `:key` property on `<item>` component or dom frag with `v-for` directive.
* Consider using `box-sizing: border-box` on `<item>` if you want absolutely correct scroll height.
## Props type
<img height="256" src="https://tangbc.github.io/github-images/vitual-scroll-list-prop-type.png">
> Props of basic:
| Prop | Type | Required | Description |
|---------------|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| size | Number | ✓ | Each list item height, in variable height, this prop just use to calculate the virtual-list outside container viewport fixed height. |
| remain | Number | ✓ | How many items should be shown in virtual-list viewport, so `size` and `remain` determine the outside container viewport height (`size × remian`). |
> Props of performance:
| Prop | Type | Required | Description |
|---------------|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| bench | Number | * | Default value is equal to `remain`, unreached items count, not show in virtual-list viewport but exist in real DOM, the larger the bench, the higher the scroll performance will achieved. |
| debounce | Number | * | It's disabled by default, milliseconds of using `debounce` function to ensure scroll event doesn't fire so often that it bricks browser performance. |
> Props of position:
| Prop | Type | Required | Description |
|---------------|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| start | Number | * | Default value is `0`, the initial scroll start index. It must be integer and in the range of list index, if invalid there will be effected as `0` or the last one. |
| offset | Number | * | Default value is `0`, the initial scroll offset. If both `start` and `offset` are assigned at initialization, `start` is preferred. |
> Props of element and class:
| Prop | Type | Required | Description |
|---------------|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| rtag | String | * | Default value is `div`, virtual-list root element tag name, in all cases it's style is set to `display: block;` |
| wtag | String | * | Default value is `div`, virtual-list item wrapper element tag name, in all cases it's style is set to `display: block;` |
| wclass | String | * | Default is no classname, virtual-list item wrapper element class, if assign this prop, you better **not** to change it's [CSS box model](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Introduction_to_the_CSS_box_model). |
> Props of scroll mode:
| Prop | Type | Required | Description |
|---------------|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| pagemode | Boolean | * | Let virtual-list scroll with window page viewport. |
| scrollelement | HTMLElement | * | Let virtual-list scroll with a parent element. When `pagemode` is true, `scrollelement` is ignored. |
> Props of scroll event:
| Prop | Type | Required | Description |
|---------------|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| totop | Function | * | Called when virtual-list is scrolled to top, no param. |
| tobottom | Function | * | Called when virtual-list is scrolled to bottom, no param. |
| onscroll | Function | * | Called when virtual-list is scrolling, with param: [`(event, data)`](https://github.com/tangbc/vue-virtual-scroll-list/releases/tag/v1.1.7). |
> Props of variable height:
| Prop | Type | Required | Description |
|---------------|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| variable | Function or Boolean | * | If assign `Function`, this prop is a variable height getter function which is called with param: `(index)` when each item is ready to be calculated; if assign `Boolean`, virtual-list will get each item variable height by it's inline style height automatic. |
> Props of item-mode:
| Prop | Type | Required | Description |
|---------------|---------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| item | Component | * | List item vue component or vNode. |
| itemcount | Number | * | List total count, you should update this prop when source data changed. |
| itemprops | Function | * | A function call when each item is going to be rendered, you can assign props or data to each item component in this function. |
## Public methods
Here are some usefull public methods you can call via [`ref`](https://vuejs.org/v2/guide/components-edge-cases.html#Accessing-Child-Component-Instances-amp-Child-Elements):
* `forceRender()`: force render virtual-list if you need or make it refresh.
* `updateVariable(index)`: update item height by index in variable height list.
## Contributions
Welcome to improve this vue component with any issue, pull request or code review!
## Changelogs
Maintain and update occasionally, for changes see [release](https://github.com/tangbc/vue-virtual-scroll-list/releases).
## License
[MIT License](https://github.com/tangbc/vue-virtual-scroll-list/blob/master/LICENSE)
<template>
<a :href="url" class="github-corner" aria-label="View source on GitHub">
<svg :width="size" :height="size" viewBox="0 0 250 250" style="fill:#151513; color:#fff; position: absolute; top: 0; border: 0; right: 0; z-index: 1000;" aria-hidden="true">
<path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z" />
<path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" style="transform-origin: 130px 106px;" fill="currentColor" class="octo-arm" />
<path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.7,120.9 152.7,124.9 L141.0,136.5 C139.8,137.7 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body" />
</svg>
</a>
</template>
<script>
import { isMobile } from './util'
export default {
name: 'GithubCorner',
props: {
path: {
type: String,
default: ''
}
},
data () {
return {
size: isMobile ? 40 : 80
}
},
computed: {
url () {
return 'https://github.com/tangbc/vue-virtual-scroll-list/tree/master/demos' + (this.path || '')
}
}
}
</script>
<style>
.github-corner:hover .octo-arm{animation:octocat-wave 560ms ease-in-out}@keyframes octocat-wave{0%,100%{transform:rotate(0)}20%,60%{transform:rotate(-25deg)}40%,80%{transform:rotate(10deg)}}@media (max-width:500px){.github-corner:hover .octo-arm{animation:none}.github-corner .octo-arm{animation:octocat-wave 560ms ease-in-out}}
</style>
<template>
<header :class="warning ? 'warning': ''">
<h1>{{ title }}</h1>
<section>
<span class="desciption">{{ desciption }}</span>
<span id="time" class="performance time" />
<span id="memory" class="performance memory" />
<div class="icon" :class="showSetting ? 'active' : ''" @click="clickIcon">
<svg width="25" height="25" t="1553394278598" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="8690" xmlns:xlink="http://www.w3.org/1999/xlink">
<path d="M809.21 474.749H374.022c-19.865 0-35.966 16.101-35.966 35.966 0 19.859 16.101 35.966 35.966 35.966H809.21c19.865 0 35.966-16.107 35.966-35.966 0-19.864-16.101-35.966-35.966-35.966m0 215.796H374.022c-19.865 0-35.966 16.101-35.966 35.966 0 19.859 16.101 35.966 35.966 35.966H809.21c19.865 0 35.966-16.107 35.966-35.966 0-19.865-16.101-35.966-35.966-35.966M220.52 258.954c-19.865 0-35.966 16.101-35.966 35.966 0 19.865 16.101 35.966 35.966 35.966s35.966-16.101 35.966-35.966c0-19.865-16.102-35.966-35.966-35.966m153.502 71.932H809.21c19.865 0 35.966-16.101 35.966-35.966 0-19.865-16.101-35.966-35.966-35.966H374.022c-19.865 0-35.966 16.101-35.966 35.966 0 19.864 16.102 35.966 35.966 35.966M220.52 474.749c-19.865 0-35.966 16.101-35.966 35.966 0 19.859 16.101 35.966 35.966 35.966s35.966-16.107 35.966-35.966c0-19.864-16.102-35.966-35.966-35.966m0 215.796c-19.865 0-35.966 16.101-35.966 35.966 0 19.859 16.101 35.966 35.966 35.966s35.966-16.107 35.966-35.966c0-19.865-16.102-35.966-35.966-35.966" p-id="8691" fill="#2c2c2c" />
</svg>
</div>
<div v-show="showSetting" class="setting">
<div v-if="showStart" class="option">
<span v-if="isMobile" class="name">Index:</span>
<span v-else class="name">Start index:</span>
<input v-model="selfStartIndex" type="text"
@focus="$event.target.select()"
@input="inputDataChange('start', $event.target.value)"
>
</div>
<div class="option">
<span v-if="isMobile" class="name">Count:</span>
<span v-else class="name">List count:</span>
<label>
<input v-model="renderCount" type="radio" value="1">
<span class="t1">1,000</span>
</label>
<label class="middle">
<input v-model="renderCount" type="radio" value="2">
<span class="t2">10,000</span>
</label>
<label>
<input v-model="renderCount" type="radio" value="3">
<span class="t3">100,000</span>
</label>
</div>
</div>
</section>
</header>
</template>
<script>
import { isMobile, debounce, countStorage, settingStorage } from './util'
export default {
name: 'AppHeader',
props: {
warning: Boolean,
title: {
type: String,
default: ''
},
desciption: {
type: String,
default: ''
},
startIndex: {
type: Number,
default: 0
},
onDataChange: {
type: Function,
default: () => {}
}
},
data () {
return {
isMobile,
selfStartIndex: 0,
showSetting: settingStorage.isShow(),
renderCount: String(countStorage.get()).length - 3
}
},
computed: {
showStart () {
return this.startIndex !== undefined
},
isRenderSetting () {
return this.showSetting && (this.showStart)
}
},
watch: {
renderCount (val) {
countStorage.set(val)
window.location.reload()
}
},
mounted () {
this.selfStartIndex = this.startIndex
},
methods: {
clickIcon () {
const nextStatus = !this.showSetting
this.showSetting = nextStatus
settingStorage.setShow(nextStatus)
},
inputDataChange: debounce(function (type, value) {
const val = Number(value)
if (this.onDataChange && value !== '' && !isNaN(val) && val >= 0) {
this.onDataChange(type, val)
}
}, 1000, false)
}
}
</script>
<style lang="less">
header {
font-family: monospace;
h1 {
padding: 20px 0;
@media (max-width: 640px) {
padding: 10px 0;
font-size: 24px;
}
}
section {
font-size: 14px;
background: #f7f7f7;
padding: 10px;
margin-bottom: 20px;
border-radius: 5px;
position: relative;
.performance {
color: #ee82ee;
position: absolute;
right: 50px;
font-size: 12px;
@media (max-width: 640px) {
display: block;
position: relative;
right: 0;
padding-top: 5px;
}
}
.memory {
top: 18px;
@media (max-width: 640px) {
display: block;
position: relative;
right: 0;
padding-top: 5px;
top: 0;
}
}
.time {
top: 5px;
}
.icon {
width: 25px;
height: 25px;
line-height: 25px;
text-align: center;
position: absolute;
right: 10px;
top: 5px;
cursor: pointer;
border-radius: 3px;
&.active {
background-color: #c0c0c0;
}
}
.setting {
position: relative;
padding: 30px 0 20px 20px;
@media (max-width: 640px) {
padding: 20px 0 20px 0px;
}
.option {
display: block;
margin-bottom: 20px;
&:last-child {
margin: 0;
}
.name {
font-family: 'Courier New', Courier, monospace;
font-weight: bold;
display: inline-block;
min-width: 120px;
text-align: left;
@media (max-width: 640px) {
min-width: 50px;
}
}
.middle {
margin: 0 20px;
@media (max-width: 640px) {
margin: 0;
}
}
label {
input {
@media (max-width: 640px) {
position: relative;
top: 3px;
}
}
span {
@media (max-width: 640px) {
position: relative;
left: -5px;
}
}
}
}
i {
position: absolute;
right: 0;
color: lightsteelblue;
font-size: 12px;
}
input[type="text"] {
-webkit-appearance: none;
appearance: none;
padding: 5px;
outline: none;
color: #464a4c;
background-color: #fff;
border-radius: 3px;
border: 1px solid rgba(0, 0, 0, .15);
font-size: 14px;
transition: border-color ease-in-out .15s,box-shadow ease-in-out .15s;
&:focus {
outline: 0;
border-color: #5cb3fd;
}
}
}
}
}
header.warning {
h1, .desciption {
color: #ffc107;
}
.t3 {
color: red;
}
}
</style>
<template>
<div class="item" :style="itemStyle">
<div class="index">
#{{ index }}
</div>
<div class="card">
<div class="card-avatar"
:class="{'no-avatar': !avatar}"
:style="{'background-color': !avatar && info.color}"
>
<span v-if="!avatar">{{ getAbbrName(info.name) }}</span>
<img v-else class="card-avatar-img" :src="info.avatar" alt="AVATAR">
</div>
<div class="card-info">
<div class="card-info-item name" :style="{color: info.color}">
{{ info.name }}
</div>
<div class="card-info-item time">
Registered: {{ info.time }}
</div>
</div>
<div v-if="variable" class="card-height">
{{ height }}px
</div>
</div>
</div>
</template>
<script>
import { getQuery } from './util'
export default {
name: 'Item',
props: {
height: {
type: Number,
default: 0
},