文档章节
时间函数
使用这些函数处理时间值。
这一页解决什么问题
模板里的日期/时间绕不开三个动作:解析(字符串 → time.Time)、换算(时区)、输出(固定格式或本地化),外加时长的构造与解析。本章覆盖的正是这几件事。
字符串日期 ──time.AsTime──▶ time.Time ──time.In──▶ 换时区的 time.Time ──time.Format──▶ 字符串
「数量+单位」──time.Duration──▶ time.Duration
时长字符串 ──time.ParseDuration──▶ time.Duration读完本章你应该能够
- 判断手上的值是字符串还是
time.Time,并知道前者必须先过time.AsTime; - 用
time.Format输出固定格式,并知道机器可读的写法是2006-01-02T15:04:05Z07:00; - 用
time.In把同一时刻换算到别的时区,并说清时区优先级的四级顺序; - 说明
time.Now是构建时间而不是访问时间; - 用
time.Duration或time.ParseDuration构造时长,并取到秒数/分钟数。
什么时候用本章的函数,什么时候别用
该用:
- 日期是字符串(YAML/JSON 日期、加引号的 TOML、数据文件里的日期)→ 先解析;
- 输出需要固定格式(RSS、
datetime属性、文件名)或需要本地化标记; - 需要跨时区展示,或需要时长计算。
别用:
- 页面日期(
.Date、.Lastmod、.PublishDate)本身已经是time.Time→ 直接配合time.Format输出,不必再解析; - 想通过本地化标记输出多语言日期 → 先读
time.Format的实测说明(本站改用固定布局,避免部分语言回退成英文); - 需要日历运算(加减月份、取某一天)→ 看 methods/time 下的时间方法;
- 需要「读者打开页面的当前时间」→ 静态站点做不到,那属于客户端脚本的职责。
阅读顺序
- 解析与输出:time.AsTime → time.Format → time.In
- 时长:time.Duration → time.ParseDuration
- 当前时间:time.Now(配合 methods/time 的方法链)
完整示例:从字符串日期到上海时间
layouts/_partials/date-line.htmlgo-html-template
{{ $t := time.AsTime "2023-10-15T13:18:50-07:00" }}
<p>原值:{{ $t }}</p>
<p>固定格式:{{ time.Format "2006-01-02" $t }}</p>
<p>换到上海时间:{{ $t | time.In "Asia/Shanghai" | time.Format "2006-01-02 15:04" }}</p>
<p>24 小时的秒数:{{ (time.Duration "hour" 24).Seconds }}</p>Hugo 渲染为(站点配置 timeZone = "Asia/Shanghai"):
html
<p>原值:2023-10-15 13:18:50 -0700 -0700</p>
<p>固定格式:2023-10-15</p>
<p>换到上海时间:2023-10-16 04:18</p>
<p>24 小时的秒数:86400</p>你应当看到什么:原值保留输入字符串里的偏移(-0700);time.Format 用固定布局取日期;换算到 Asia/Shanghai 后跨到了次日 04:18;秒数由 time.Duration 返回值的 .Seconds 方法算出。
本章内容
- time.AsTime 把日期/时间值的给定字符串表示返回为 time.Time 值。 (今天)
- time.Duration 使用给定的时间单位与数值返回 time.Duration 值。 (今天)
- time.Format 把给定日期/时间返回为格式化并本地化后的字符串。 (今天)
- time.In 返回给定日期/时间在指定 IANA 时区中的表示。 (今天)
- time.Now 返回当前本地时间。 (今天)
- time.ParseDuration 解析给定的时长字符串,返回 time.Duration 值。 (今天)