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

setUTCMilliseconds() - изменение миллисекунд по UTC в JavaScript

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

Синтаксис

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

date.setUTCMilliseconds(millisecondsValue)

Где:

  • date - это объект Date
  • millisecondsValue - новые миллисекунды по UTC

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

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

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));
const result = date.setUTCMilliseconds(900);

console.log(typeof result); // "number"
console.log(result === date.getTime()); // true
console.log(date.toISOString()); // "2025-01-15T10:20:30.900Z"

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

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

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

date.setUTCMilliseconds(900);

console.log(date.getUTCMilliseconds()); // 900
console.log(date.toISOString()); // "2025-01-15T10:20:30.900Z"

Здесь:

  • 2025 - год
  • 0 - январь
  • 15 - день месяца
  • 10 - часы
  • 20 - минуты
  • 30 - секунды
  • 400 - исходные миллисекунды

После вызова метода миллисекунды по UTC становятся 900.

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

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

  • 0 - начало секунды
  • 500 - середина секунды
  • 999 - последняя миллисекунда перед следующей секундой
const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

date.setUTCMilliseconds(0);

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

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

У setUTCMilliseconds() только один аргумент

Это важный нюанс.

В отличие от setUTCMinutes() или setUTCSeconds(), у setUTCMilliseconds() нет дополнительных аргументов для других частей времени.

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

date.setUTCMilliseconds(250);

console.log(date.getUTCMilliseconds()); // 250

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

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

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

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

date.setUTCMilliseconds(900);

console.log(date.getUTCMilliseconds()); // 900

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

Чем setUTCMilliseconds() отличается от getUTCMilliseconds()

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

  • getUTCMilliseconds() читает миллисекунды по UTC
  • setUTCMilliseconds() изменяет миллисекунды по UTC
const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

console.log(date.getUTCMilliseconds()); // 400

date.setUTCMilliseconds(900);

console.log(date.getUTCMilliseconds()); // 900

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

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

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

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

Чем setUTCMilliseconds() отличается от setMilliseconds()

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

  • setUTCMilliseconds() изменяет миллисекунды по UTC
  • setMilliseconds() изменяет миллисекунды по локальному времени

Здесь есть важный нюанс: на практике результат очень часто совпадает, потому что миллисекунды сами по себе обычно не зависят от часового пояса так заметно, как дата, часы или минуты. Но логически это всё равно разные системы времени.

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

date.setUTCMilliseconds(0);

console.log(date.toISOString()); // "2025-01-15T11:30:45.000Z"

Если в задаче важен именно UTC, лучше использовать setUTCMilliseconds(), даже если в простых примерах локальная версия даёт такой же результат.

Миллисекунды могут выходить за пределы 0..999

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

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

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 999));

date.setUTCMilliseconds(1000);

console.log(date.getUTCFullYear()); // 2025
console.log(date.getUTCMonth()); // 0
console.log(date.getUTCDate()); // 15
console.log(date.getUTCHours()); // 10
console.log(date.getUTCMinutes()); // 20
console.log(date.getUTCSeconds()); // 31
console.log(date.getUTCMilliseconds()); // 0
console.log(date.toISOString()); // "2025-01-15T10:20:31.000Z"

Здесь 1000 означает переход на начало следующей секунды по UTC.

Можно перейти и на предыдущий день

Если передать отрицательное значение, JavaScript сдвинет дату назад.

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

date.setUTCMilliseconds(-1);

console.log(date.getUTCFullYear()); // 2025
console.log(date.getUTCMonth()); // 0
console.log(date.getUTCDate()); // 14
console.log(date.getUTCHours()); // 23
console.log(date.getUTCMinutes()); // 59
console.log(date.getUTCSeconds()); // 59
console.log(date.getUTCMilliseconds()); // 999
console.log(date.toISOString()); // "2025-01-14T23:59:59.999Z"

Здесь время переходит на предыдущий день по UTC.

setUTCMilliseconds() не меняет секунды сам по себе

Это полезно помнить.

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

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

date.setUTCMilliseconds(900);

console.log(date.getUTCSeconds()); // 30
console.log(date.getUTCMilliseconds()); // 900

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

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

const date = new Date("invalid");

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

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

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

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

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

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

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

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

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

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

date.setUTCMilliseconds(900);

console.log(sameDate.getUTCMilliseconds()); // 900

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

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

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

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

Пример:

const eventTime = new Date("2025-01-15T10:20:30.400Z");

eventTime.setUTCMilliseconds(0);

console.log(eventTime.toISOString()); // "2025-01-15T10:20:30.000Z"

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

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

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

date.setUTCMilliseconds(900);

console.log(date.getUTCMilliseconds()); // 900

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

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

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));
const result = date.setUTCMilliseconds(900);

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

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

Думать, что значение больше 999 вызовет ошибку

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 999));

date.setUTCMilliseconds(1000);

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

Забывать про переход на предыдущий день

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

date.setUTCMilliseconds(-1);

Отрицательное значение может перенести время назад.

Путать setUTCMilliseconds() и getUTCMilliseconds()

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

console.log(date.getUTCMilliseconds()); // 400
date.setUTCMilliseconds(900);

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

Думать, что setUTCMilliseconds() меняет полный timestamp напрямую

const date = new Date(Date.UTC(2025, 0, 15, 10, 20, 30, 400));

date.setUTCMilliseconds(900);

Метод меняет только часть времени внутри даты, а не заменяет timestamp целиком вручную.

Путать setUTCMilliseconds() и setMilliseconds()

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

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

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

  • setUTCMilliseconds() вызывается у объекта Date
  • метод изменяет исходную дату
  • результатом является timestamp
  • у метода только один аргумент
  • обычно миллисекунды идут от 0 до 999
  • значения меньше 0 и больше 999 нормализуются автоматически
  • setUTCMilliseconds() работает по UTC
  • для локального времени есть setMilliseconds()
  • у невалидного аргумента результатом будет Invalid Date
  • Invalid Date через setUTCMilliseconds() не восстанавливается

Коротко

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

← setUTCSeconds() - изменение секунд по UTC в JavaScript
toISOString() - ISO-строка даты в JavaScript →