`stampToDate`过滤器：如何在AnQiCMS模板中格式化Unix时间戳？

在AnQiCMS的模板设计中，数据的展示方式对用户体验至关重要。尤其是日期和时间这类信息，如果以原始的Unix时间戳形式呈现，对普通访客来说是难以理解的。幸运的是，AnQiCMS提供了一个非常实用的过滤器——stampToDate，它能帮助我们轻松地将这些机器可读的数字序列转化为清晰、友好的日期时间格式。

认识Unix时间戳与stampToDate过滤器

首先，简单了解一下什么是Unix时间戳。它本质上是一个从1970年1月1日00:00:00 UTC（协调世界时）起经过的秒数。在数据库中，为了存储和计算效率，常常以这种格式保存日期时间。例如，文档的发布时间（CreatedTime）或更新时间（UpdatedTime）通常就是以Unix时间戳的形式存在。

在AnQiCMS的模板里，如果直接输出这些时间戳，您会看到一长串数字，比如1609470335。而stampToDate过滤器就像一个翻译官，它的任务就是将这串数字“翻译”成我们习惯阅读的日期和时间格式。

使用stampToDate过滤器的基本语法非常直观： {{stampToDate(时间戳, "格式")}}

这里有两个关键部分：

1. 时间戳: 这是您想要格式化的Unix时间戳，通常是模板中某个变量（如item.CreatedTime）。请注意，它需要是一个10位的数字，代表秒。
2. 格式: 这是一个字符串，用来告诉过滤器您希望日期时间以何种具体形式呈现。

掌握Go语言的日期格式化魔法

stampToDate过滤器采用的是Go语言特有的日期格式化规则，这与PHP的Y-m-d或Python的%Y-%m-%d有所不同。Go语言的格式化不是通过字母代号来表示年、月、日，而是通过一个固定的参考时间——2006年01月02日15时04分05秒，外加时区和毫秒。您只需要记住这个“魔法数字”对应的各个部分，然后用您想要的格式来替换它们即可。

让我们通过一些常见示例来理解这个格式：

• 只显示年份：将参考时间中的年份2006替换为2006。 例如：{{stampToDate(publishStamp, "2006")}} -> 2021
• 显示年-月-日：将参考时间中的2006-01-02替换为2006-01-02。 例如：{{stampToDate(publishStamp, "2006-01-02")}} -> 2021-06-30
• 显示年/月/日：将参考时间中的2006-01-02替换为2006/01/02。 例如：{{stampToDate(publishStamp, "2006/01/02")}} -> 2021/06/30
• 显示带有中文的日期：将参考时间中的2006-01-02替换为2006年01月02日。 例如：{{stampToDate(publishStamp, "2006年01月02日")}} -> 2021年06月30日
• 显示时:分:秒：将参考时间中的15:04:05替换为15:04:05。 例如：{{stampToDate(publishStamp, "15:04:05")}} -> 12:00:00
• 显示完整的日期时间：将参考时间中的2006-01-02 15:04:05替换为2006-01-02 15:04:05。 例如：{{stampToDate(publishStamp, "2006-01-02 15:04:05")}} -> 2021-06-30 12:00:00

关键在于，您需要记住2006-01-02 15:04:05这个骨架，然后根据您需要的格式来“拼凑”出新的格式字符串。例如，如果想要月/日/年的格式，您就写01/02/2006。

stampToDate的实际应用

在AnQiCMS中，您会经常在文章列表、文章详情、评论列表等地方用到日期时间显示。比如，当您遍历一个文档列表（archiveList）时，每个文档项（item）通常都会包含CreatedTime（创建时间）和UpdatedTime（更新时间）字段。这些字段通常存储的就是Unix时间戳。

假设您正在设计一个文章列表页面，希望显示每篇文章的发布日期：

{# 假设 publishStamp 是一个Unix时间戳变量，例如 1609470335 #}
{% set publishStamp = 1609470335 %}

<p>格式化为 2021年06月30日: {{stampToDate(publishStamp, "2006年01月02日")}}</p>
<p>格式化为 2021-06-30: {{stampToDate(publishStamp, "2006-01-02")}}</p>
<p>格式化为 2021/06/30 12:00:00: {{stampToDate(publishStamp, "2006/01/02 15:04:05")}}</p>
<p>格式化为 30/06/2021: {{stampToDate(publishStamp, "02/01/2006")}}</p>
<p>格式化为 12:00:00: {{stampToDate(publishStamp, "15:04:05")}}</p>

在一个文章列表循环中，它会是这样的：

{% archiveList archives with type="page" limit="10" %}
    {% for item in archives %}
    <article>
        <h3><a href="{{item.Link}}">{{item.Title}}</a></h3>
        <p>
            发布时间：{{stampToDate(item.CreatedTime, "2006年01月02日 15:04")}}
            <span class="views">阅读量：{{item.Views}}</span>
        </p>
        <p>{{item.Description}}</p>
        <a href="{{item.Link}}" class="read-more">阅读更多</a>
    </article>
    {% empty %}
    <p>暂时没有文章。</p>
    {% endfor %}
{% endarchiveList %}

在这段代码中，item.CreatedTime是一个Unix时间戳，stampToDate过滤器将其转换成了年-月-日 时:分的格式，使得文章列表的日期显示更加友好和易读。

注意事项

• Go语言的参考时间是关键：始终以2006-01-02 15:04:05作为基准来构建您的格式字符串。记住这不是自定义占位符，而是Go语言的特定日期值。
• Unix时间戳的位数：stampToDate过滤器期望接收10位的Unix时间戳（秒级）。如果您的时间戳是13位（毫秒级），您需要先将其除以1000，例如{{stampToDate(item.CreatedTime / 1000, "格式")}}。
• 避免与date过滤器混淆：AnQiCMS模板中可能还存在一个名为date的过滤器。date过滤器通常用于格式化Go语言原生的time.Time类型对象，而不是原始的Unix时间戳。如果将Unix时间戳传递