Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

Ler e alterar o ano UTC de um objeto Date

`getUTCFullYear()` lê o ano em UTC. `setUTCFullYear()` altera o mesmo objeto `Date` e devolve o novo carimbo temporal. Omitir um argumento não é o mesmo que passar `undefined`.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

date.getUTCFullYear()
date.setUTCFullYear(year)
date.setUTCFullYear(year, monthIndex)
date.setUTCFullYear(year, monthIndex, dayOfMonth)

getUTCFullYear() não recebe argumentos e devolve o ano civil em UTC como um número inteiro, não como uma cadeia de quatro algarismos. Se a data for inválida, devolve NaN. Já getFullYear() e setFullYear() usam o fuso horário local do ambiente de execução. Perto da passagem de ano, o mesmo instante pode pertencer a anos diferentes em UTC e na hora local.

setUTCFullYear(year, monthIndex, dayOfMonth) modifica o objeto Date existente e devolve o novo carimbo temporal em milissegundos desde a época Unix. O ano é obrigatório; o índice opcional do mês vai de 0 (janeiro) a 11 (dezembro), e o dia do mês começa em 1. Para indicar o dia, é preciso indicar também o mês. Os componentes omitidos e a hora do dia são obtidos da data UTC existente. Os valores fora do intervalo habitual são normalizados: 29 de fevereiro passa a 1 de março ao mudar para um ano não bissexto.

Os argumentos são convertidos em números. Passar explicitamente undefined não equivale a omiti-lo: o valor é convertido em NaN. Se um argumento for convertido em NaN ou o carimbo temporal resultante ficar fora do intervalo de Date, o método guarda e devolve NaN. Se a data já for inválida, o ponto de partida é 1970-01-01T00:00:00.000Z, pelo que uma chamada válida pode recuperá-la.

Ao contrário de Date.UTC(), setUTCFullYear() não soma 1900 aos anos de 0 a 99. Ambos os métodos do protótipo exigem que this seja um verdadeiro objeto Date; uma chamada com um recetor incompatível lança um TypeError.

Exemplos

const date = new Date('2024-02-29T12:34:56.789Z');
console.log(date.getUTCFullYear());
console.log(date.setUTCFullYear(2023));
console.log(date.toISOString());
console.log(date.setUTCFullYear(2023, undefined));
console.log(date.getUTCFullYear());
date.setUTCFullYear(7);
console.log(date.toISOString());

Resultado

2024
1677674096789
2023-03-01T12:34:56.789Z
NaN
NaN
0007-01-01T00:00:00.000Z

Ao mudar para 2023, 29 de fevereiro passa a 1 de março sem alterar a hora UTC. Passar explicitamente `undefined` invalida a data; definir o ano como `7` volta a produzir uma data válida: 1 de janeiro do ano 7 à meia-noite UTC.

Lições relacionadas

  • JavaScript · Lição 5 · Avançado · Versão: 4

Fontes