Что он делает?

Вы добавляете на страницу элемент с указанной в нем датой, а скрипт заменит его на счетчик, показывающий, сколько еще дней, часов, минут и секунд осталось до достижения этой даты.

Installation

Создание обратного отсчета

Счетчик можно добавить, используя следующий формат:

<span class="countdown" style="display:none;">До Нового года осталось всего <span class="countdowndate">January 01 2027 00:00:00</span>...</span>

Текст, находящийся внутри элемента countdown, будет виден только при активном счетчике. Элемент countdowndate можно сопровождать любым текстом, который не будет меняться.

Код выше дает такой результат:

До Нового года осталось всего January 01 2027 00:00:00...(Пример обратного отсчета)

Дополнительный элемент с классом nocountdown позволяет указать текст, который будет показываться, пока скрипт загружается или если он не работает. Например, код <span class="nocountdown">Уже почти Новый год!</span> во время загрузки скрипта будет показывать "Уже почти новый год!". Этот элемент необходимо ставить сразу же после разметки счетчика, как в примере выше.

Часовые пояса

Код выше неудобен тем, что при расчете времени до даты скрипт будет полагаться на системное время читателя. В случае с Новым годом это не страшно, а вот в других случаях может подложить свинью.

Для работы с конкретным часовым поясом или часовой зоной можно использовать два варианта. Самый простой — указать идентефикатор пояса в конце требуемой даты. Например, будем считать относительно североамериканского восточного времени (EST):

<span class="countdowndate">January 01 2027 00:00:00 EST</span>

Хоть этот вариант работает с большинством аббревиатур, с некоторыми зонами, использующими летнее время, такой фокус не пройдет. Например, британское летнее время (British Summer Time, BST) определяться не будет.

Другой и более надежный метод — указать сдвиг относительно всемирного координированного времени (UTC). Предыдущий пример можно переписать следуюшим образом (пояс EST имеет сдвиг в минус пять часов):

<span class="countdowndate">January 01 2027 00:00:00 -0500</span>

Обратите внимание: скрипт не умеет сам переключать время с летнего на зимнее, и это должен делять сам пользователь с помощью одного из двух способов, описанных выше.

Настройки

Завершение отсчета

Таймер подойдет к концу, и что тогда делать? Есть пять вариантов:

1. считать дальше, начиная с нуля. Этот вариант используется по умолчанию;
2. удалить контейнер счетчика;
3. остановить отсчет на нуле;
4. заменить счетчик другим элементом;
5. вызвать пользовательскую функцию JavaScript.

Продолжение отсчета

Это стандартный вариант, так что тут делать ничего не надо.

Удаление

Добавьте в атрибут контейнера data-end значение remove:

<span data-end="remove" class="countdown" style="display:none;"><!--
-->До Нового года осталось всего <span class="countdowndate">January 01 2027 00:00:00</span>...<!--
--></span>

Остановка

Добавьте в атрибут контейнера data-end значение stop:

<span data-end="stop" class="countdown" style="display:none;"><!--
-->До Нового года осталось всего <span class="countdowndate">January 01 2027 00:00:00</span>...<!--
--></span>

Замена

Добавьте в атрибут контейнера data-end значение toggle. Дополнительно придется указать селектор нужного элемента в атрибуте data-toggle.

<span data-end="toggle" data-toggle=".post-countdown" class="countdown" style="display:none;"><!--
-->До Нового года осталось всего <span class="countdowndate">January 01 2027 00:00:00</span>...<!--
--></span><span class="post-countdown" style="display:none;">C 2027-м годом!</span>

Обратите внимание на точку в начале значения data-toggle! Это значение представляет собой CSS или jQuery-селектор. Таким образом, .name выбирает элементы по классу, а #name — по ID.

Если элемент, на который будет производиться замена, стоит сразу же после счетчика, можно использовать специальное значение data-toggle="next". Это полезно, если несколько обратных отсчетов используются в шаблоне.

Пользовательское действие

Добавьте в атрибут контейнера data-end значение callback. Дополнительно придется указать название вызываемой функции в атрибуте data-toggle.

<span data-end="callback" data-callback="myFunction" class="countdown" style="display:none;"><!--
-->До Нового года осталось всего <span class="countdowndate">January 01 2027 00:00:00</span>...<!--
--></span>

Отсчет будет остановлен на нуле, после чего будет вызвана указанная функция. В ее области видимости ключевое слово this будет обозначать контейнер счетчика. Чтобы скрипт мог обратиться к функции, его нужно указать отдельно:

window.countdownTimer = {
    myFunction: function () {
       $(this).text("C 2027-м годом!");
    }
}

Ведущие нули

По умолчанию ведущие нули отображаются:

0 дней, 0 часов, 10 минут и 10 секунд

Если вы предпочитайте такой вариант:

10 минут и 10 секунд

вам надо добавить в атрибут data-options значение no-leading-zeros:

<span data-options="no-leading-zeros" class="countdown" style="display:none;"><!--
-->До Нового года осталось всего <span class="countdowndate">January 01 2027 00:00:00</span>...<!--
--></span>

Короткий формат

Если вам больше нравится формат типа 2д 5ч 30м 1с, то вам нужно добавить значение short-format в атрибут data-options. Может быть так, что этот атрибут уже определен, и тогда необходимо разделить значения пробелом:

<span data-options="no-leading-zeros short-format" class="countdown" style="display:none;"><!--
-->До Нового года осталось всего <span class="countdowndate">January 01 2027 00:00:00</span>...<!--
--></span>

Динамический контент

Этот скрипт поддерживает содержимое, вставленное динамически (комментарии к статье или предпросмотр в редакторе). Однако, если вы добавляете счетчик средствами JavaScript, вам придется вручную запустить событие с помощью кода ниже:

mw.hook("wikipage.content").fire($("ELEMENT"));

ELEMENT — селектор элемента, в который был добавлен обратный отсчет.

Changelog