vue-l-lazyload
A lazyload and in-view detection plugin for Vue.js v2.x+.
Demo
Live demo or npm install vue-l-lazyload && npm run startDev
to play it!
Pull requests are welcome :)
License
Features
- No extra dependencies except Vue
- Progressive configuration
- Flexible events to trigger loading
- Lazyload as src attribute and background image are supported
- Customized retry control
- Filters for substitution of url by rules
- Performance boost by event delegation and passive event listener when it's available
- LazyComp for lazy loading child component.
- InViewComp for in-view detection
Installation
npm install vue-l-lazyload
Usage
A simple way:
import { VueLLazyload } from 'vue-l-lazyload'; // For smaller production code with tree shaking, I recommend you to import the src instead: // import { VueLLazyloadLocal: VueLLazyload } from 'vue-l-lazyload/src'; Vue.use(VueLLazyload, { events: 'scroll' }); // The root $lazy "Vue.$lazy" will be available after it's been installed
<img lazy="xxx.png">
A more configurable way:
import { VueLLazyload } from 'vue-l-lazyload'; Vue.use(VueLLazyload, config);
<lazy-ref ref="lazyRef" opts="config"> <img lazy="{src:xxx.png, ref:'lazyRef'}"> </lazy-ref>
Vue Plugins
VueLLazyload
Vue Plugin with global option of registering directive "lazy" and component "lazy-ref".
VueLLazyloadLocal
Vue Plugin without global option of registering directives or components for local usage purpose and smaller footprint.
Config
Notes about Config
Note that ALL ANCESTORS' CONFIGS WILL BE INHERITED level by level. So be careful there may be conflict problems if you use too many ancestors' configs!
Available Config Table
Name | Type | Default | Description |
---|---|---|---|
events | String or Array<String> | scroll | Events to be bound with. |
preloadRatio | Number | 1 | The "resize" ratio of parent view when it's children views compare with it. |
onEnter | Function | - | It will be triggered if the element enters the sight. The argument will be a object: { // The LazyLoader $lazy, } |
onLeave | Function | - | It will be triggered if the element leaves the sight. The argument will be a object: { // The LazyLoader $lazy, } |
throttleMethod | String | debounce | Throttling method. Available values: "debounce", "throttle" |
throttleTime | Integer | 250 | Throttling time in ms. |
regGlobal | Boolean | true | Whether to register the directive "lazy" and component "lazy-ref" globally or not. Only available for global config of "VueLLazyload". |
[1]: All options will inherit its ancestors' options.
LazyLoader
$lazy is Instance of LazyLoader, available for LazyRef and InViewComp.
Methods
Name | Arguments | Description |
---|---|---|
check | - | Manually check and load itself and its children loaders which haven't loaded. |
Directives
Lazy(v-lazy)
value
Type | Description |
---|---|
String or Object | If the value is an Object, it has the same spec as config with extra config. If the value is a String, it will be used as `src` of config |
Extra config for the Value of Lazy
Name | Type | Default | Description | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ref | String | `null` | The name of parent view (lazy-ref component or window). If it's not specified, it will be the window. By now, it only supports one level of LazyRef parent. | |||||||||||||||||||||
src[2] | String | - | The resource url going to be loaded. Only available for Lazy. | |||||||||||||||||||||
filters | Array<Function> | - | Filter the src you one by one before the element requests it. Each filter is a function and should return the filtered url. The signiture of it should be like this: function: String ( // Last filtered result. It will be the original src if it's the first filter. lastResult, // Other infomation info: { // The element to which the loader attaches el, }, ) {} | |||||||||||||||||||||
retry | Integer or Function | 0 | If it's a number, it will be the retry amount, 0 for no retry, -1 for infinite retry. If it's a function, it will be used to control the flow of retry. It will pass a object parameter which has following properties:
| |||||||||||||||||||||
classLoading | String | lazy-loading | Class name of loading Only available for Lazy. | |||||||||||||||||||||
classLoaded | String | lazy-loaded | Class name of loaded Only available for Lazy. | |||||||||||||||||||||
classErr | String | lazy-err | Class name of load error Only available for Lazy. | |||||||||||||||||||||
classTarget | String | self | Element (real node) of class name to be changed when the load stat changes. If it's set to `parent`, the class name of parent element will be changed. By default, the class name of element it self will be changed. | |||||||||||||||||||||
once | Boolean | true | Remove listener after it has loaded if it is set to true. | |||||||||||||||||||||
mode | String | - | The mode the lazyload. If it's set to 'bg', the resource will be loaded as a background image. By default, it will be set as the "src" attribute of the element. Only available for Lazy and LazyRef. | |||||||||||||||||||||
onLoad | Function | - | It will be called when the src is loaded successfully (after retry if it did retry). It will pass a object parameter which has following properties:
| |||||||||||||||||||||
onErr | Function | - | It will be called when the src fails to load each time. It will pass a object parameter which has following properties:
| |||||||||||||||||||||
onReq | Function | - | It will be called when the load request begins to be sent each time. It will pass a object parameter which has following properties:
|
[1]: All options should not be changed after they have initialized except for [2].
[2]: It will mark the node not loaded and load again when it's in parent view. if once
is set to false
.
[3]: All options will inherit its ancestors' options.
Components
LazyRef(lazy-ref, Experimental)
Name | Type | Default | Description |
---|---|---|---|
tag | String | div | The tag name of the wrapper component when it renders. |
opts | Object | null | See config. And it can be used a parent option to be inherited. |
InViewComp
opts
InViewComp
Extra config for Name | Type | Default | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
onInView | Function | - | It will be called when the element is in the viewport. It will pass wa object parameter which has following properties:
|
[1]: All options above won't inherit its ancestors' options by now.
LazyComp
Props
Name | Type | Default Value | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
tag | String | div | The tag name of the wrapper component when it renders. | ||||||||||
opts | Object | null | It has the same spec as config with extra config. | ||||||||||
stat | Integer | COMP_NOT_LOAD | The status of the component which controls the slot's display. Available constants for stat:
|
opts
LazyComp
Extra config for Name | Type | Default | Description | |||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
classCompLoading | String | comp-stat-loading | Class name of loading Only available for LazyComp. | |||||||||
classCompLoaded | String | comp-stat-loaded | Class name of loaded Only available for LazyComp. | |||||||||
classCompErr | String | comp-stat-err | Class name of load error Only available for LazyComp. | |||||||||
classCompNotLoad | String | comp-stat-err | Class name of load error Only available for LazyComp. | |||||||||
onInView | Function | - | It will be called when the element is in the viewport. It will pass wa object parameter which has following properties:
|
[1]: All options above won't inherit its ancestors' options by now.
Slots
Name | Description |
---|---|
not-load | It will be shown if the prop `stat` is set to `COMP_NOT_LOAD`. |
loading | It will be shown if the prop `stat` is set to `COMP_LOADING`. |
err | It will be shown if the prop `stat` is set to `COMP_ERR`. |
(default) | It will be shown if the prop `stat` is set to `COMP_LOADED`. |
Well, what's next?
- More abilities
- More test cases
- Performance optimization