O que ele faz

Você adiciona um elemento com uma data alvo na página e este script substituirá a data por uma contagem regressiva até que o dia/hora/minuto/segundo seja atingido.

Installation

Criando uma contagem regressiva

Uma contagem regressiva pode ser adicionada em uma página usando o seguinte formato:

<span class="countdown" style="display:none;">Apenas <span class="countdowndate">January 01 2027 00:00:00</span> até o próximo ano...</span>

O texto dentro de "countdown" só aparece quando a contagem está ativa. Qualquer texto antes de "countdowndate" precederá a contagem, e qualquer texto depois de "countdowndate" seguirá a contagem.

O exemplo acima produz:

Apenas January 01 2027 00:00:00 até o próximo ano...(Exemplo de contagem regressiva)

Um span opcional com a classe "nocountdown" pode ser usado como texto alternativo caso o script da contagem não funcione ou enquanto estiver carregando.

• Por exemplo, usar <span class="nocountdown">Já é quase ano novo!</span> resulta em
  "Já é quase ano novo!" enquanto o script carrega.

Este span deve ser colocado diretamente após o código de contagem acima.

Fusos horários

Usando o código de exemplo acima, a contagem funcionará de acordo com o fuso horário do leitor. Em casos como uma contagem de ano novo, isso é útil, mas pode não fazer sentido em outros contextos.

Dois métodos podem ser usados para fazer a contagem funcionar de acordo com um fuso horário específico. O mais fácil é adicionar o identificador do fuso horário ao final do código. Por exemplo, para fazer uma contagem para Eastern Standard Time (EST):

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

Este método funciona com a maioria dos identificadores, mas não funciona com algumas variantes do horário de verão (ex.: British Summer Time - BST).

Uma alternativa e método mais confiável é adicionar o Tempo Universal Coordenado (UTC) ao final do código. Por exemplo, para uma contagem regressiva para EST, que em relação ao UTC é -5 horas:

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

Note que as mudanças do horário de verão não são feitas automaticamente e devem ser ajustadas pelo usuário — seja com o identificador do horário de verão ou usando o UTC.

Opções

Finalizando a contagem

Como você quer que a contagem termine? Existem cinco opções:

1. contagem progressiva a partir de zero — esta é a opção padrão
2. remover o contêiner da contagem
3. parar a contagem em zero
4. substituir a contagem por outra coisa
5. chamar uma função JavaScript personalizada de sua escolha

Contagem progressiva

Como esta é a opção padrão, você não precisa fazer nada.

Remover

Adicione um atributo data-end com o valor "remove" ao contêiner:

<span data-end="remove" class="countdown" style="display:none;"><!--
-->Apenas <span class="countdowndate">January 01 2027 00:00:00</span> até o próximo ano...<!--
--></span>

Parar

Adicione um atributo data-end com o valor "stop" ao contêiner:

<span data-end="stop" class="countdown" style="display:none;"><!--
-->Apenas <span class="countdowndate">January 01 2027 00:00:00</span> até o próximo ano...<!--
--></span>

Substituir

Adicione um atributo data-end com o valor "toggle" ao contêiner. Além disso, você precisará adicionar um atributo data-toggle com o seletor que aponta para o substituto:

<span data-end="toggle" data-toggle=".post-countdown" class="countdown" style="display:none;"><!--
-->Apenas <span class="countdowndate">January 01 2027 00:00:00</span> até o próximo ano...<!--
--></span><span class="post-countdown" style="display:none;">Feliz 2027!</span>

Observe o ponto no valor de data-toggle! O valor esperado é um seletor CSS ou jQuery. Portanto, usa-se ".nome" para classes, "#nome" para IDs, etc.

Alternativamente, se o contêiner de alternância (toggle) for o elemento imediatamente após o contador, o valor especial data-toggle="next" pode ser usado, sem a necessidade de especificar um seletor. Isso é útil ao usar várias contagens regressivas como parte de uma predefinição, por exemplo.

Chamada Personalizada

Adicione um atributo data-end com o valor "callback" ao contêiner. Além disso, você precisará adicionar um atributo data-callback com o nome da função que deseja chamar:

<span data-end="callback" data-callback="myFunction" class="countdown" style="display:none;"><!--
-->Apenas <span class="countdowndate">January 01 2027 00:00:00</span> até o próximo ano...<!--
--></span>

A contagem parará em zero e então sua função será chamada. O contêiner da contagem será o objeto this da função.

Para tornar a função disponível para o módulo Countdown, você precisará adicioná-la ao próprio módulo:

window.countdownTimer = {
    myFunction: function () {
       $(this).text("Feliz 2027!");
    }
}

Zeros à esquerda

Por padrão, os zeros serão mostrados:

0 dias, 0 horas, 10 minutos e 10 segundos

Mas se você preferir assim:

10 minutos e 10 segundos

Você precisa adicionar o atributo data-options com o valor "no-leading-zeros":

<span data-options="no-leading-zeros" class="countdown" style="display:none;"><!--
-->Apenas <span class="countdowndate">January 01 2027 00:00:00</span> até o próximo ano...<!--
--></span>

Formato curto

Se preferir mostrar a contagem em um formato curto como 2d 5h 30m 1s em vez de palavras inteiras, você deve adicionar o atributo data-options com o valor "short-format".

Se você já definiu um atributo data-options, adicione todas as opções, separando-as com um espaço:

<span data-options="no-leading-zeros short-format" class="countdown" style="display:none;"><!--
-->Apenas <span class="countdowndate">January 01 2027 00:00:00</span> até o próximo ano...<!--
--></span>

Conteúdo Dinâmico

Este script suporta conteúdo inserido dinamicamente, como comentários de artigos ou pré-visualizações do editor. No entanto, se você inserir um contador via JavaScript, precisará disparar este evento após a inserção:

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

Onde ELEMENTO é um seletor para o elemento no qual o contador foi inserido.

Registro de alterações