Temporal.Instant

描述

Temporal.Instant 在语义上与 Date 相同。它们都封装了一个时间点，但 Temporal.Instant 更精确，因为它存储纳秒而不是毫秒。Temporal.Instant 还避免了 Date 的陷阱，因为它不假设任何日历或时区信息——如果你想读取任何日期或时间信息（例如年份或月份），你需要首先使用 toZonedDateTimeISO() 将其转换为 Temporal.ZonedDateTime。

你可以使用 Date.prototype.toTemporalInstant() 方法从 Date 转换为 Temporal.Instant，该方法应优先于其他方法（例如 Temporal.Instant.fromEpochMilliseconds()），因为前者涉及的用户代码更少，并且可能更优化。你也可以使用 Temporal.Instant 的纪元毫秒将其转换为 Date，例如 new Date(instant.epochMilliseconds)。

RFC 9557 格式

Instant 对象可以使用 RFC 9557 格式进行序列化和解析，这是 ISO 8601 / RFC 3339 格式的扩展。该字符串具有以下形式（空格仅为可读性，实际字符串中不应包含）：

YYYY-MM-DD T HH:mm:ss.sssssssss Z/±HH:mm

YYYY

一个四位数，或者一个带 + 或 - 号的六位数。

MM

一个从 01 到 12 的两位数。

DD

一个从 01 到 31 的两位数。YYYY、MM 和 DD 部分可以用 - 分隔或不用。

T

日期-时间分隔符，可以是 T、t 或空格。

HH

一个两位数字，从 00 到 23。

mm 可选

一个从 00 到 59 的两位数。默认为 00。

ss.sssssssss 可选

一个从 00 到 59 的两位数。可以选择后跟 . 或 , 和一到九位数字。默认为 00。HH、mm 和 ss 部分可以用 : 分隔或不用。你可以只省略 ss 或同时省略 ss 和 mm，因此时间可以有三种形式：HH、HH:mm 或 HH:mm:ss.sssssssss。

Z/±HH:mm

UTC 指示符 Z 或 z，或以 + 或 - 形式表示的 UTC 偏移量，后跟与时间分量相同的格式。请注意，其他系统可能不支持分钟以下的精度（:ss.sssssssss），该精度被接受但从不输出。如果提供了偏移量，则时间将按指定的偏移量进行解释。

作为输入，你可以选择性地包含时区标识符和日历，格式与 ZonedDateTime 相同，但它们将被忽略。其他 [key=value] 格式的注解也会被忽略，并且它们不能具有关键标志。

序列化时，你可以配置小数秒位数和偏移量。

构造函数

Temporal.Instant() 实验性

通过直接提供底层数据来创建一个新的 Temporal.Instant 对象。

静态方法

Temporal.Instant.compare() 实验性

返回一个数字（-1、0 或 1），表示第一个瞬间是在第二个瞬间之前、相同还是之后。等同于比较两个瞬间的 epochNanoseconds。

Temporal.Instant.from() 实验性

从另一个 Temporal.Instant 对象或 RFC 9557 字符串创建一个新的 Temporal.Instant 对象。

Temporal.Instant.fromEpochMilliseconds() 实验性

从自 Unix 纪元（1970 年 1 月 1 日午夜，UTC）以来的毫秒数创建一个新的 Temporal.Instant 对象。

Temporal.Instant.fromEpochNanoseconds() 实验性

从自 Unix 纪元（1970 年 1 月 1 日午夜，UTC）以来的纳秒数创建一个新的 Temporal.Instant 对象。

实例属性

这些属性在 Temporal.Instant.prototype 上定义，并由所有 Temporal.Instant 实例共享。

Temporal.Instant.prototype.constructor

创建实例对象的构造函数。对于 Temporal.Instant 实例，初始值为 Temporal.Instant() 构造函数。

Temporal.Instant.prototype.epochMilliseconds 实验性

返回一个整数，表示自 Unix 纪元（1970 年 1 月 1 日午夜，UTC）到此瞬间经过的毫秒数。相当于将 epochNanoseconds 除以 1e6 并向下取整。

Temporal.Instant.prototype.epochNanoseconds 实验性

返回一个 BigInt，表示自 Unix 纪元（1970 年 1 月 1 日午夜，UTC）到此瞬间经过的纳秒数。

Temporal.Instant.prototype[Symbol.toStringTag]

[Symbol.toStringTag] 属性的初始值为字符串 "Temporal.Instant"。此属性在 Object.prototype.toString() 中使用。

实例方法

Temporal.Instant.prototype.add() 实验性

返回一个新的 Temporal.Instant 对象，表示此瞬间按给定持续时间（可以由 Temporal.Duration.from() 转换的形式）向前移动后的时间。

Temporal.Instant.prototype.equals() 实验性

如果此瞬间的值与另一个瞬间（可以由 Temporal.Instant.from() 转换的形式）等效，则返回 true，否则返回 false。它们通过其纪元纳秒进行比较。等同于 Temporal.Instant.compare(this, other) === 0。

Temporal.Instant.prototype.round() 实验性

返回一个新的 Temporal.Instant 对象，表示此瞬间四舍五入到给定单位后的时间。

Temporal.Instant.prototype.since() 实验性

返回一个新的 Temporal.Duration 对象，表示从另一个瞬间（可以由 Temporal.Instant.from() 转换的形式）到此瞬间的持续时间。如果另一个瞬间在此瞬间之前，则持续时间为正；如果在此瞬间之后，则为负。

Temporal.Instant.prototype.subtract() 实验性

返回一个新的 Temporal.Instant 对象，表示此瞬间按给定持续时间（可以由 Temporal.Duration.from() 转换的形式）向后移动后的时间。

Temporal.Instant.prototype.toJSON() 实验性

返回一个字符串，表示此瞬间的 RFC 9557 格式，与调用 toString() 相同。旨在由 JSON.stringify() 隐式调用。

Temporal.Instant.prototype.toLocaleString() 实验性

返回一个带有此瞬间的语言敏感表示的字符串。在支持 Intl.DateTimeFormat API 的实现中，此方法委托给 Intl.DateTimeFormat。

Temporal.Instant.prototype.toString() 实验性

返回一个字符串，表示此瞬间的 RFC 9557 格式，使用指定的时区。

Temporal.Instant.prototype.toZonedDateTimeISO() 实验性

返回一个新的 Temporal.ZonedDateTime 对象，表示此瞬间在指定时区中，使用 ISO 8601 日历系统。

Temporal.Instant.prototype.until() 实验性

返回一个新的 Temporal.Duration 对象，表示从此瞬间到另一个瞬间（可以由 Temporal.Instant.from() 转换的形式）的持续时间。如果另一个瞬间在此瞬间之后，则持续时间为正；如果在此瞬间之前，则为负。

Temporal.Instant.prototype.valueOf() 实验性

抛出 TypeError，这可以防止 Temporal.Instant 实例在算术或比较操作中被 隐式转换为原始值。

规范

浏览器兼容性

另见

• Temporal
• Temporal.Duration
• Temporal.ZonedDateTime