Giter VIP home page Giter VIP logo

ez-progress's Introduction

ez-progress

一个web(伪)进度插件。

我们经常会遇到需要做一个页面加载进度的loading需求。进度loading有别于一般的动画loading,因为我们除了表达页面从开始加载,到加载完成这一过程之外,还需要实时地显示出某一刻的加载进度(百分比),在web中要做到真实的进度控制是很难的(其实我想说的是不可能),所以我们需要在这一段时间里作出一些模拟的效果,让用户觉得“我知道当前已经加载到什么程度了”。

install

npm install ez-progress --save

config

var Progress = require('ez-progress')
var progress = new Progress({
  from: 0,  // 默认进度条起点
  to: 100,  // 默认进度条终点
  speed: 1,  //  默认速度为1,单位为progress/delay(进度每间隔),详见api说明
  delay: 1000 / 11  // 默认时间间隔为11分之1秒,即进度变化周期
})

值得注意的是,所有配置项都是非必选的。。。

看到这里,也许你会想先看看使用插件实现一个网页进度loading的设计过程Demo

api

  1. on 用于事件监听
  2. fire 用于触发事件
  3. handler 事件集合
  4. from 设置进度起点,该项覆盖配置项from
  5. add 增量配置进度
  6. go 设置目的进度
  7. end 中断进度,进度不可恢复
  8. complete 完成进度,若进度未达到最大值,将自动完成剩余进度
  9. reset非中断非销毁 的进度进行重置,回到配置的起点
  10. destroy 销毁进度,进度不可恢复

参数对照

api 入参 返回值 说明
on event(str), callback(func) - -
fire event(str), callback(func) - -
handler - Object -
from progress(num/arr) this 该项覆盖配置项from
add progress(num/arr), callback(func), speed(num/arr), delay(num/arr) this callback不是必传项,但是如果需要传后面的参数,请设置并占位为null,如:add(10, null, 1, 100);speed为速度,单位是 progress/delay ,可以设置为具体数值,也可以设置为数组,设置为数组表示为取区间内的随机数,delay同理,如:add(10, null, [1, 3], [100, 300]),表示 进度+10,无回调,速度为每时间间隔增加进度1~3,时间间隔为100~300毫秒之间
go progress(num/arr), callback(func), speed(num/arr), delay(num/arr) this 参数同add,此api实质是由add实现的。
end callback(func) this 中断进度,进度不可恢复(即不可reset)。
complete callback(func), speed(num/arr), delay(num/arr) this 参数同add,此api实质是由add实现的,注意,不需要传progress。
reset callback(func) this 非中断非销毁 的进度进行重置,回到配置的起点。
destroy callback(func) this 销毁进度(config、data、timer、on、fire、handler),进度不可恢复。

留意:

  1. progress、speed暂不支持负值,所以add不支持传负数,go不支持倒退;
  2. callback不是必传项,但是如果需要传后面的参数,无回调要设置为null
  3. speed和delay都是非必传项;
  4. 所有callback都注入一个data

callback (data)

所有回调都注入一个data,这个data可以由progress.data(假设progress是一个进度实例)获得。初始化的data结构如下:

// cfg为配置项,由progress.config获得
data = {
  progress: cfg.from,  // progress初始化为配置起点,之后的操作过程中,表示即时进度
  next: {  // next表示当前进行中的进度段数据
    dist: cfg.from,  // 当前进度段的终点
    callback: null,  // 进度段结束后的回调
    speed: cfg.speed,  // 进度段(配置)速度,注意,不是当前实时速度
    delay: cfg.delay,  // 进度段(配置)间隔,注意,不是当前实时间隔
    status: 1  // 进度段的状态,初始化时为1表示已完成,0表示未完成
  },
  status: 0  // 进度条的状态,0表示正常工作,1表示锁定(已结束/中断后会将进度条锁定),2表示完成中(调用了complete之后,但complete未完成之前)
}

on/fire

目前支持订阅的事件:

事件 说明
progress 进度执行过程中的回调,可以了解进度的实时变化
add add被执行的时候
go go被执行的时候
passed 前一进度段被跳过(覆盖)的时候
ended end被执行的时候
completed complete被执行的时候
destroy destroy被执行的时候
reset reset被执行的时候

留意:

  1. add/go等api传参的回调与通过on来订阅的回调是有本质区别的,api传参的回调是在本次进度完成之后执行,而on订阅的回调则是在一调用api就触发的;
  2. passed事件的发生条件是,当多个进度在同步进行,在某个阶段a进度被b进度赶上并覆盖的时候,我们将取消a的过程,而继续完成b的过程,这个a被b赶上的那一瞬间,a被取消的那一刻,会触发一次passed事件;
  3. destroy的回调都是在实例销毁之前执行的,因为销毁后的实例已经不具备执行回调的功能。

用法

下面我们看演示代码(多es6语法,请自行转换es5。。。):

var $prg = document.getElementById('progress')
var $prgBar = document.getElementById('progress_bar')

var Progress = require('ez-progress')
var prg = new Progress({
  from: 0,
  to: 100,
  speed: 1,
  delay: 1000 / 11
})

prg.on('progress', (res) => {
  console.log('progress: ' + res.progress)
  var prg = Math.round(res.progress)

  $prg.innerHTML = prg + '%'
  $prgBar.style.width = prg + '%'
})

prg.on('add', (res) => {
  console.log('add to: ' + res.next.dist)
})

prg.on('go', (res) => {
  console.log('go: ' + res.next.dist)
})

prg.on('passed', (res) => {
  console.log('passed: ' + res.next.dist)
})

prg.on('ended', (res) => {
  console.log('ended: ' + res.next.dist)
})

prg.on('completed', (res) => {
  console.log('completed: ' + res.progress)
})

prg.on('destroy', (res) => {
  console.log('destroy: ' + res.progress)
})

prg.on('reset', (res) => {
  console.log('reset: ' + res.progress)
})

prg.go([20, 60], (res) {
  prg.add(30, null, [0, 3], [0, 100])
}, [0, 3], [0, 200])

setTimeout(() => {
  prg.complete(null, [0, 5], [0, 50])
}, 5000)

这里的演示代码只是一个简单的用法介绍,我们还详细介绍了一个网页进度loading的设计过程Demo

log

0.1.0 - publish

ez-progress's People

Contributors

jack-lo avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.