JavaScript метод Date.setUTCDate()

Определение и применение

JavaScript метод setUTCDate() объекта Date устанавливает день месяца для указанной даты по всемирному времени.

В качестве возвращаемого значения метода setUTCDate() вы получаете количество миллисекунд между 1 января 1970 00:00:00 UTC и заданной датой.

Поддержка браузерами

Спецификация: ecma262

Поддерживается во всех основных браузерах с 2015 года.

Показать браузеры
Совместимостьjavascript.builtins.Date.setUTCDate
ВозможностьКомпьютерыМобильные
ChromeEdgeFirefoxOperaSafariChrome AndroidFirefox for AndroidOpera AndroidSafari on iOSSamsung BrowserWebView AndroidWebView on iOS
setUTCDate✓1✓12✓1✓4✓1✓18✓4✓10.1✓1✓1.0✓4.4✓1

поддерживаетсяс ограниченияминет поддержкинет данных≤31 — не позднее версии 31

JavaScript синтаксис

JavaScript
dateObj.setUTCDate(dayValue);

Значения параметров

setUTCDate(): параметры
Параметр Описание
dayValue Целое число, представляющее день месяца. Обязательный параметр.
Ожидаемые значения лежат в диапазоне от 1 до 31, но другие значения возможны, например:
  • значение 0 приведет к последнему дню предыдущего месяца
  • значение -1 приведет ко дню, предшествующему последнему дню предыдущего месяца, значение -10 соответственно приведет к сдвигу назад от последнего дня предыдущего месяца.
Если месяц имеет 30 дней, то значение 31 будет соответствовать первому дню следующего месяца, а значение 35 пятому дню следующего месяца и так далее.

Возвращаемое значение и особенности

Метод изменяет исходный объект и возвращает новую метку времени — число миллисекунд от 1970-01-01T00:00:00.000Z, а не объект Date. Если аргумент преобразуется в NaN (в том числе явно переданный undefined), дата становится недействительной и возвращается NaN. Пропуск обязательного аргумента также приводит к NaN.

Аргументы преобразуются к числам; дробная часть отбрасывается. Бесконечные значения и результат за пределами диапазона Date (±8,64 × 1015 миллисекунд от эпохи) дают Invalid Date.

Значения за пределами обычного диапазона, включая отрицательные, переносятся в соседние компоненты даты.

Если исходный объект содержит Invalid Date, этот метод не восстанавливает его: результат остаётся NaN.

Изменяется день месяца по UTC. Местный переход на летнее время не влияет на расчёт UTC; метод не устанавливает день недели.

Спецификация

ECMAScript — Date.prototype.setUTCDate(). Метод входит в стандарт начиная с ECMAScript 1.

Примеры, попробуйте сами

setUTCDate() — пример 1

Измените аргументы и нажмите ▶. Каждый вызов в этом примере начинается с исходной даты; сравните результат в UTC с комментариями.

index.html
HTML
<p>Результат выполнения выводится в консоль.</p>
main.js
JavaScript
// Исходный момент и вывод явно заданы по UTC.
let someDay

someDay = new Date('2019-02-14T12:00:00Z')
someDay.setUTCDate(0) // Изменяем день месяца по UTC.
console.log(someDay.toISOString()) // "2019-01-31T12:00:00.000Z"

someDay = new Date('2019-02-14T12:00:00Z')
someDay.setUTCDate(10) // Изменяем день месяца по UTC.
console.log(someDay.toISOString()) // "2019-02-10T12:00:00.000Z"

someDay = new Date('2019-02-14T12:00:00Z')
someDay.setUTCDate(20) // Изменяем день месяца по UTC.
console.log(someDay.toISOString()) // "2019-02-20T12:00:00.000Z"

someDay = new Date('2019-02-14T12:00:00Z')
someDay.setUTCDate(31) // Изменяем день месяца по UTC.
console.log(someDay.toISOString()) // "2019-03-03T12:00:00.000Z"

someDay = new Date('2019-02-14T12:00:00Z')
someDay.setUTCDate(-1) // Изменяем день месяца по UTC.
console.log(someDay.toISOString()) // "2019-01-30T12:00:00.000Z"

someDay = new Date('2019-02-14T12:00:00Z')
someDay.setUTCDate(-10) // Изменяем день месяца по UTC.
console.log(someDay.toISOString()) // "2019-01-21T12:00:00.000Z"

someDay = new Date('2019-02-14T12:00:00Z')
someDay.setUTCDate(-40) // Изменяем день месяца по UTC.
console.log(someDay.toISOString()) // "2018-12-22T12:00:00.000Z"

Возвращаемая метка и Invalid Date

Сравните результат метода с getTime(). Явно переданный undefined делает дату недействительной.

index.html
HTML
<p>Результат выполнения выводится в консоль.</p>
main.js
JavaScript
const date = new Date('2019-02-14T12:00:00Z')
const timestamp = date.setUTCDate(20)
console.log(typeof timestamp) // "number"
console.log(timestamp === date.getTime()) // true

console.log(date.setUTCDate(undefined)) // NaN
console.log(Number.isNaN(date.getTime())) // true