From 3b89ca42e86442c412d2c95bbcce490717eacd2c Mon Sep 17 00:00:00 2001
From: ruanyf <yifeng.ruan@gmail.com>
Date: Thu, 25 Jul 2024 16:51:38 +0800
Subject: [PATCH] docs(temporal): add temporal API

---
 docs/temporal.md | 184 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 docs/temporal.md

diff --git a/docs/temporal.md b/docs/temporal.md
new file mode 100644
index 0000000..b0a4be4
--- /dev/null
+++ b/docs/temporal.md
@@ -0,0 +1,184 @@
+# Temporal API
+
+Temporal 是一个表示日期时间的全新 API，对目前的 Date API 的诸多问题进行修正。
+
+## Temporal.Now
+
+`Temporal.Now`表示当前系统的准确时间。
+
+- Temporal.Now.instant()- 获取当前系统准确时间
+- Temporal.Now.timeZoneId()- 获取当前系统时区
+- Temporal.Now.zonedDateTimeISO()- 获取系统时区和 ISO-8601 日历中的当前日期和挂钟时间
+- Temporal.Now.plainDateISO()- 获取系统时区和 ISO-8601 日历中的当前日期
+- Temporal.Now.plainTimeISO()- 获取系统时区和 ISO-8601 日历中的当前挂钟时间
+- Temporal.Now.plainDateTimeISO()- 与上面相同，但返回 ISO-8601 日历中的日期时间
+
+```javascript
+// 返回 UTC 的当前时间
+Temporal.Now.instant().toString()
+
+// 返回某个时区的当前日期时间
+Temporal.Now.zonedDateTimeISO('Asia/Shanghai').toString()
+
+// 返回 ISO 格式当前日期时间
+Temporal.Now.plainDateTimeISO().toString()
+
+// 返回 ISO 格式的当前时间，不含日期
+Temporal.Now.plainTimeISO().toString()
+```
+
+下面的例子是获取指定时区的当前时间。
+
+```javascript
+const now = Temporal.Now.zonedDateTimeISO('America/New_York');
+console.log(now.toString());
+```
+
+## Temporal.Instant
+
+`Temporal.Instant`表示某个固定的时间。
+
+```javascript
+const instant = Temporal.Instant.from('1969-07-20T20:17Z');
+instant.toString(); // => '1969-07-20T20:17:00Z'
+instant.epochMilliseconds; // => -14182980000
+```
+
+## Temporal.ZonedDateTime
+
+`Temporal.ZonedDateTime`表示某个时区的时间。
+
+```javascript
+const zonedDateTime = Temporal.ZonedDateTime.from({
+  timeZone: 'America/Los_Angeles',
+  year: 1995,
+  month: 12,
+  day: 7,
+  hour: 3,
+  minute: 24,
+  second: 30,
+  millisecond: 0,
+  microsecond: 3,
+  nanosecond: 500
+}); // => 1995-12-07T03:24:30.0000035-08:00[America/Los_Angeles]
+```
+
+## Temporal.PlainDate
+
+`Temporal.PlainDate`表示与时区无关的日期。
+
+```javascript
+const date = Temporal.PlainDate.from({ year: 2006, month: 8, day: 24 }); // => 2006-08-24
+date.year; // => 2006
+date.inLeapYear; // => false
+date.toString(); // => '2006-08-24'
+```
+
+下面的例子是计算某个日期以后的时间。
+
+```javascript
+const date = Temporal.PlainDate.from('2024-01-01');
+const newDate = date.add({ days: 10 });
+console.log(newDate.toString()); // Outputs '2024-01-11'
+```
+
+## Temporal.PlainTime
+
+`Temporal.PlainTime`表示与时区无关的某个时点。
+
+```javascript
+const time = Temporal.PlainTime.from({
+  hour: 19,
+  minute: 39,
+  second: 9,
+  millisecond: 68,
+  microsecond: 346,
+  nanosecond: 205
+}); // => 19:39:09.068346205time.second; // => 9
+time.toString(); // => '19:39:09.068346205'
+```
+
+## Temporal.PlainDateTime
+
+`Temporal.PlainDateTime`表示时区无关的日期时间。
+
+```javascript
+const dateTime = Temporal.PlainDateTime.from({
+  year: 1995,
+  month: 12,
+  day: 7,
+  hour: 15
+}); // => 1995-12-07T15:00:00
+const dateTime1 = dateTime.with({
+  minute: 17,
+  second: 19
+}); // => 1995-12-07T15:17:19
+```
+
+## Temporal.PlainYearMonth
+
+`Temporal.PlainYearMonth`表示不含日期的年月。
+
+```javascript
+const yearMonth = Temporal.PlainYearMonth.from({ year: 2020, month: 10 }); // => 2020-10
+yearMonth.daysInMonth; // => 31
+yearMonth.daysInYear; // => 366
+```
+
+## Temporal.PlainMonthDay
+
+`Temporal.PlainMonthDay`表示没有年份的月和日。
+
+下面是计算生日的例子。
+
+```javascript
+const birthday = Temporal.PlainMonthDay.from("12-15");
+// 或者写成
+// const birthday = Temporal.PlainMonthDay.from({ month: 12, day: 15 })
+
+const birthdayIn2030 = birthday.toPlainDate({ year: 2030 });
+
+birthdayIn2030.toString() // 2030-12-15
+birthdayIn2030.dayOfWeek // 7
+```
+
+## Temporal.Duration
+
+`Temporal.Duration`表示时长。
+
+```javascript
+const duration = Temporal.Duration.from({
+  hours: 130,
+  minutes: 20
+});
+
+duration.total({ unit: 'second' }); // => 469200
+```
+
+## Temporal.TimeZone
+
+`Temporal.TimeZone`表示某个时区。
+
+```javascript
+const timeZone = Temporal.TimeZone.from('Africa/Cairo');
+timeZone.getInstantFor('2000-01-01T00:00'); // => 1999-12-31T22:00:00Z
+timeZone.getPlainDateTimeFor('2000-01-01T00:00Z'); // => 2000-01-01T02:00:00
+timeZone.getPreviousTransition(Temporal.Now.instant()); // => 2014-09-25T21:00:00Z
+timeZone.getNextTransition(Temporal.Now.instant()); // => null
+```
+
+## Temporal.Calendar
+
+`Temporal.Calendar`表示某个日历系统。
+
+```javascript
+const cal = Temporal.Calendar.from('iso8601');
+const date = cal.dateFromFields({ year: 1999, month: 12, day: 31 }, {});
+date.monthsInYear; // => 12
+date.daysInYear; // => 365
+```
+
+## 参考链接
+
+- [Temporal documentation](https://tc39.es/proposal-temporal/docs/)
+