jQuery 倒计时插件 jQuery.countdown

在Web页面中有时会需要倒计时功能，jQuery.countdown是一个使用简单、无任何CSS/HTML依赖的 jQuery 倒计时插件。它会自动控制DOM、注册回调并开始计时，适用于任何布局方式，且支持多种不同的倒计时方式。

1. 安装与引用

安装

jQuery.countdown支持Bower安装，安装命令如下：

bower install jquery.countdown

或者点击以下链接下载：

下载 jQuery.countdown.zip

引用

安装后在页面引用插件即可：

<script src="/bower_components/jquery.countdown/dist/jquery.countdown.js"></script>

2. 插件使用

countdown会为每个DOM选择器创建一个实例，并发送包含剩余时间的事件，其中有周、日、小时等。countdown实例是被包裹在DOM元素中，会随着包裹元素的移除而自动移除。

$('div#clock').countdown(finalDate[, callback]);

与传统方法类型，需要注册事件的回调函数（callback (update、finish 或 stop)）以在指定时刻进行相应的处理。也可以通过jQuery的.on()方法来添加回调：

$('div#clock').countdown(finalDate)
  .on('update.countdown', callback)
  .on('finish.countdown', callback);

调用countdown()方法并传入finalDate参数就可以启动倒计时，但需要通过注册回调函数来操作和更新DOM。

2.1 参数

finalDate

创建倒计时的目标时间。可以是以下形式之一：

JavaScriptDate对象
一个毫秒级的'UNIX'时间戳
以下格式的字符串：
- YYYY/MM/DD
- MM/DD/YYYY
- YYYY/MM/DD hh:mm:ss
- MM/DD/YYYY hh:mm:ss

callback

回调函数，其形式如下：

function(event) { ... }

配置对象

在插件初始化时，可以传入两个自定义的配置参数：

$('div#clock').countdown(finalDate, {
  elapse: true,    // '{bool} 到达更新时间后是否继续'
  precision: 5000 '{int} 更新时间（毫秒）'
})

Elapse模式会控制在到达指定时间点后是否继续计时，我们可以在回调函数的 event.elapsed属性中访问这个设置，并可以结合这个设置项进行一些精确控制：

$('div#clock').countdown(finalDate, {elapse: true})
  .on('update.countdown', function(event) {
    if (event.elapsed) { // Either true or false
      // Counting up...
    } else {
      // Countdown...
    }
  });

2.2 控制

通过pause/resume参数可以控制倒计时的执行流：

// 暂停
$('div#clock').countdown('pause');
// 恢复
$('div#clock').countdown('resume');

stop/start可以实现相同的功能：

// 暂停
$('div#clock').countdown('stop');
// 恢复
$('div#clock').countdown('start');

向初始化方法传入一个时间，可以开始一个新的倒计时：

$('div#clock').countdown('2010/10/10');
// Then ...
$('div#clock').countdown('2012/20/20 12:34:56');

3. 事件与事件对象

3.1 事件

jQuery.countdown会在状态改变时发送一些事件：

Update：更新DOM时触发
Finish：完时倒计时时触发
Stop：暂停时触发

可以通过event.type的形式来注册回调函数：

update.countdown
finish.countdown
stop.countdown

3.2 事件对象

事件的回调函数中有一个参数，该参数是一个事件对象：

{
  type:           '{String} 事件类型 {update,finish,stop}.countdown',
  strftime:       '{Function} 格式化函数',
  finalDate:      '{Date} 结束时间',
  elapsed:        '{bool} 是否执行到最后?'
  offset: {
    seconds:    '{int} 差多少到下一分钟',
    minutes:    '{int} 差多少分到下一小时',
    hours:      '{int} 差多少小时到下一天',
    daysToWeek: '{int} 差多少天到下一周'
    daysToMonth:'{int} 差多少天到下一月'
    totalDays:  '{int} 到结束时间的总天数',
    weeks:      '{int} 到结束时间的总周数',
    months:     '{int} 到结束时间的总月数' ,
    years:      '{int} 到结束时间的总年数'
  }
}

4. 格式化

在回调函数的参数对象中，有一个event.strftime属性，该属性是一个格式化方法，可以通过%来设置输出格式：

event.strftime('%W weeks %-d days %-H h %M min %S sec');
// => 1 week 2 days 3 h 04 min 05 sec

填充设置在输出命令中默认使用0进行左侧填充如（01, 02, 03, ..., 10），也可以通过-符号使用空添充。

非复数设置默认情况下，当指定单位超过1时，会使用复数形式。可以通过!符号设置使用非复数形式

命令格式

命令	空白填充	说明
`%Y`	`%-Y`	年剩余 *
`%m`	`%-m`	月剩余 *
`%n`	`%-n`	天剩余（到下一月） *
`%w`	`%-w`	周剩余
`%d`	`%-d`	天剩余（到下一周）
`%D`	`%-D`	剩余总天数
`%H`	`%-H`	小时剩余
`%M`	`%-M`	分剩余
`%S`	`%-S`	秒剩余