aboutsummaryrefslogtreecommitdiff
path: root/files/ru/web/javascript/reference/global_objects/intl/datetimeformat/index.html
blob: 0808b909cbe52a6737234164cbfc63ed3cea3767 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
---
title: Intl.DateTimeFormat
slug: Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat
tags:
  - DateTimeFormat
  - Internationalization
  - JavaScript
translation_of: Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat
---
<div>{{JSRef("Global_Objects", "DateTimeFormat", "Intl,Collator,NumberFormat")}}</div>

<h2 id="Summary">Сводка</h2>

<p>Объект <strong><code>Intl.DateTimeFormat</code></strong> является конструктором объектов, включающих языка-зависимое форматирование даты и времени.</p>

<h2 id="Syntax">Синтаксис</h2>

<pre class="syntaxbox"><code>new Intl.DateTimeFormat([<var>locales</var>[, <var>options</var>]])
Intl.DateTimeFormat.call(<var>this</var>[, <var>locales</var>[, <var>options</var>]])</code></pre>

<h3 id="Parameters">Параметры</h3>

<dl>
 <dt><code>locales</code></dt>
 <dd>
 <p>Необязательный параметр. Строка с языковой меткой BCP 47, либо массив таких строк. Описание общей формы и интерпретации аргумента <code>locales</code> смотрите на {{jsxref("Global_Objects/Intl", "странице, посвящённой объекту Intl", "#Locale_identification_and_negotiation", 1)}}. Разрешены следующие ключи расширения Unicode:</p>

 <dl>
  <dt><code>nu</code></dt>
  <dd>Используемая система нумерации. Возможные значения включают в себя: <code>"arab"</code>, <code>"arabext"</code>, <code>"bali"</code>, <code>"beng"</code>, <code>"deva"</code>, <code>"fullwide"</code>, <code>"gujr"</code>, <code>"guru"</code>, <code>"hanidec"</code>, <code>"khmr"</code>, <code>"knda"</code>, <code>"laoo"</code>, <code>"latn"</code>, <code>"limb"</code>, <code>"mlym"</code>, <code>"mong"</code>, <code>"mymr"</code>, <code>"orya"</code>, <code>"tamldec"</code>, <code>"telu"</code>, <code>"thai"</code>, <code>"tibt"</code>.</dd>
  <dt><code>ca</code></dt>
  <dd>Используемый календарь. Возможные значения включают в себя: <code>"buddhist"</code>, <code>"chinese"</code>, <code>"coptic"</code>, <code>"ethioaa"</code>, <code>"ethiopic"</code>, <code>"gregory"</code>, <code>"hebrew"</code>, <code>"indian"</code>, <code>"islamic"</code>, <code>"islamicc"</code>, <code>"iso8601"</code>, <code>"japanese"</code>, <code>"persian"</code>, <code>"roc"</code>.</dd>
 </dl>
 </dd>
 <dt><code>options</code></dt>
 <dd>
 <p>Необязательный параметр. Объект с некоторыми или всеми из следующих свойств:</p>

 <dl>
  <dt><code>localeMatcher</code></dt>
  <dd>Используемый алгоритм сопоставления локалей. Возможными значениями являются <code>"lookup"</code> и <code>"best fit"</code>; значением по умолчанию является <code>"best fit"</code>. Информацию по этой опции смотрите на {{jsxref("Global_Objects/Intl", "странице, посвящённой объекту Intl", "#Locale_negotiation", 1)}}.</dd>
  <dt><code>timeZone</code></dt>
  <dd>Используемый часовой пояс. Единственным значением, которые реализации обязаны распознавать, является <code>"UTC"</code>; значением по умолчанию является часовой пояс по умолчанию среды выполнения. Реализации также могут распознавать названия часовых поясов из <a href="https://www.iana.org/time-zones">базы данных часовых поясов IANA</a>, например <code>"Asia/Shanghai"</code>, <code>"Asia/Kolkata"</code> или <code>"America/New_York"</code>.</dd>
  <dt><code>hour12</code></dt>
  <dd>Определяет, использовать ли 12-часовой формат времени (в противовес 24-часовому). Возможными значениями являются <code>true</code> и <code>false</code>; значение по умолчанию зависит от локали.</dd>
  <dt><code>formatMatcher</code></dt>
  <dd>Используемый алгоритм сопоставления форматов. Возможными значениями являются <code>"basic"</code> и <code>"best fit"</code>; значением по умолчанию является <code>"best fit"</code>. Смотрите следующий абзац, объясняющий, как использовать это свойство.</dd>
 </dl>

 <p>Следующие свойства описывают компоненты даты/времени, используемые в форматированном выводе, и их желаемые представления. Реализации должны поддерживать, как минимум, следующие подмножества:</p>

 <ul>
  <li><code>weekday</code>, <code>year</code>, <code>month</code>, <code>day</code>, <code>hour</code>, <code>minute</code>, <code>second</code></li>
  <li><code>weekday</code>, <code>year</code>, <code>month</code>, <code>day</code></li>
  <li><code>year</code>, <code>month</code>, <code>day</code></li>
  <li><code>year</code>, <code>month</code></li>
  <li><code>month</code>, <code>day</code></li>
  <li><code>hour</code>, <code>minute</code>, <code>second</code></li>
  <li><code>hour</code>, <code>minute</code></li>
 </ul>

 <p>Также реализации могут поддерживать другие подмножества и запросы будут сравниваться со всеми доступными подмножествами представлений для поиска наилучшего соответствия. Для такого сравнения доступно два алгоритма, нужный из которых выбирается свойством <code>formatMatcher</code>: <a href="http://www.ecma-international.org/ecma-402/1.0/#BasicFormatMatcher">чётко определённый алгоритм <code>"basic"</code></a> и зависящий от реализации алгоритм <code>"best fit"</code>.</p>

 <dl>
  <dt><code>weekday</code></dt>
  <dd>Представление дней недели. Возможными значениями являются <code>"narrow"</code>, <code>"short"</code> и <code>"long"</code>.</dd>
  <dt><code>era</code></dt>
  <dd>Представление эр. Возможными значениями являются <code>"narrow"</code>, <code>"short"</code> и <code>"long"</code>.</dd>
  <dt><code>year</code></dt>
  <dd>Представление лет. Возможными значениями являются <code>"numeric"</code> и <code>"2-digit"</code>.</dd>
  <dt><code>month</code></dt>
  <dd>Представление месяцев. Возможными значениями являются <code>"numeric"</code>, <code>"2-digit"</code>, <code>"narrow"</code>, <code>"short"</code> и <code>"long"</code>.</dd>
  <dt><code>day</code></dt>
  <dd>Представление дней. Возможными значениями являются <code>"numeric"</code> и <code>"2-digit"</code>.</dd>
  <dt><code>hour</code></dt>
  <dd>Представление часов. Возможными значениями являются <code>"numeric"</code> и <code>"2-digit"</code>.</dd>
  <dt><code>minute</code></dt>
  <dd>Представление минут. Возможными значениями являются <code>"numeric"</code> и <code>"2-digit"</code>.</dd>
  <dt><code>second</code></dt>
  <dd>Представление секунд. Возможными значениями являются <code>"numeric"</code> и <code>"2-digit"</code>.</dd>
  <dt><code>timeZoneName</code></dt>
  <dd>Представление названий часовых поясов. Возможными значениями являются <code>"short"</code> и <code>"long"</code>.</dd>
 </dl>

 <p class="noinclude">Значение по умолчанию для всех свойств компонентов даты/времени является значение {{jsxref("Global_Objects/undefined", "undefined")}},но если все свойства компонентов будут равны {{jsxref("Global_Objects/undefined", "undefined")}}, то будет предполагаться, что значением свойств <code>year</code>, <code>month</code> и <code>day</code> является <code>"numeric"</code>.</p>
 </dd>
