setUTCFullYear() - изменение года по UTC в JavaScript

setUTCFullYear() изменяет год в объекте Date по UTC. При необходимости он может сразу обновить не только год, но и месяц с днём.

Синтаксис

Базовая запись выглядит так:

date.setUTCFullYear(yearValue)
date.setUTCFullYear(yearValue, monthValue)
date.setUTCFullYear(yearValue, monthValue, dateValue)

Где:

• date - это объект Date
• yearValue - новый год по UTC
• monthValue - необязательный месяц от 0 до 11
• dateValue - необязательный день месяца

Что возвращает setUTCFullYear()

Метод возвращает timestamp - количество миллисекунд с 1 января 1970 года.

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));
const result = date.setUTCFullYear(2030);

console.log(typeof result); // "number"
console.log(result === date.getTime()); // true
console.log(date.toISOString()); // "2030-01-15T12:30:00.000Z"

Это важно: setUTCFullYear() возвращает число, а не новый объект Date.

Простой пример

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

date.setUTCFullYear(2030);

console.log(date.getUTCFullYear()); // 2030
console.log(date.toISOString()); // "2030-01-15T12:30:00.000Z"

Здесь:

• 2025 - исходный год
• 0 - январь
• 15 - день месяца

После вызова метода год по UTC становится 2030.

Можно сразу изменить год, месяц и день

У setUTCFullYear() есть дополнительные аргументы.

С их помощью можно за один вызов изменить сразу несколько частей даты по UTC.

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

date.setUTCFullYear(2030, 5, 20);

console.log(date.getUTCFullYear()); // 2030
console.log(date.getUTCMonth()); // 5
console.log(date.getUTCDate()); // 20
console.log(date.toISOString()); // "2030-06-20T12:30:00.000Z"

Здесь:

• 2030 - новый год
• 5 - июнь
• 20 - день месяца

Важно помнить: месяц здесь тоже начинается с 0.

setUTCFullYear() меняет исходную дату

Это главное отличие от методов вроде getUTCFullYear().

setUTCFullYear() не просто читает значение, а изменяет сам объект Date.

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

date.setUTCFullYear(2030);

console.log(date.getUTCFullYear()); // 2030

Если объект даты используется в нескольких местах, это поведение важно учитывать.

Чем setUTCFullYear() отличается от getUTCFullYear()

Эти методы связаны, но делают разное.

• getUTCFullYear() читает год по UTC
• setUTCFullYear() изменяет год по UTC

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

console.log(date.getUTCFullYear()); // 2025

date.setUTCFullYear(2030);

console.log(date.getUTCFullYear()); // 2030

setUTCFullYear() работает именно по UTC

Это главный момент.

Метод setUTCFullYear() изменяет дату с точки зрения UTC, а не локального часового пояса пользователя.

Если вы работаете с серверным временем, ISO-строками и данными из API, это поведение обычно удобнее и предсказуемее.

Чем setUTCFullYear() отличается от setFullYear()

Разница такая:

• setUTCFullYear() изменяет год по UTC
• setFullYear() изменяет год по локальному времени

Это особенно важно возле границы года.

const date = new Date("2024-12-31T23:30:00-02:00");

date.setUTCFullYear(2030);

console.log(date.toISOString()); // "2030-01-01T01:30:00.000Z"

У setFullYear() похожий вызов может дать другой момент времени, потому что он ориентируется на локальный часовой пояс пользователя.

Дата может сдвинуться при смене года

Это полезный нюанс.

Если текущая дата существует в одном году, но не существует в другом, JavaScript автоматически нормализует результат.

const date = new Date(Date.UTC(2024, 1, 29, 12, 0, 0));

date.setUTCFullYear(2025);

console.log(date.toISOString()); // "2025-03-01T12:00:00.000Z"

Здесь 29 февраля 2024 года превращается в 1 марта 2025 года, потому что в 2025 году такого дня нет.

Invalid Date можно восстановить через setUTCFullYear()

Это поведение встречается не так часто, но оно полезно.

Если объект даты невалидный, setUTCFullYear() с корректным значением может сделать его снова рабочим.

const date = new Date("invalid");

date.setUTCFullYear(2025);

console.log(date.toISOString()); // "2025-01-01T00:00:00.000Z"
console.log(date.getUTCFullYear()); // 2025
console.log(date.getUTCMonth()); // 0
console.log(date.getUTCDate()); // 1

В таком случае дата восстанавливается как 1 января 00:00:00.000 UTC указанного года.

Невалидное значение делает дату Invalid Date

Если в setUTCFullYear() передать NaN или значение, которое превращается в NaN, результатом будет невалидная дата.

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

console.log(date.setUTCFullYear(NaN)); // NaN
console.log(String(date)); // "Invalid Date"

Это важно помнить, если год приходит из формы, API или пользовательского ввода.

setUTCFullYear() не создаёт новый объект даты

Этот метод не создаёт новую дату рядом со старой.

Он изменяет уже существующий объект Date.

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));
const sameDate = date;

date.setUTCFullYear(2030);

console.log(sameDate.toISOString()); // "2030-01-15T12:30:00.000Z"

Обе переменные указывают на один и тот же объект.

Когда это полезно

setUTCFullYear() особенно удобен, когда:

• дата хранится в UTC
• вы работаете с серверным временем
• нужно одинаковое поведение независимо от часового пояса пользователя
• нужно менять год у ISO-дат и данных из API

Пример:

const expiresAt = new Date("2025-01-15T12:00:00Z");

expiresAt.setUTCFullYear(2026);

console.log(expiresAt.toISOString()); // "2026-01-15T12:00:00.000Z"

Частые ошибки

Ожидать новый объект Date, а не изменение старого

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

date.setUTCFullYear(2030);

console.log(date.toISOString()); // "2030-01-15T12:30:00.000Z"

Метод меняет исходный объект.

Ожидать объект Date в результате

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));
const result = date.setUTCFullYear(2030);

console.log(typeof result); // "number"

Результат метода - timestamp, а не объект даты.

Забывать, что monthValue начинается с 0

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

date.setUTCFullYear(2030, 0, 1);

console.log(date.getUTCMonth()); // 0

Январь здесь - это 0, а не 1.

Путать setUTCFullYear() и getUTCFullYear()

const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

console.log(date.getUTCFullYear()); // 2025
date.setUTCFullYear(2030);

Один метод читает значение, другой его изменяет.

Путать setUTCFullYear() и setFullYear()

const date = new Date("2024-12-31T23:30:00-02:00");

date.setUTCFullYear(2030);

console.log(date.toISOString()); // "2030-01-01T01:30:00.000Z"

Если важен именно UTC, лучше использовать setUTCFullYear(), а не локальную версию setFullYear().

Не учитывать сдвиг даты на 29 февраля

const date = new Date(Date.UTC(2024, 1, 29, 12, 0, 0));

date.setUTCFullYear(2025);

Дата может автоматически перейти на следующий допустимый день.

Быстрая памятка

• setUTCFullYear() вызывается у объекта Date
• метод изменяет исходную дату
• результатом является timestamp
• можно передать только год или сразу год, месяц и день
• monthValue считается от 0 до 11
• setUTCFullYear() работает по UTC
• для локального времени есть setFullYear()
• у невалидного аргумента результатом будет Invalid Date
• невалидную дату можно восстановить корректным годом

Коротко

setUTCFullYear() в JavaScript нужен, чтобы изменить год в объекте Date по UTC. Главное, что стоит запомнить: метод меняет исходную дату, возвращает timestamp, может сразу принять месяц и день, работает именно по UTC и отличается от getUTCFullYear() тем, что не читает значение, а изменяет его.