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
- ECMAScript® 2024 Language Specification — Date.prototype.getUTCFullYear
- ECMAScript® 2024 Language Specification — Date.prototype.setUTCFullYear
- ECMAScript® 2024 Language Specification — Date.UTC
- ECMAScript® 2024 Language Specification — TimeClip
- Date.prototype.getUTCFullYear() - JavaScript | MDN
- Date.prototype.setUTCFullYear() - JavaScript | MDN