CKTIS / JavaScript
Odczyt i zmiana roku w UTC w obiekcie Date
`getUTCFullYear()` odczytuje rok w UTC, a `setUTCFullYear()` zmienia ten sam obiekt `Date` i zwraca znacznik czasu. Pominięcie argumentu nie działa tak samo jak przekazanie `undefined`.
Wersja: ECMAScript 2024 and the current web platform; runtime support varies
Składnia
date.getUTCFullYear()
date.setUTCFullYear(year)
date.setUTCFullYear(year, monthIndex)
date.setUTCFullYear(year, monthIndex, dayOfMonth)getUTCFullYear() nie przyjmuje argumentów i zwraca rok kalendarzowy w UTC jako liczbę całkowitą, nie jako czterocyfrowy tekst. Dla nieprawidłowej daty zwraca NaN. Z kolei getFullYear() i setFullYear() działają według lokalnej strefy czasowej środowiska. Na przełomie roku ten sam moment może należeć do innego roku w UTC niż lokalnie.
setUTCFullYear(year, monthIndex, dayOfMonth) modyfikuje istniejący obiekt Date i zwraca nowy znacznik czasu w milisekundach od epoki Uniksa. Rok jest wymagany; opcjonalny miesiąc jest liczony od 0 (styczeń) do 11 (grudzień), a dzień miesiąca od 1. Aby podać dzień, trzeba podać też miesiąc. Pominięte składowe oraz pora dnia pochodzą z dotychczasowej daty w UTC. Wartości spoza zwykłego zakresu są normalizowane: 29 lutego po zmianie roku na nieprzestępny staje się 1 marca.
Argumenty są konwertowane na liczby. Jawne undefined nie oznacza pominięcia: daje NaN. Gdy argument po konwersji daje NaN lub wynikowy znacznik czasu wypada poza zakresem Date, metoda zapisuje i zwraca NaN. Jeśli obiekt był już nieprawidłowy, punktem wyjścia jest 1970-01-01T00:00:00.000Z, więc poprawne wywołanie może go naprawić.
W odróżnieniu od Date.UTC() metoda setUTCFullYear() nie dodaje 1900 do lat od 0 do 99. Obie metody prototypu wymagają, by this było rzeczywistym obiektem Date; wywołanie z nieodpowiednim this powoduje TypeError.
Przykłady
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());Wynik
2024 1677674096789 2023-03-01T12:34:56.789Z NaN NaN 0007-01-01T00:00:00.000Z
Zmiana roku na 2023 przesuwa 29 lutego na 1 marca bez zmiany pory dnia w UTC. Jawne `undefined` unieważnia datę, a ustawienie roku `7` przywraca poprawną datę: 1 stycznia roku 7 o północy UTC.
Powiązane lekcje
- JavaScript · Lekcja 5 · Zaawansowany · Wersja: 4
Źródła
- 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