-
Notifications
You must be signed in to change notification settings - Fork 102
/
format.xml
493 lines (479 loc) · 17.7 KB
/
format.xml
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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: ac397fd0da4d814b5a2f4ba49254f9b6093315e1 Maintainer: mowangjuanzi Status: ready -->
<!-- CREDITS: Luffy -->
<refentry xml:id="datetime.format" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>DateTimeInterface::format</refname>
<refname>DateTimeImmutable::format</refname>
<refname>DateTime::format</refname>
<refname>date_format</refname>
<refpurpose>按照指定格式返回格式化后的日期</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<para>&style.oop;</para>
<methodsynopsis role="DateTimeInterface">
<modifier>public</modifier> <type>string</type><methodname>DateTimeInterface::format</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
</methodsynopsis>
<methodsynopsis role="DateTimeImmutable">
<modifier>public</modifier> <type>string</type><methodname>DateTimeImmutable::format</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
</methodsynopsis>
<methodsynopsis role="DateTime">
<modifier>public</modifier> <type>string</type><methodname>DateTime::format</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
</methodsynopsis>
<para>&style.procedural;</para>
<methodsynopsis>
<type>string</type><methodname>date_format</methodname>
<methodparam><type>DateTimeInterface</type><parameter>object</parameter></methodparam>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
</methodsynopsis>
<para>
按照指定格式返回格式化后的日期。
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
&date.datetime.description;
<varlistentry>
<term><parameter>format</parameter></term>
<listitem>
<para>
输出的日期 <type>string</type>
的格式。参见下面的格式化选项。也有几个<link linkend="datetimeinterface.constants.types">预定义日期常量</link>可以代替。例如
<constant>DATE_RSS</constant> 包含格式化字符串 <literal>'D, d M Y H:i:s'</literal>。
</para>
<para>
<table>
<title><parameter>format</parameter> 参数字符串可以识别以下字符</title>
<tgroup cols="3">
<thead>
<row>
<entry><parameter>format</parameter> 字符</entry>
<entry>说明</entry>
<entry>返回值示例</entry>
</row>
</thead>
<tbody>
<row>
<entry align="center"><emphasis>日</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>d</literal></entry>
<entry>月份中的第几天,有补零的两位数字</entry>
<entry><literal>01</literal> 到 <literal>31</literal></entry>
</row>
<row>
<entry><literal>D</literal></entry>
<entry>文字表示星期几,三个字母</entry>
<entry><literal>Mon</literal> 到 <literal>Sun</literal></entry>
</row>
<row>
<entry><literal>j</literal></entry>
<entry>月份中的第几天,没有补零</entry>
<entry><literal>1</literal> 到 <literal>31</literal></entry>
</row>
<row>
<entry><literal>l</literal>(小写 'L')</entry>
<entry>完整文本表示星期几</entry>
<entry><literal>Sunday</literal> 到 <literal>Saturday</literal></entry>
</row>
<row>
<entry><literal>N</literal></entry>
<entry>ISO 8601 数字表示星期几</entry>
<entry><literal>1</literal>(星期一)到 <literal>7</literal>(星期天)</entry>
</row>
<row>
<entry><literal>S</literal></entry>
<entry>月份中的第几天英文后缀,两个字符</entry>
<entry>
<literal>st</literal>、<literal>nd</literal>、<literal>rd</literal> 或
<literal>th</literal>。可以和 <literal>j</literal> 一起使用
</entry>
</row>
<row>
<entry><literal>w</literal></entry>
<entry>数字表示星期几</entry>
<entry><literal>0</literal>(星期天)到 <literal>6</literal>(星期六)</entry>
</row>
<row>
<entry><literal>z</literal></entry>
<entry>一年中的第几天(从 0 开始)</entry>
<entry><literal>0</literal> 到 <literal>365</literal></entry>
</row>
<row>
<entry align="center"><emphasis>周</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>W</literal></entry>
<entry>ISO 8601 格式当年中的第几周,每周从周一开始</entry>
<entry>示例:<literal>42</literal>(当年的第 42 周)</entry>
</row>
<row>
<entry align="center"><emphasis>月</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>F</literal></entry>
<entry>月份的完整文本表示,比如 January 或者 March</entry>
<entry><literal>January</literal> 到 <literal>December</literal></entry>
</row>
<row>
<entry><literal>m</literal></entry>
<entry>月份的数字表示,补零</entry>
<entry><literal>01</literal> 到 <literal>12</literal></entry>
</row>
<row>
<entry><literal>M</literal></entry>
<entry>简短文本表示月份,三个字母</entry>
<entry><literal>Jan</literal> 到 <literal>Dec</literal></entry>
</row>
<row>
<entry><literal>n</literal></entry>
<entry>数字表示几月份,不补零</entry>
<entry><literal>1</literal> 到 <literal>12</literal></entry>
</row>
<row>
<entry><literal>t</literal></entry>
<entry>指定月份的天数</entry>
<entry><literal>28</literal> 到 <literal>31</literal></entry>
</row>
<row>
<entry align="center"><emphasis>年</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>L</literal></entry>
<entry>是否是闰年</entry>
<entry>如果是闰年为 <literal>1</literal>,否则为 <literal>0</literal>。</entry>
</row>
<row>
<entry><literal>o</literal></entry>
<entry>ISO 8601 数字年份表示。这和 <literal>Y</literal> 值相同,但如果 ISO
周数(<literal>W</literal>)属于上一年或者下一年,则用那一年。</entry>
<entry>示例:<literal>1999</literal> 或 <literal>2003</literal></entry>
</row>
<row>
<entry><literal>X</literal></entry>
<entry>年份的展开全数字表示,至少四位,<literal>-</literal>
表示公元前,<literal>+</literal> 表示公元。</entry>
<entry>示例:<literal>-0055</literal>、<literal>+0787</literal>、
<literal>+1999</literal>、<literal>+10191</literal></entry>
</row>
<row>
<entry><literal>x</literal></entry>
<entry>如果需要,年份可以展开全数字表示,如果可能的话,也可以用标准的全数字(<literal>Y</literal>)表示。至少有四位数字。公元前以
<literal>-</literal> 为前缀,年份不小于 <literal>10000</literal>
时以 <literal>+</literal> 为前缀。</entry>
<entry>示例:<literal>-0055</literal>, <literal>0787</literal>,
<literal>1999</literal>, <literal>+10191</literal></entry>
</row>
<row>
<entry><literal>Y</literal></entry>
<entry>年份完整数字表示,至少四位,使用 <literal>-</literal> 表示公元前。</entry>
<entry>示例:<literal>-0055</literal>、<literal>0787</literal>、
<literal>1999</literal>、<literal>2003</literal>、<literal>10191</literal>
</entry>
</row>
<row>
<entry><literal>y</literal></entry>
<entry>两位数的年份表示</entry>
<entry>示例:<literal>99</literal> 或 <literal>03</literal></entry>
</row>
<row>
<entry align="center"><emphasis>时间</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>a</literal></entry>
<entry>小写的上午和下午</entry>
<entry><literal>am</literal> 或 <literal>pm</literal></entry>
</row>
<row>
<entry><literal>A</literal></entry>
<entry>大写的上午和下午</entry>
<entry><literal>AM</literal> 或 <literal>PM</literal></entry>
</row>
<row>
<entry><literal>B</literal></entry>
<entry>Swatch 互联网时间</entry>
<entry><literal>000</literal> 到 <literal>999</literal></entry>
</row>
<row>
<entry><literal>g</literal></entry>
<entry>不补零的小时(12 小时制)</entry>
<entry><literal>1</literal> 到 <literal>12</literal></entry>
</row>
<row>
<entry><literal>G</literal></entry>
<entry>不补零的小时(24 小时制)</entry>
<entry><literal>0</literal> 到 <literal>23</literal></entry>
</row>
<row>
<entry><literal>h</literal></entry>
<entry>补零的小时(12 小时制)</entry>
<entry><literal>01</literal> 到 <literal>12</literal></entry>
</row>
<row>
<entry><literal>H</literal></entry>
<entry>补零的小时(24 小时制)</entry>
<entry><literal>00</literal> 到 <literal>23</literal></entry>
</row>
<row>
<entry><literal>i</literal></entry>
<entry>补零的分钟</entry>
<entry><literal>00</literal> 到 <literal>59</literal></entry>
</row>
<row>
<entry><literal>s</literal></entry>
<entry>补零的秒</entry>
<entry><literal>00</literal> 到 <literal>59</literal></entry>
</row>
<row>
<entry><literal>u</literal></entry>
<entry>
微秒。注意 <function>date</function> 总是生成 <literal>000000</literal>,因为它需要一个
<type>int</type> 参数,而如果 <classname>DateTime</classname> 是使用微秒创建的,则
<methodname>DateTime::format</methodname> 支持微秒。
</entry>
<entry>示例:<literal>654321</literal></entry>
</row>
<row>
<entry><literal>v</literal></entry>
<entry>
毫秒。与 <literal>u</literal> 的说明相同。
</entry>
<entry>示例:<literal>654</literal></entry>
</row>
<row>
<entry align="center"><emphasis>时区</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>e</literal></entry>
<entry>时区标识符</entry>
<entry>示例:<literal>UTC</literal>、<literal>GMT</literal>、<literal>Atlantic/Azores</literal></entry>
</row>
<row>
<entry><literal>I</literal>(大写 i)</entry>
<entry>是否为夏令时</entry>
<entry>如果是夏令时为 <literal>1</literal>,否则为 <literal>0</literal>。</entry>
</row>
<row>
<entry><literal>O</literal></entry>
<entry>跟格林尼治时间(GMT)的差异,小时和分钟时间没有冒号</entry>
<entry>示例:<literal>+0200</literal></entry>
</row>
<row>
<entry><literal>P</literal></entry>
<entry>跟格林尼治时间(GMT)的差异,小时和分钟时间有冒号</entry>
<entry>示例:<literal>+02:00</literal></entry>
</row>
<row>
<entry><literal>p</literal></entry>
<entry>
跟 <literal>P</literal> 相同,区别是使用 <literal>Z</literal>
替换 <literal>+00:00</literal> 返回(PHP 8.0.0 起可用)
</entry>
<entry>示例:<literal>Z</literal> 或 <literal>+02:00</literal></entry>
</row>
<row>
<entry><literal>T</literal></entry>
<entry>如果知道会返回时区缩写,否则返回 GMT 时差。</entry>
<entry>示例:<literal>EST</literal>、<literal>MDT</literal>、<literal>+05</literal></entry>
</row>
<row>
<entry><literal>Z</literal></entry>
<entry>以秒为单位的时差。UTC 以西的时区为负的时差,以东为正的时差。</entry>
<entry><literal>-43200</literal> 到 <literal>50400</literal></entry>
</row>
<row>
<entry align="center"><emphasis>完整日期/时间</emphasis></entry>
<entry>---</entry>
<entry>---</entry>
</row>
<row>
<entry><literal>c</literal></entry>
<entry>ISO 8601 日期</entry>
<entry>2004-02-12T15:19:21+00:00</entry>
</row>
<row>
<entry><literal>r</literal></entry>
<entry><link xlink:href="&url.rfc;2822">RFC 2822</link>/<link
xlink:href="&url.rfc;5322">RFC 5322</link> 格式化时间</entry>
<entry>示例:<literal>Thu, 21 Dec 2000 16:01:07 +0200</literal></entry>
</row>
<row>
<entry><literal>U</literal></entry>
<entry>从 Unix 纪元(January 1 1970 00:00:00 GMT)到至今的秒数</entry>
<entry>参见 <function>time</function></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
格式字符串中无法识别的字符将会原样打印。当使用 <function>gmdate</function>
时,<literal>Z</literal> 格式将始终返回 <literal>0</literal>。
</para>
<note>
<para>
由于本函数仅接受 <type>int</type> 类型时间戳,所以 <literal>u</literal> 格式化标识符仅在用户使用
<function>date_create</function> 且使用 <function>date_format</function> 创建时间戳时才有用。
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
成功时返回格式化后的日期字符串。
</para>
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.2.0</entry>
<entry>
新增 <literal>X</literal> 和 <literal>x</literal> 格式化字符。
</entry>
</row>
<row>
<entry>8.0.0</entry>
<entry>
新增 <literal>p</literal> 格式化字符。
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>DateTimeInterface::format</function> 示例</title>
<para>&style.oop;</para>
<programlisting role="php">
<![CDATA[
<?php
$date = new DateTimeImmutable('2000-01-01');
echo $date->format('Y-m-d H:i:s');
?>
]]>
</programlisting>
<para>&style.procedural;</para>
<programlisting role="php">
<![CDATA[
<?php
$date = date_create('2000-01-01');
echo date_format($date, 'Y-m-d H:i:s');
?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
2000-01-01 00:00:00
]]>
</screen>
</example>
</para>
<para>
<example>
<title>更多示例</title>
<programlisting role="php">
<![CDATA[
<?php
// 设置使用的默认时区。
date_default_timezone_set('UTC');
// 现在
$date = new DateTimeImmutable();
// 打印类似:Wednesday
echo $date->format('l'), "\n";
// 打印类似:Wednesday 19th of October 2022 08:40:48 AM
echo $date->format('l jS \o\f F Y h:i:s A'), "\n";
/* 在 format 参数中使用常量 */
// 打印类似:Wed, 19 Oct 2022 08:40:48 +0000
echo $date->format(DateTimeInterface::RFC2822), "\n";
?>
]]>
</programlisting>
</example>
</para>
<para>
通过对格式化字符串中的识别字符添加反斜线,对其转义来防止被解析。如果带有反斜线的字符已经是特殊序列,那么还要对反斜线进行转义。
<example>
<title>格式化时转义字符</title>
<programlisting role="php">
<![CDATA[
<?php
$date = new DateTimeImmutable();
// 打印类似:Wednesday the 19th
echo $date->format('l \t\h\e jS');
?>
]]>
</programlisting>
</example>
</para>
<para>
要格式化其它语言的日期,可以使用 <methodname>IntlDateFormatter::format</methodname>
代替 <methodname>DateTimeInterface::format</methodname>。
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
<para>
此方法不使用区域设置,所有的输出都是英文。
</para>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<simplelist>
<member><methodname>IntlDateFormatter::format</methodname></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->