Learn JavaScript
Справочник / setUTCDate()

setUTCDate() - изменение дня месяца по UTC в JavaScript

setUTCDate() изменяет день месяца в объекте Date по UTC, меняет существующую дату. При этом метод может автоматически сдвинуть месяц или даже год, если передать значение за пределами обычного диапазона.

Синтаксис

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

date.setUTCDate(dayValue)

Где:

  • date - это объект Date
  • dayValue - новый день месяца по UTC

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

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

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

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

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

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

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

date.setUTCDate(20);

console.log(date.getUTCDate()); // 20
console.log(date.toISOString()); // "2025-01-20T12:30:00.000Z"

Здесь:

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

После вызова метода день месяца по UTC становится 20.

Обычно используют значения от 1 до 31

В большинстве случаев в setUTCDate() передают обычный день месяца:

  • 1 - первое число
  • 15 - пятнадцатое число
  • 31 - тридцать первое число
const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

date.setUTCDate(1);

console.log(date.getUTCDate()); // 1

Но у setUTCDate() есть полезная особенность: он умеет работать и со значениями вне этого диапазона.

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

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

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

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

date.setUTCDate(20);

console.log(date.getUTCDate()); // 20

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

Чем setUTCDate() отличается от getUTCDate()

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

  • getUTCDate() читает день месяца по UTC
  • setUTCDate() изменяет день месяца по UTC
const date = new Date(Date.UTC(2025, 0, 15, 12, 30, 0));

console.log(date.getUTCDate()); // 15

date.setUTCDate(20);

console.log(date.getUTCDate()); // 20

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

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

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

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

Чем setUTCDate() отличается от setDate()

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

  • setUTCDate() изменяет день месяца по UTC
  • setDate() изменяет день месяца по локальному времени

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

const date = new Date("2025-03-01T00:30:00+03:00");

date.setUTCDate(1);

console.log(date.toISOString()); // "2025-02-01T21:30:00.000Z"

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

День месяца может выходить за пределы 1..31

Это одна из самых полезных особенностей Date.

Если передать значение больше допустимого, JavaScript автоматически перенесёт дату в следующий месяц.

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

date.setUTCDate(32);

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

Здесь 32 означает переход на 1 февраля 2025 года по UTC.

0 - это последний день предыдущего месяца

Этот приём часто используют на практике.

Если передать 0, дата перейдёт на последний день предыдущего месяца.

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

date.setUTCDate(0);

console.log(date.getUTCFullYear()); // 2024
console.log(date.getUTCMonth()); // 11
console.log(date.getUTCDate()); // 31
console.log(date.toISOString()); // "2024-12-31T12:00:00.000Z"

Здесь дата превращается в 31 декабря 2024 года по UTC.

setUTCDate() не меняет день недели напрямую

Это полезно помнить, потому что setUTCDate() работает именно с числом месяца.

Он не устанавливает понедельник, вторник или другой день недели.

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

date.setUTCDate(1);

console.log(date.getUTCDate()); // 1
console.log(date.getUTCDay()); // день недели считается отдельно

То есть setUTCDate(1) означает первое число месяца, а не воскресенье, понедельник или другой день недели.

Invalid Date не восстанавливается через setUTCDate()

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

const date = new Date("invalid");

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

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

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

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

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

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

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

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

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

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

date.setUTCDate(20);

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

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

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

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

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

Пример:

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

deadline.setUTCDate(1);

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

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

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

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

date.setUTCDate(20);

console.log(date.getUTCDate()); // 20

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

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

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

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

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

Думать, что setUTCDate() принимает только значения от 1 до 31

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

date.setUTCDate(32);

Ошибка не появится. JavaScript просто перенесёт дату в следующий месяц.

Забывать, что 0 - это не ошибка

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

date.setUTCDate(0);

Так можно получить последний день предыдущего месяца.

Путать день месяца и день недели

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

date.setUTCDate(1);
console.log(date.getUTCDay());

setUTCDate() работает с числом месяца, а не с днём недели.

Путать setUTCDate() и getUTCDate()

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

console.log(date.getUTCDate()); // 15
date.setUTCDate(20);

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

Путать setUTCDate() и setDate()

setUTCDate() работает по UTC, а setDate() - по локальному часовому поясу пользователя.

Если важен именно UTC, лучше использовать setUTCDate().

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

  • setUTCDate() вызывается у объекта Date
  • метод изменяет исходную дату
  • результатом является timestamp
  • обычно передают день месяца от 1 до 31
  • значения вроде 0 и 32 тоже допустимы и нормализуются автоматически
  • setUTCDate() работает по UTC
  • для локального времени есть setDate()
  • у невалидного аргумента результатом будет Invalid Date
  • Invalid Date через setUTCDate() не восстанавливается

Коротко

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

← setUTCMonth() - изменение месяца по UTC в JavaScript
setUTCHours() - изменение часов по UTC в JavaScript →