</dl>

<h2 id="Description">Описание</h2>

<h3 id="Properties">Свойства</h3>

<dl>
 <dt>{{jsxref("DateTimeFormat.prototype", "Intl.DateTimeFormat.prototype")}}</dt>
 <dd>Позволяет добавлять свойства ко всем объектам.</dd>
</dl>

<h2 id="Methods">Методы</h2>

<dl>
 <dt>{{jsxref("DateTimeFormat.supportedLocalesOf", "Intl.DateTimeFormat.supportedLocalesOf()")}}</dt>
 <dd>Возвращает массив, содержащий те из предоставленных локалей, которые поддерживаются без отката к локали по умолчанию среды выполнения.</dd>
</dl>

<h2 id="DateTimeFormat_instances">Экземпляры объекта <code>DateTimeFormat</code></h2>

<h3 id="Properties_of_DateTimeFormat_instance">Свойства</h3>

<p>Экземпляры <code>DateTimeFormat</code> наследуют следующие свойства из своего прототипа:</p>

<div>{{page('/ru/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/prototype', 'Properties')}}</div>

<h3 id="Methods_of_DateTimeFormat_instance">Методы</h3>

<p>Экземпляры <code>DateTimeFormat</code> наследуют следующие методы из своего прототипа:</p>

<div>{{page('/ru/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/prototype', 'Methods')}}</div>

