jQuery 倒计时插件 jQuery.countdown

 2016年05月06日    184     声明


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


  1. 安装与引用
  2. 插件使用
  3. 事件与事件对象
  4. 格式化

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 秒剩余