插件 jQuery.circle progress 中文API文档

🌙
手机阅读
本文目录结构

插件 jQuery.circle progress 中文API文档 https://github.com/kottenator/jquery-circle-progress

jquery-circle-progress

Build status Bower version NPM version

jQuery Plugin to draw animated circular progress bars like this:

Check out more examples! Or maybe the crazy one?

Install

Make your choice:

Usage

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
<script src="jquery-circle-progress/dist/circle-progress.js"></script>

<div id="circle"></div>

<script>
  $('#circle').circleProgress({
    value: 0.75,
    size: 80,
    fill: {
      gradient: ["red", "orange"]
    }
  });
</script>

If you use AMD or CommonJS with some JS bundler - see the UMD section below.

Options

Specify options like in example above.

Option Description
value This is the only required option. It should be from 0.0 to 1.0
Default: 0
size Size of the circle / canvas in pixels
Default: 100
startAngle Initial angle (for 0 value)
Default: -Math.PI
reverse Reverse animation and arc draw
Default: false
thickness Width of the arc. By default it’s automatically calculated as 1/14 of size but you may set your own number
Default: "auto"
lineCap Arc line cap: "butt", "round" or "square" - read more
Default: "butt"
fill The arc fill config. You may specify next:
- "#ff1e41"
- { color: "#ff1e41" }
- { color: 'rgba(255, 255, 255, .3)' }
- { gradient: ["red", "green", "blue"] }
- { gradient: [["red", .2], ["green", .3], ["blue", .8]] }
- { gradient: [ ... ], gradientAngle: Math.PI / 4 }
- { gradient: [ ... ], gradientDirection: [x0, y0, x1, y1] }
- { image: "http://i.imgur.com/pT0i89v.png" }
- { image: imageInstance }
- { color: "lime", image: "http://i.imgur.com/pT0i89v.png" }
Default: { gradient: ["#3aeabb", "#fdd250"] }
emptyFill Color of the “empty” arc. Only a color fill supported by now
Default: "rgba(0, 0, 0, .1)"
animation Animation config. See jQuery animations.
You may also set it to false
Default: { duration: 1200, easing: "circleProgressEasing" }
"circleProgressEasing" is just a ease-in-out-cubic easing
animationStartValue Default animation starts at 0.0 and ends at specified value. Let’s call this direct animation. If you want to make reversed animation then you should set animationStartValue to 1.0. Also you may specify any other value from 0.0 to 1.0
Default: 0.0
insertMode Canvas insertion mode: append or prepend it into the parent element?
Default: "prepend"

From version 1.1.3 you can specify any config option as HTML data- attribute.

It will work only on init, i.e. after the widget is inited you may update its properties only via .circleProgress({/*...*/}) method. data- attributes will be ignored.

Also, object options like "fill" or "animation" should be valid JSON (and don’t forget about HTML-escaping):

<div
  class="circle"
  data-value="0.9"
  data-size="60"
  data-thickness="20"
  data-animation-start-value="1.0"
  data-fill="{
    &quot;color&quot;: &quot;rgba(0, 0, 0, .3)&quot;,
    &quot;image&quot;: &quot;http://i.imgur.com/pT0i89v.png&quot;
  }"
  data-reverse="true"
></div>

Events

Event Description Handler
circle-inited Triggered on init or re-init. function(event):
- event - jQuery event
circle-animation-start Triggered once the animation is started. function(event):
- event - jQuery event
circle-animation-progress Triggered on each animation tick. function(event, animationProgress, stepValue):
- event - jQuery event
- animationProgress - from 0.0 to 1.0
- stepValue - current step value: from 0.0 to value
circle-animation-end Triggered once the animation is finished. function(event):
- event - jQuery event

Browsers support

The library uses <canvas> which is supported by all modern browsers (including mobile browsers) and Internet Explorer 9+ (Can I Use).

I haven’t implemented any fallback / polyfill for unsupported browsers yet (i.e. for Internet Explorer 8 and older / misc browsers).

UMD

I use UMD template for jQuery plugin which combines three things:

  • works fine with browser globals
  • works fine with AMD
  • works fine with CommonJS

Browser globals

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
<script src="jquery-circle-progress/dist/circle-progress.js"></script>
<script>
  $('#circle').circleProgress({
    value: 0.75,
  });
</script>

AMD

Assuming that you have jquery, jquery-circle-progress and requirejs in libs/ directory:

<script src="libs/requirejs/require.js"></script>
<script>
  requirejs.config({
    paths: {
      'jquery': 'libs/jquery/dist/jquery', // 'jquery' path is required - 'jquery-circle-progress' requires it
      'jquery-circle-progress': 'libs/jquery-circle-progress/dist/circle-progress' // and this one is for your convenience
    }
  });
  requirejs(['jquery', 'jquery-circle-progress'], function($) {
    $('#circle').circleProgress({
      value: 0.75
    });
  });
</script>

You can configure RequireJS as you wish, just make 'jquery' dependency reachable.

CommonJS

// script.js
require('jquery-circle-progress');
var $ = require('jquery');
$('#circle').circleProgress({
  value: 0.75
});
some-js-bundler < script.js > script.bundle.js
<script src="script.bundle.js"></script>

You can use any JS bundler (Webpack, Browserify, etc) - no specific configuration required.

API

Get/set value

Get it:

$('.circle').circleProgress({ value: 0.5 });
var value = $('.circle').circleProgress('value'); // 0.5

It will return the first item’s value (by first I mean when $('.circle').length >= 1). It works only if the widget is already inited. Raises an error otherwise.

Set it:

$('.circle').circleProgress('value', 0.75); // set value to 0.75 & animate the change

It will update all selected items value and animate the change. It doesn’t redraw the widget - it updates the value & animates the changes. For example, it may be an AJAX loading indicator, which shows the loading progress.

Get <canvas>

$('.circle').circleProgress({ value: 0.5 });
var canvas = $('.circle').circleProgress('widget');

It will return the first item’s <canvas> (by first I mean when $('.circle').length >= 1). It works only if the widget is already inited. Raises an error otherwise.

Get CircleProgress instance

var instance = $('#circle').data('circle-progress');

Redraw existing circle

$('#circle').circleProgress({ value: 0.5, fill: { color: 'orange' }});
$('#circle').circleProgress('redraw'); // use current configuration and redraw
$('#circle').circleProgress(); // alias for 'redraw'
$('#circle').circleProgress({ size: 150 }); // set new size and redraw

It works only if the widget is already inited. Raises an error otherwise.

Change default options

$.circleProgress.defaults.size = 50;

FAQ

How to start the animation only when the circle appears in browser's view (on scrolling)?
Here is my proposed solution.
How to make the size flexible?
E.g. for responsive design, you can do it in the following way.
What if I need it to run in IE8?
There is no full-feature support for IE8 (actually, I didn't imlpement IE8 support at all). But you may follow my recommendations.
How to stop the animation?
Here is what you can do.
Can I handle "click" event?
It's not in the "core" but you can use my example of mouse/touch events handling.
May I customize the shape somehow?
It's a bit "tricky" but possible. Here is my little collection.

Development

Install

git clone git@github.com:kottenator/jquery-circle-progress.git
npm install

Modify

You need to update dist/circle-progress.min.js after any change to dist/circle-progress.js:

npm run build-min

If you’re using one of JetBrains IDEs - you can configure a File Watcher. It’s also possible to use some CLI tool like Watchman.

Test

npm test

SauceLabs:

export SAUCE_USERNAME=...
export SAUCE_ACCESS_KEY=...
export BUILD_NUMBER=...
npm test -- karma-saucelabs.conf.js

Build docs

The API docs are not complete yet but you can build them:

npm run build-docs

They will be generated in docs/api/.

Release new version

  • finalize the code

  • update the version in package.json, bower.json and dist/circle-progress.js docstring

  • update min dist: npm run build-min

  • update docs/index.html - link to the latest dist version (which doesn’t exist yet)

  • push the changes to master branch

  • release on Bower: just create a Git tag (e.g.): git tag v1.2.3 && git push --tags

  • release on GitHub - add release notes to the Git tag

  • release on NPM: npm publish, but be aware:

    Once a package is published with a given name and version, that specific name and version combination can never be used again - NPM docs

AXIHE / 精选资源

浏览全部教程

面试题

学习网站

前端培训
自己甄别

前端书籍

关于朱安邦

我叫 朱安邦,阿西河的站长,在杭州。

以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

关注我: Github / 知乎

于2021年离开前端领域,目前重心放在研究区块链上面了

我叫朱安邦,阿西河的站长

目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>

于2021年离开前端领域,目前从事区块链方面工作了