Temporal.PlainDate

描述

PlainDate 本质上是 Temporal.PlainDateTime 对象中的日期部分，去除了时间信息。由于日期和时间信息之间没有太多交互，因此所有有关日期属性的通用信息都在这里记录。

RFC 9557 格式

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

YYYY-MM-DD [u-ca=calendar_id]

YYYY

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

MM

一个从 01 到 12 的两位数。

DD

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

[u-ca=calendar_id] 可选

将 calendar_id 替换为要使用的日历。有关常用支持的日历类型列表，请参阅 Intl.supportedValuesOf()。默认为 [u-ca=iso8601]。可以通过在键前加 ! 来添加关键标志：例如 [!u-ca=iso8601]。这个标志通常告诉其他系统，如果它们不支持它，就不能忽略它。如果注解包含两个或多个日历注解且其中一个是关键的，Temporal 解析器将抛出错误。请注意，YYYY-MM-DD 始终被解释为 ISO 8601 日历日期，然后转换为指定的日历。

作为输入，你可以选择性地包含时间、偏移量和时区标识符，格式与 PlainDateTime 相同，但它们将被忽略。[key=value] 格式的其他注解也将被忽略，且它们不得带有关键标志。

序列化时，你可以配置是否显示日历 ID，以及是否为其添加关键标志。

无效日期校正

Temporal.PlainDate.from()、Temporal.PlainDate.prototype.with()、Temporal.PlainDate.prototype.add()、Temporal.PlainDate.prototype.subtract() 方法，以及其他 Temporal 对象中的对应方法，允许使用日历特定属性构造日期。日期组件可能超出范围。在 ISO 日历中，这总是溢出，例如月份大于 12 或日期大于天数，并且修复它只会涉及将值钳制到允许的最大值。在其他日历中，无效情况可能更复杂。使用 overflow: "constrain" 选项时，无效日期将按以下方式校正为有效日期

• 如果日期不存在但月份存在：选择同一月份中最接近的日期。如果该月份中有两个同样接近的日期，则选择较晚的日期。
• 如果月份是闰月，但在该年份不存在：根据该日历用户的文化习俗选择另一个日期。通常，这会导致该闰月通常所属的闰年中的前一个月或后一个月的相同日期。
• 如果月份因其他原因在该年份不存在：选择在该年份内最接近的日期。如果该年份中有两个同样接近的日期，则选择较晚的日期。
• 如果整个年份不存在：选择在不同年份中最接近的日期。如果存在两个同样接近的日期，则选择较晚的日期。

构造函数

Temporal.PlainDate() 实验性

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

静态方法

Temporal.PlainDate.compare() 实验性

返回一个数字（-1、0 或 1），指示第一个日期是早于、等于还是晚于第二个日期。等同于比较底层 ISO 8601 日期的年、月、日字段。

Temporal.PlainDate.from() 实验性

从另一个 Temporal.PlainDate 对象、具有日期属性的对象或 RFC 9557 字符串创建新的 Temporal.PlainDate 对象。

实例属性

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

Temporal.PlainDate.prototype.calendarId 实验性

返回一个字符串，表示用于解释内部 ISO 8601 日期的日历。

Temporal.PlainDate.prototype.constructor

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

Temporal.PlainDate.prototype.day 实验性

返回一个正整数，表示此日期在本月中的基于 1 的日期索引，这与你在日历上看到的日期数字相同。依赖于日历。通常从 1 开始并且是连续的，但并非总是如此。

Temporal.PlainDate.prototype.dayOfWeek 实验性

返回一个正整数，表示该日期在星期中的基于 1 的日期索引。一周中的日期从 1 到 daysInWeek 依次编号，每个数字映射到其名称。取决于日历。通常，1 在日历中表示星期一，即使使用该日历的区域可能将不同的日期视为一周的第一天（请参阅 Intl.Locale.prototype.getWeekInfo()）。

Temporal.PlainDate.prototype.dayOfYear 实验性

返回一个正整数，表示该日期在一年中的基于 1 的日期索引。该年份的第一天是 1，最后一天是 daysInYear。取决于日历。

Temporal.PlainDate.prototype.daysInMonth 实验性

返回一个正整数，表示此日期所在月份的天数。依赖于日历。

Temporal.PlainDate.prototype.daysInWeek 实验性

返回一个正整数，表示此日期所在星期中的天数。依赖于日历。对于 ISO 8601 日历，这总是 7，但在其他日历系统中，每周可能不同。

Temporal.PlainDate.prototype.daysInYear 实验性

返回一个正整数，表示此日期所在年份的天数。依赖于日历。对于 ISO 8601 日历，这是 365，闰年是 366。

Temporal.PlainDate.prototype.era 实验性

