Pace.js自动加载进度条中文API文档
前一篇文章介绍Pace.js插件的基本使用方法和简介内容,接下来我们为大家介绍Pace.js插件的配置参数、回调函数等中文文档,方便广大的开发者自定义Pace.js插件。
Themes
Pace 包括一系列显示主题,当你开始使用的时候。只需要包含相应的CSS文件即可,如果可以,你也可以自己编写主题显示样式,并分享给我们,你创造的与任何有趣的主题。
Collectors
Collectors are the bits of code which gather progress information. Pace includes four default collectors:
- AjaxMonitors all ajax requests on the page
- ElementsChecks for the existance of specific elements on the page
- DocumentChecks the document readyState
- Event LagChecks for event loop lag signaling that javascript is being executed
They can each be configured or disabled through configuration options of the same name.
paceOptions = {
ajax: false, // disabled
document: false, // disabled
eventLag: false, // disabled
elements: {
selectors: ['.my-page']
}
};
Add your own classes to paceOptions.extraSources
to add more sources. Each source should either have a .progress
property, or a .elements
property which is a list of objects with .progress
properties. Pace will automatically handle all scaling to make the progress changes look smooth to the user.
Elements
Elements being rendered to the screen is one way for us to decide that the page has been rendered. If you would like to use that source of information (not required at all), specify one or more selectors. You can comma seperate the selectors to propertly handle error states, where the progress bar should disappear, but the element we are looking for may never appear:
paceOptions = {
elements: {
selectors: ['.timeline,.timeline-error', '.user-profile,.profile-error']
}
}
Pace will consider the elements test successful when each selector matches something. For this example, when either .timeline
or .timeline-error
exist, and either .user-profile
or .profile-error
exist.
Restart Rules
Most users want the progress bar to automatically restart when a pushState event occurs (generally means ajax navigation is occuring). You can disable this:
paceOptions = {
restartOnPushState: false
}
You can also have pace restart on every ajax request which lasts longer than x ms. You’ll want to disable this if you make ajax requests the user doesn’t need to know about, like precaching:
paceOptions = {
restartOnRequestAfter: false
}
You can always trigger a restart manually by calling Pace.restart()
See the source for a full list of all options.
API
Pace exposes the following methods:
Pace.start
: Show the progress bar and start updating. Called automatically if you don’t use AMD or CommonJS.Pace.restart
: Show the progress bar if it’s hidden and start reporting the progress from scratch. Called automatically wheneverpushState
orreplaceState
is called by default.Pace.stop
: Hide the progress bar and stop updating it.Pace.track
: Explicitly track one or more requests, see Tracking belowPace.ignore
: Expliticly ignore one or more requests, see Tracking below
Events
Pace fires the following events:
start
: When pace is initially started, or as a part of a restartstop
: When pace is manually stopped, or as a part of a restartrestart
: When pace is restarted (manually, or by a new AJAX request)done
: When pace is finishedhide
: When the pace is hidden (can be later thandone
, based onghostTime
andminTime
)
You can bind onto events using the on
, off
and once
methods:
Pace.on(event, handler, [context])
: Callhandler
(optionally with context) whenevent
is triggeredPace.off(event, [handler])
: Unbind the providedevent
andhandler
combination.Pace.once(event, handler, [context])
: Bindhandler
to the next (and only the next) incidence ofevent
Tracking
By default, Pace will show any ajax requests which begin as a part of a normal or ajax-y page load, or which last longer than 500ms.
You can disable all ajax tracking by setting ajax
to false:
Pace.options = {
ajax: false
}
You can disable ajax tracking except on page navigation by setting restartOnRequestAfter
to false:
Pace.options = {
restartOnRequestAfter: false
}
You can manually disable tracking for a specific request or requests by triggering them within a Pace.ignore
callback:
Pace.ignore(function(){
$.ajax(...)
});
You can force the progress bar to be shown for a specific request by triggering them within a Pace.track
callback:
Pace.track(function(){
$.ajax(...)
});
You can also ignore URLs based on a pattern:
Pace.options = {
ajax: {
ignoreURLs: ['some-substring', /some-regexp/]
}
}
Dependencies
None!
Support
Pace is designed to support IE8+ (standards mode), FF 3.5+, Chrome, Safari 4+, Opera 10.5+, and all modern mobile browsers. If you run into a compatibility issue, or can make a case for supporting something else, please create an issue.
Size
pace.js is 4kb minified and gzipped. The themes vary between 0.5 and 4kb.
Issues
We have obviously not tested this on every website. If you run into an issue, or find a way the automatic detection could be better, please create an Issue. If you can include a test case, that’s even better.
Contributing
PRs Welcome!
Building requires node.js.
npm install
grunt
You can also run grunt watch
to have it automatically build as you make changes.
There is no need to include compiled files in PRs.
Credits
Javascript by Zack Bloom CSS by Adam Schwartz
Themes inspired by Mary Lou
Project inspired by nprogress