# date 日期时间库

## 功能

date() 创建本地时区 Date 对象；支持日期字符串解析、chrono/strftime 风格格式化、Unix 时间戳转换、日期运算，以及年月日时分秒等字段读取。

## 语法

```bt
date()
date(timestamp)
date(text)
```

## 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------ | ------ | ------ | ------ | ------ |
| timestamp | Int/Float | 否 | 无 | 秒级 Unix 时间戳；不传任何参数时返回当前本地时间。 |
| text | String | 否 | 无 | 日期字符串或秒级 Unix 时间戳字符串。 |

## 返回值

| 类型 | 说明 |
| ------ | ------ |
| Date | 返回本地时区 Date 对象。 |

## API 列表

| API | 说明 |
| ------ | ------ |
| [Date.format](/zh-hans/docs/date/format) | 按格式字符串输出日期时间。 |
| [Date.from_string](/zh-hans/docs/date/from_string) | 解析日期字符串并创建新的 Date 对象。 |
| [Date.from_timestamp](/zh-hans/docs/date/from_timestamp) | 通过秒级 Unix 时间戳创建新的 Date 对象。 |
| [Date.from_millis](/zh-hans/docs/date/from_millis) | 通过毫秒级 Unix 时间戳创建新的 Date 对象。 |
| [Date.from_micros](/zh-hans/docs/date/from_micros) | 通过微秒级 Unix 时间戳创建新的 Date 对象。 |
| [Date.from_nanos](/zh-hans/docs/date/from_nanos) | 通过纳秒级 Unix 时间戳创建新的 Date 对象。 |
| [Date.add](/zh-hans/docs/date/add) | 返回加减指定时间后的新 Date 对象。 |
| [Date.diff](/zh-hans/docs/date/diff) | 返回两个日期之间按指定单位换算后的差值。 |
| [Date.start_of_day](/zh-hans/docs/date/start_of_day) | 返回当天零点的新 Date 对象。 |
| [Date.timestamp](/zh-hans/docs/date/timestamp) | 读取秒级 Unix 时间戳。 |
| [Date.timestamp_millis](/zh-hans/docs/date/timestamp_millis) | 读取毫秒级 Unix 时间戳。 |
| [Date.timestamp_micros](/zh-hans/docs/date/timestamp_micros) | 读取微秒级 Unix 时间戳。 |
| [Date.timestamp_nanos](/zh-hans/docs/date/timestamp_nanos) | 读取纳秒级 Unix 时间戳。 |
| [Date.year](/zh-hans/docs/date/year) | 读取年份。 |
| [Date.month](/zh-hans/docs/date/month) | 读取月份。 |
| [Date.day](/zh-hans/docs/date/day) | 读取月份中的日期。 |
| [Date.hour](/zh-hans/docs/date/hour) | 读取小时。 |
| [Date.minute](/zh-hans/docs/date/minute) | 读取分钟。 |
| [Date.second](/zh-hans/docs/date/second) | 读取秒。 |
| [Date.millis](/zh-hans/docs/date/millis) | 读取当前秒内的毫秒部分。 |
| [Date.micros](/zh-hans/docs/date/micros) | 读取当前秒内的微秒部分。 |
| [Date.nanos](/zh-hans/docs/date/nanos) | 读取当前秒内的纳秒部分。 |
| [Date.weekday](/zh-hans/docs/date/weekday) | 读取星期序号。 |
| [Date.week](/zh-hans/docs/date/week) | 读取 ISO 周序号。 |
| [Date.yearday](/zh-hans/docs/date/yearday) | 读取一年中的日期序号。 |
| [Date.quarter](/zh-hans/docs/date/quarter) | 读取季度。 |
| [Date.to_string](/zh-hans/docs/date/to_string) | 按默认格式输出日期时间。 |

## 代码示例

```bt

// 输出： 2026-06-09 10:11
print date().format('%Y-%m-%d %H:%M')

d = date('2026-06-09 10:11:12')

result = {
    text: d.format('%Y-%m-%d'),
    timestamp: d.timestamp(),
    quarter: d.quarter()
}
```

## 注意事项

- 无参数 date() 返回当前本地时间。
- 整数和浮点参数按秒级 Unix 时间戳创建 Date。
- 字符串参数会按常见日期格式解析为 Date，不再支持 date('%Y-%m-%d') 直接格式化当前时间。
- 格式化当前时间请使用 date().format('%Y-%m-%d')。
- Date 内部使用本地时区，遇到夏令时歧义时间时使用第一个本地时间结果。