返回一个日历特定的小写字符串，表示此日期的纪元，如果日历不使用纪元（例如 ISO 8601），则返回 undefined。era 和 eraYear 一起唯一地标识日历中的一年，就像 year 一样。依赖于日历。对于格里高利历，它是 "gregory" 或 "gregory-inverse"。

Temporal.PlainDate.prototype.eraYear 实验性

返回一个非负整数，表示此日期在纪元内的年份，如果日历不使用纪元（例如 ISO 8601），则返回 undefined。年份索引通常从 1（更常见）或 0 开始，一个纪元内的年份可以随时间减少（例如格里高利历的公元前）。era 和 eraYear 一起唯一地标识日历中的一年，就像 year 一样。依赖于日历。

Temporal.PlainDate.prototype.inLeapYear 实验性

返回一个布尔值，指示此日期是否在闰年。闰年是指比平年有更多天数（由于闰日或闰月）的年份。依赖于日历。

Temporal.PlainDate.prototype.month 实验性

返回一个正整数，表示该日期在年份中的基于 1 的月份索引。该年份的第一个月是 1，最后一个月是 monthsInYear。取决于日历。请注意，与 Date.prototype.getMonth() 不同，索引是基于 1 的。如果日历有闰月，则具有相同 monthCode 的月份在不同年份中可能具有不同的 month 索引。

Temporal.PlainDate.prototype.monthCode 实验性

返回一个日历特定的字符串，表示此日期的月份。依赖于日历。通常是 M 加上一个两位数的月份编号。对于闰月，它是上一个月的代码后跟 L。如果闰月是一年中的第一个月，代码是 M00L。

Temporal.PlainDate.prototype.monthsInYear 实验性

返回一个正整数，表示此日期所在年份的月份数。依赖于日历。对于 ISO 8601 日历，这总是 12，但在其他日历系统中可能会有所不同。

Temporal.PlainDate.prototype.weekOfYear 实验性

返回一个正整数，表示该日期在 yearOfWeek 中的基于 1 的周索引，如果日历没有明确定义的周系统，则返回 undefined。年份的第一周是 1。取决于日历。请注意，对于 ISO 8601，年份的头几天和最后几天可能被归入上一年或下一年的第一周。

Temporal.PlainDate.prototype.year 实验性

返回一个整数，表示此日期的年份，相对于日历特定的纪元开始年份。依赖于日历。通常，第 1 年是最新纪元的第一年或 ISO 8601 的 0001 年。如果纪元在年中开始，该年在纪元开始日期前后将具有相同的值。

Temporal.PlainDate.prototype.yearOfWeek 实验性

返回一个整数，表示与该日期的 weekOfYear 配对的年份，如果日历没有明确定义的周系统，则返回 undefined。取决于日历。通常这是日期的年份，但对于 ISO 8601，年份的头几天和最后几天可能归属于上一年或下一年的第一周，导致 yearOfWeek 相差 1。

Temporal.PlainDate.prototype[Symbol.toStringTag]

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

实例方法

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

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

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

如果该日期在值上与另一个日期（以可由 Temporal.PlainDate.from() 转换的形式）等效，则返回 true，否则返回 false。它们根据日期值和日历进行比较。

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

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

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

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

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

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

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

返回此日期的语言敏感表示字符串。

Temporal.PlainDate.prototype.toPlainDateTime() 实验性

返回一个新的 Temporal.PlainDateTime 对象，表示此日期和在同一日历系统中提供的某个时间。

Temporal.PlainDate.prototype.toPlainMonthDay() 实验性

返回一个新的 Temporal.PlainMonthDay 对象，表示此日期在同一日历系统中的 monthCode 和 day。

Temporal.PlainDate.prototype.toPlainYearMonth() 实验性

返回一个新的 Temporal.PlainYearMonth 对象，表示此日期在同一日历系统中的 year 和 month。

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

返回一个字符串，表示此日期的 RFC 9557 格式。

Temporal.PlainDate.prototype.toZonedDateTime() 实验性

返回一个新的 Temporal.ZonedDateTime 对象，表示此日期、提供的某个时间和提供的某个时区，在同一日历系统中。

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

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

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

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

Temporal.PlainDate.prototype.with() 实验性

返回一个新的 Temporal.PlainDate 对象，表示此日期，其中某些字段已被新值替换。

Temporal.PlainDate.prototype.withCalendar() 实验性

返回一个新的 Temporal.PlainDate 对象，表示此日期在新日历系统中的解释。

规范

浏览器兼容性

另见

• Temporal
• Temporal.Duration
• Temporal.PlainDateTime
• Temporal.PlainMonthDay
• Temporal.PlainYearMonth
• Temporal.ZonedDateTime