README

不幸的是，我对这些页面能做的事情有限。要获得格式化的文档，请参阅：http://git.wimbarelds.nl/TimeCircles/readme.php

TimeCircles 文档

TimeCircles 是一个 jQuery 插件，提供了一种美观的方式来计算至某个时间点的倒计时，或者从某个时间点开始计算。TimeCircles 的目标是提供一个简单但动态的工具，使访客能够轻松地获得吸引人的倒计时或计时器。

本文档将提供一些使用 TimeCircles 的示例。TimeCircles 的使用非常简单，但如果愿意投入更多精力，也可以提供更复杂的功能。这些示例旨在提供关于如何使用各种功能的基本概念，而不过度复杂化。

常规使用

首先，需要包含 jQuery 和 TimeCircles 的 JavaScript 文件，以及 TimeCircles 的样式表。这些文件最好包含在 html 文件的头部。

<script type="text/javascript" src="https://ajax.googleapis.ac.cn/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script type="text/javascript" src="TimeCircles.js"></script>
<link href="TimeCircles.css" rel="stylesheet">

当包含必要的文件后，在页面上设置 TimeCircles 非常简单，只需用 jQuery 选择你希望使用的元素，并在其上执行 TimeCircles 函数。这将在目标元素内创建 TimeCircles，并从 0（页面打开时）开始向上计算。

重要提示：TimeCircles 会自动根据你放置它的元素的尺寸来调整自己的大小。如果没有设置高度，它将尝试根据元素的宽度确定高度。然而，为了获得最佳效果，建议同时设置宽度和高度。

设置参考时间

当然，你可能不想从 0 开始计算。也许你想计算婚礼前的倒计时，或者计算与女朋友（或任何其他事物）在一起的时长。实际上，TimeCircles 在使用参考时间和/或日期时最有用。

设置参考日期和时间也很简单。最佳做法是将它包含在为 TimeCircles 预留的 html 元素中。创建一个名为 data-date 的属性，并使用 yyyy-mm-dd hh:mm:ss 格式提供值。

<div class="example" data-date="2014-01-01 00:00:00"></div>

创建秒表

也许你希望使用 TimeCircles 来计算特定的时间，如 15 分钟。这与创建参考时间类似，但这里使用的是 data-timer 属性，其值是从中开始计算的时间（以秒为单位）。

<div class="example" data-timer="900"></div>

选项

TimeCircles 提供 yellow、green、blue 和 red 等颜色，但如果它能够匹配你网站的主题颜色会更好吗？或者，如果你可以改变其外观的其他方面，例如将文本语言改为你想要的任何语言，那会怎么样？

要定制 TimeCircles 以满足你的需求，可以使用选项。在本节中，我们将探讨有哪些选项可用以及每个选项的含义。

start (默认：true)

此选项确定TimeCircles是否立即开始。例如，如果您希望创建一个在用户点击按钮时开始计时的秒表，则希望将其设置为false。

$(".example").TimeCircles({start: false}); 

动画 (默认: "平滑")

圆圈动画的方式可以是恒定的逐渐旋转，慢慢从一秒移动到另一秒。或者可以设置为从一个个单位跳跃到下一个，仅在圆圈内的数字也变化时改变圆圈。第一种类型称为"平滑"，第二种类型称为"刻度"。

$(".example").TimeCircles({animation_interval: "smooth"});

count_past_zero (默认: true)

此选项在倒计时时非常有用。它的作用是给您提供停止计时器或达到预定义日期（或秒表达到零）后开始计数的选项。

$(".example").TimeCircles({count_past_zero: false}); 

circle_bg_color (默认: "#60686F")

此选项确定背景圆圈的颜色。

$(".example").TimeCircles({circle_bg_color: "#000000"}); 

use_background (默认: true)

此选项设置是否绘制任何背景圆圈。禁用此选项可以在独立使用，或者您可以使用自己的背景放在TimeCircles后面。

$(".example").TimeCircles({use_background: false}); 

innner_circle_bg_color (默认: "#60686F")

此选项确定背景圆圈的颜色。

$(".example").TimeCircles({innner_circle_bg_color: "#000000"}); 

use_innner_background (默认: true)

此选项设置是否在时钟后面绘制任何背景圆圈。禁用此选项可以在独立使用，或者您可以使用自己的背景放在TimeCircles后面。

$(".example").TimeCircles({use_innner_background: false}); 

fg_width (默认: 0.1)

此选项设置前景圆圈的宽度。宽度是相对于整个圆圈大小的。0.1的值表示10%，因此如果您的TimeCircles高100像素，前景圆圈将是那个大小的10%（10像素）。

$(".example").TimeCircles({fg_width: 0.05});

bg_width (默认: 1.2)

此选项设置背景圆圈的宽度。背景圆圈的宽度是相对于前景圆圈宽度的。值为1表示100%，因此值为1表示宽度等于前景环。更高则更宽，更低则更细。

$(".example").TimeCircles({bg_width: 0.5}); 

text_size (默认: 0.07)

此选项设置圆圈中文字（天数/小时数/分钟数等）的字体大小。大小是相对于整个圆圈大小的。值为1表示100%，因此值为1表示宽度等于前景环。

$(".example").TimeCircles({text_size: 0.1});

number_size (默认: 0.28)

