SetUTCFullYear: примеры (JAVASCRIPT)

Простые примеры использования

Установка только года:

const date = new Date('2023-08-15T12:00:00Z');
date.setUTCFullYear(2025);
console.log(date.toISOString());

2025-08-15T12:00:00.000Z

Установка года и месяца:

const date = new Date('2023-08-15T12:00:00Z');
date.setUTCFullYear(2025, 5); // июнь (месяц 5)
console.log(date.toISOString());

2025-06-15T12:00:00.000Z

Установка года, месяца и дня:

const date = new Date('2023-08-15T12:00:00Z');
date.setUTCFullYear(2025, 10, 25); // 25 ноября
console.log(date.toISOString());

2025-11-25T12:00:00.000Z

Альтернативные функции в JavaScript

setFullYear() - устанавливает год для указанной даты в местном часовом поясе. Отличие от setUTCFullYear() заключается в учете локального времени.

setUTCMonth() и setUTCDate() - позволяют устанавливать месяц и день по UTC отдельно.

Date.UTC() - статический метод, возвращающий количество миллисекунд с 1 января 1970 года для указанной даты в UTC.

Выбор между setUTCFullYear() и setFullYear() зависит от требований приложения: для работы с серверным временем или в международных приложениях предпочтительнее использовать UTC-методы.

Типичные ошибки

Путаница между UTC и локальным временем:

const date = new Date(2023, 7, 15); // локальное время
console.log('Исходная:', date.toISOString());
date.setUTCFullYear(2025);
console.log('После setUTCFullYear:', date.toISOString());

Исходная: 2023-08-14T21:00:00.000Z
После setUTCFullYear: 2025-08-14T21:00:00.000Z

Использование двузначных годов (может привести к неоднозначности):

const date = new Date('2023-08-15T12:00:00Z');
date.setUTCFullYear(25); // 1925 или 2025?
console.log(date.getUTCFullYear());

1925

Выход за допустимые диапазоны значений (автоматическая корректировка):

const date = new Date('2023-08-15T12:00:00Z');
date.setUTCFullYear(2025, 15, 40); // месяц 15, день 40
console.log(date.toISOString());

2026-04-09T12:00:00.000Z

Изменения в спецификации

Метод setUTCFullYear() был введен в ECMAScript 1 (1997 год) и с тех пор остается стабильным. В ECMAScript 2015 (ES6) были уточнены некоторые аспекты поведения при недопустимых значениях параметров, но базовый функционал не изменился.

В современных версиях JavaScript рекомендуется использовать четырехзначные значения годов для избежания неоднозначности, связанной с двузначными годами.

Расширенные примеры

Обработка високосных годов:

const date = new Date('2024-02-29T12:00:00Z'); // високосный год
console.log('Исходная:', date.toISOString());

// Установка 2025 года (не високосный)
date.setUTCFullYear(2025);
console.log('После установки 2025:', date.toISOString()); // 1 марта

// Установка 2028 года (високосный)
date.setUTCFullYear(2028, 1, 29); // 29 февраля 2028
console.log('29 февраля 2028:', date.toISOString());

Исходная: 2024-02-29T12:00:00.000Z
После установки 2025: 2025-03-01T12:00:00.000Z
29 февраля 2028: 2028-02-29T12:00:00.000Z

Пакетное обновление дат в массиве:

const dates = [
  new Date('2023-01-15T00:00:00Z'),
  new Date('2023-06-20T00:00:00Z'),
  new Date('2023-12-05T00:00:00Z')
];

dates.forEach(date => {
  date.setUTCFullYear(2025);
});

console.log(dates.map(d => d.toISOString()));

["2025-01-15T00:00:00.000Z",
 "2025-06-20T00:00:00.000Z",
 "2025-12-05T00:00:00.000Z"]

Создание дат для повторяющихся событий:

function createEventSeries(startDate, count, intervalYears) {
  const events = [];
  const date = new Date(startDate);
  
  for(let i = 0; i < count; i++) {
    const eventDate = new Date(date);
    eventDate.setUTCFullYear(date.getUTCFullYear() + i * intervalYears);
    events.push(eventDate.toISOString().split('T')[0]);
  }
  return events;
}

console.log(createEventSeries('2023-08-15', 5, 2));

["2023-08-15", "2025-08-15", "2027-08-15", "2029-08-15", "2031-08-15"]

Аналоги в других языках программирования

PHP: метод modify() объекта DateTime:

$date = new DateTime('2023-08-15 12:00:00', new DateTimeZone('UTC'));
$date->modify('2025 year');
echo $date->format('Y-m-d H:i:s');

2025-08-15 12:00:00

Python: метод replace() объекта datetime:

from datetime import datetime, timezone
date = datetime(2023, 8, 15, 12, 0, 0, tzinfo=timezone.utc)
date = date.replace(year=2025)
print(date.isoformat())

2025-08-15T12:00:00+00:00

MySQL: функция DATE_ADD() или арифметика дат:

SELECT DATE_ADD('2023-08-15 12:00:00', INTERVAL 2 YEAR) AS new_date;

2025-08-15 12:00:00

В отличие от JavaScript, в Python и PHP обычно используются неизменяемые объекты даты, поэтому методы возвращают новые объекты.