# 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](/docs/date/format) | 按格式字符串输出日期时间。 |
| [Date.from_string](/docs/date/from_string) | 解析日期字符串并创建新的 Date 对象。 |
| [Date.from_timestamp](/docs/date/from_timestamp) | 通过秒级 Unix 时间戳创建新的 Date 对象。 |
| [Date.from_millis](/docs/date/from_millis) | 通过毫秒级 Unix 时间戳创建新的 Date 对象。 |
| [Date.from_micros](/docs/date/from_micros) | 通过微秒级 Unix 时间戳创建新的 Date 对象。 |
| [Date.from_nanos](/docs/date/from_nanos) | 通过纳秒级 Unix 时间戳创建新的 Date 对象。 |
| [Date.timestamp](/docs/date/timestamp) | 读取秒级 Unix 时间戳。 |
| [Date.timestamp_millis](/docs/date/timestamp_millis) | 读取毫秒级 Unix 时间戳。 |
| [Date.timestamp_micros](/docs/date/timestamp_micros) | 读取微秒级 Unix 时间戳。 |
| [Date.timestamp_nanos](/docs/date/timestamp_nanos) | 读取纳秒级 Unix 时间戳。 |
| [Date.year](/docs/date/year) | 读取年份。 |
| [Date.month](/docs/date/month) | 读取月份。 |
| [Date.day](/docs/date/day) | 读取月份中的日期。 |
| [Date.hour](/docs/date/hour) | 读取小时。 |
| [Date.minute](/docs/date/minute) | 读取分钟。 |
| [Date.second](/docs/date/second) | 读取秒。 |
| [Date.millis](/docs/date/millis) | 读取当前秒内的毫秒部分。 |
| [Date.micros](/docs/date/micros) | 读取当前秒内的微秒部分。 |
| [Date.nanos](/docs/date/nanos) | 读取当前秒内的纳秒部分。 |
| [Date.weekday](/docs/date/weekday) | 读取星期序号。 |
| [Date.week](/docs/date/week) | 读取 ISO 周序号。 |
| [Date.yearday](/docs/date/yearday) | 读取一年中的日期序号。 |
| [Date.quarter](/docs/date/quarter) | 读取季度。 |
| [Date.to_string](/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 内部使用本地时区，遇到夏令时歧义时间时使用第一个本地时间结果。