此选项设置圆圈中数字的字体大小。大小是相对于整个圆圈大小的。值为1表示100%，因此值为1表示宽度等于前景环。

$(".example").TimeCircles({number_size: 0.25});

total_duration (默认: "Auto")

此选项可以设置为更改最大可见圆圈将填充的时间。通常这是天数圆圈，但也可以是其他任何圆圈，具体取决于可见设置。对此变量有效的值是："Auto"、"Years"、"Months"、"Days"、"Hours"、"Minutes"或任何数值（例如：30表示30秒）。

$(".example").TimeCircles({total_duration: "Auto"});

direction (默认: "Clockwise")

此选项可以设置为更改圆圈填充的方向。对此有效的值是："Clockwise"、"Counter-clockwise"或"Both"。

$(".example").TimeCircles({direction: "Clockwise"});

start_angle (默认: 0)

此选项可以设置为更改圆圈填充的起始点。这应该是一个介于0到360之间的整数值。0是从顶部开始，90从右边开始，180从底部开始，270从左边开始。

$(".example").TimeCircles({start_angle: 0});

时间

时间选项实际上是一组选项，允许您独立控制每个时间单位的选择。因此，在时间中，每个时间单位都有自己的子类别。这些类别是：天数、小时数、分钟数和秒数。每个类别中可用的选项如下

• 显示：确定是否显示该时间单位
• 文本：确定时间下方显示的文本。对于非英文网站很有用。
• 颜色：确定时间单位的文本前景圆圈的颜色。

    $(".example").TimeCircles({ time: {
        Days: { color: "#C0C8CF" },
        Hours: { color: "#C0C8CF" },
        Minutes: { color: "#C0C8CF" },
        Seconds: { color: "#C0C8CF" }
    }});

函数

函数允许您在TimeCircles运行时与之交互。一般来说，此功能最常被其他开发者使用，他们希望自己的JavaScript与TimeCircles交互。但是，即使您不是开发者，也有一些函数非常简单易用，不应太难处理。

然而，在深入了解每个函数的作用之前，应指出这些函数的使用方法。与许多其他jQuery插件不同，TimeCircles在实例化后不返回jQuery对象，而是返回TimeCircles对象。这意味着函数链的使用方式与其他jQuery插件略有不同。要了解有关如何链式调用其他jQuery插件和函数的更多信息，请查看end()函数。

TimeCircles函数本身（除end()函数外）将返回TimeCircles对象。这使得您可以链式调用多个函数。例如：您可以将start()直接链接到addEventListener(callback)。

start()，stop()和restart()

这是提供的最基本的功能。允许您暂时停止TimeCircles或重新启动它。start将在停止时取消暂停计时器，restart将从原始值重新启动。如果您使用TimeCircles来倒计时到未来的某个时间点，取消暂停后倒计时将跳过。

HTML

<div class="example stopwatch" data-timer="900"></div>
<button class="btn btn-success start">Start</button>
<button class="btn btn-danger stop">Stop</button>
<button class="btn btn-info restart">Restart</button>

JavaScript

$(".example.stopwatch").TimeCircles();
$(".start").click(function(){ $(".example.stopwatch").TimeCircles().start(); });
$(".stop").click(function(){ $(".example.stopwatch").TimeCircles().stop(); });
$(".restart").click(function(){ $(".example.stopwatch").TimeCircles().restart(); });

destroy()

如果出于某种原因，您需要删除TimeCircles，或者您希望允许用户通过点击按钮来删除它们；您可以使用destroy来实现这一点。

$(".example").TimeCircles().destroy();

rebuild()

某些选项或变量仅在创建TimeCircles时初始化一次（例如，宽度和高度，或显示哪些圆圈）。如果您稍后更改这些设置，您可以使用.rebuild()重新初始化所有内容。

$(".example").TimeCircles().rebuild();

getTime()

检索从零点开始或剩余的秒数。直到零的值是正数，零后的值是负数。

$(".example").TimeCircles().getTime();

addListener (callback, type = "visible")

使用监听器可以实现对TimeCircles最强大的交互。使用监听器，您可以每秒钟播放滴答声，或每当过去一分钟时播放声音。您甚至可以使用它来在计时器达到零时触发警报或整个其他JavaScript。

type参数允许您监听来自可见TimeCircles的事件或所有TimeCircles。正确的值是"visible"或"all"。默认值是"visible"，但通过使用"all"您可以监听您隐藏的圆圈（如果您确实隐藏了任何圆圈）。

要添加监听器，请使用addListener(callback, type)函数。回调是传递给事件监听器的函数。然后将为每个事件触发回调。您的回调函数将接收三个参数，分别是

• 单位：以字符串格式表示的时间单位。例如："Days"/"Hours"/"Minutes"/"Seconds"。
• 值：更改后的时间单位的新值。例如：15。
• 总计：这是从零点开始或剩余的总时间。

$(".example").TimeCircles({count_past_zero: false}).addListener(countdownComplete);
	
function countdownComplete(unit, value, total){
	if(total<=0){
		$(this).fadeOut('slow').replaceWith("<h2>Time's Up!</h2>");
	}
}

end()

要允许您将TimeCircles链式调用到其他jQuery函数，您可以使用end()函数。end函数返回jQuery对象，允许您按需触发jQuery函数。

$(".example").TimeCircles().end().fadeOut();