<h2 id="Examples">Примеры</h2>

<h3 id="Example_Using_DateTimeFormat">Пример: использование <code>DateTimeFormat</code></h3>

<p>При базовом использовании без определения локали <code>DateTimeFormat</code> использует локаль и опции по умолчанию.</p>

<pre class="brush: js">var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// Вывод format без аргументов зависит от реализации,
// локали по умолчанию и часового пояса по умолчанию
console.log(new Intl.DateTimeFormat().format(date));
// → "12/19/2012", если код запущен с локалью en-US и часовым поясом America/Los_Angeles
</pre>

<h3 id="Example_Using_locales">Пример: использование аргумента <code>locales</code></h3>

<p>Этот пример показывает некоторые локализованные форматы даты и времени. Для получения формата языка, используемого в пользовательском интерфейсе вашего приложения, убедитесь, что вы указали этот язык (и, возможно, несколько запасных языков) через аргумент <code>locales</code>:</p>

<pre class="brush: js">var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// Форматирование ниже предполагает, что местный часовой пояс равен
// America/Los_Angeles для локали США

// В американском английском используется порядок месяц-день-год
console.log(new Intl.DateTimeFormat('en-US').format(date));
// → "12/19/2012"

// В британском английском используется порядок день-месяц-год
console.log(new Intl.DateTimeFormat('en-GB').format(date));
// → "20/12/2012"

// В корейском используется порядок год-месяц-день
console.log(new Intl.DateTimeFormat('ko-KR').format(date));
// → "2012. 12. 20."

// В большинстве арабоговорящих стран используют настоящие арабские цифры
console.log(new Intl.DateTimeFormat('ar-EG').format(date));
// → "<span dir="rtl">٢٠‏/١٢‏/٢٠١٢</span>"

// В Японии приложения могут захотеть использовать японский календарь,
// в котором 2012 год является 24-м годом эры Хейсей
console.log(new Intl.DateTimeFormat('ja-JP-u-ca-japanese').format(date));
// → "24/12/20"

// Если запрашиваемый язык может не поддерживаться, например
// балийский, откатываемся на запасной язык, в данном случае индонезийский
console.log(new Intl.DateTimeFormat(['ban', 'id']).format(date));
// → "20/12/2012"
</pre>

<h3 id="Example_Using_options">Пример: использование аргумента <code>options</code></h3>

<p>Формат даты и времени может быть настроен с помощью аргумента <code>options</code>:</p>

<pre class="brush: js">var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// Запрашиваем день недели вместе с длинным форматом даты
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
console.log(new Intl.DateTimeFormat('de-DE', options).format(date));
// → "Donnerstag, 20. Dezember 2012"

// Приложение может захотеть использовать UTC и показать это
options.timeZone = 'UTC';
options.timeZoneName = 'short';
console.log(new Intl.DateTimeFormat('en-US', options).format(date));
// → "Thursday, December 20, 2012, GMT"

// Иногда нам нужна большая точность
options = {
  hour: 'numeric', minute: 'numeric', second: 'numeric',
  timeZoneName: 'short'
};
console.log(new Intl.DateTimeFormat('en-AU', options).format(date));
// → "2:00:00 pm AEDT"

// Иногда даже в США нужен 24-часовой формат времени
options = {
  year: 'numeric', month: 'numeric', day: 'numeric',
  hour: 'numeric', minute: 'numeric', second: 'numeric',
  hour12: false
};
console.log(date.toLocaleString('en-US', options));
// → "12/19/2012, 19:00:00"
</pre>

<h2 id="Specifications">Спецификации</h2>

{{Specifications}}

<h2 id="Browser_compatibility">Совместимость с браузерами</h2>

<p>{{Compat}}</p>

<h2 id="See_also">Смотрите также</h2>

<div>{{page('/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl', 'See_also')}}</div>