编辑“︁Java Period”︁

{{DISPLAYTITLE:Java Period}}

'''Java Period''' 是 Java 日期时间 API（`java.time` 包）中的一个类，用于表示基于日期的时段，例如“3 年、2 个月和 5 天”。它主要用于计算两个日期之间的差值，或者对日期进行增减操作。与 `Duration` 不同，`Period` 处理的是年、月、日等日历单位，而不是精确的时间单位（如小时、分钟、秒）。

== 基本介绍 ==
`Period` 类是不可变的（immutable）且线程安全，适用于计算两个 `LocalDate` 之间的差异或调整日期。它的主要特点包括：
* 以年、月、日为单位存储时段。
* 支持解析标准 ISO-8601 格式的时段字符串（如 `P1Y2M3D`）。
* 提供多种静态工厂方法创建实例。

== 创建 Period 对象 ==
=== 使用静态工厂方法 ===
`Period` 提供了几种静态方法来创建实例：

<syntaxhighlight lang="java">
// 创建表示 1 年 2 个月 3 天的 Period
Period period1 = Period.of(1, 2, 3);

// 创建仅包含年份的 Period
Period period2 = Period.ofYears(1);

// 创建仅包含月份的 Period
Period period3 = Period.ofMonths(2);

// 创建仅包含天数的 Period
Period period4 = Period.ofDays(3);

// 解析 ISO-8601 格式字符串
Period period5 = Period.parse("P1Y2M3D"); // 1 年 2 个月 3 天
</syntaxhighlight>

=== 计算两个日期的差值 ===
可以通过 `Period.between()` 方法计算两个 `LocalDate` 之间的差值：

<syntaxhighlight lang="java">
LocalDate startDate = LocalDate.of(2020, 1, 1);
LocalDate endDate = LocalDate.of(2023, 3, 6);

Period period = Period.between(startDate, endDate);

System.out.println(period); // 输出: P3Y2M5D
System.out.println("Years: " + period.getYears());   // 输出: 3
System.out.println("Months: " + period.getMonths()); // 输出: 2
System.out.println("Days: " + period.getDays());    // 输出: 5
</syntaxhighlight>

== 操作 Period 对象 ==
`Period` 提供了一些方法来获取或修改其值：

<syntaxhighlight lang="java">
Period period = Period.of(1, 2, 3);

// 获取年、月、日
int years = period.getYears();   // 1
int months = period.getMonths(); // 2
int days = period.getDays();     // 3

// 修改值（返回新实例，因为 Period 是不可变的）
Period newPeriod = period.withYears(2).withMonths(4).withDays(10);
System.out.println(newPeriod); // 输出: P2Y4M10D

// 增加或减少时段
Period addedPeriod = period.plusYears(1).plusMonths(1);
System.out.println(addedPeriod); // 输出: P2Y3M3D
</syntaxhighlight>

== 实际应用案例 ==
=== 计算年龄 ===
`Period` 可用于计算一个人的年龄：

<syntaxhighlight lang="java">
LocalDate birthDate = LocalDate.of(1990, 5, 15);
LocalDate currentDate = LocalDate.now();

Period age = Period.between(birthDate, currentDate);

System.out.printf("年龄: %d 岁 %d 个月 %d 天%n",
    age.getYears(), age.getMonths(), age.getDays());
</syntaxhighlight>

=== 调整日期 ===
可以用 `Period` 对日期进行增减：

<syntaxhighlight lang="java">
LocalDate date = LocalDate.of(2023, 1, 1);
Period period = Period.ofMonths(3);

LocalDate newDate = date.plus(period);
System.out.println(newDate); // 输出: 2023-04-01
</syntaxhighlight>

== 注意事项 ==
* `Period` 不考虑夏令时或时区，因为它仅处理日历日期。
* 如果 `Period` 包含负值（如 `P-1Y2M3D`），表示时段是反向的。
* 与 `Duration` 不同，`Period` 不能用于 `LocalTime` 或 `Instant`。

== 总结 ==
`Period` 是处理基于日历的时段的强大工具，适用于计算日期差异或调整日期。它的不可变性和线程安全性使其成为 Java 日期时间 API 的重要组成部分。

<mermaid>
graph TD
    A[创建 Period] --> B[静态方法 of/parse]
    A --> C[Period.between]
    B --> D[操作 Period]
    C --> D
    D --> E[增减日期]
    D --> F[获取年/月/日]
</mermaid>

[[Category:编程语言]]
[[Category:Java]]
[[Category:Java日期时间api]]