时间宏使用
适用场景
在一些场景中，我们需要显示当日或者昨日的具体日期，此时需设置动态时间宏。动态时间宏在卡片标题、筛选器默认值、订阅预警等多处被使用。详见产品文档《动态时间宏》。
使用介绍
-
结构：外面为3层花括号{}，中间为表征日期的英文关键词。例如 {{{today}}}。
-
动态时间宏类型主要分为2种：时间点类型和偏移类型，可组合使用。
时间点类型
| 关键词 | 用法（不区分大小写） |
| today | 今天 |
| yesterday | 昨天 |
| tomorrow | 明天 |
| first day of last month | 上个月第一天。 first day 可替换为 last day，表示最后一天； last month 可替换为 this month、next month，表示本月、下月； month 可替换为 year、quarter。 |
| Monday last week | 上周的周一。 Monday 可替换为 Tuesday、Wednesday、Thursday、Friday、Saturday、Sunday，分别代表周二到周日； last week 可替换为 this week、next week，表示本周、下周。 |
偏移类型
| 关键词 | 用法（不区分大小写） |
| today - 1 days | 1天前。 Today 可替换为任意时间点类型关键词； days 可替换为 weeks、months、years，分别表示1周前、1月前、1年前； + 可替换为 -； 数字可以任意替换。 |
返回日期格式
1. 动态时间宏表达式一般返回日期类型，如 “2021-12-31“，不能精确到时分秒。
2. 若有需要，也可以对动态时间宏进行格式设置，比如返回年、月，只需在动态时间宏后面加“%”、“y”、“M”、“d”等格式化参数。
日期格式化参数具体用法如下：
| 参数 | 含义 | 用法举例 | 返回值 (以2021-12-31为例) | 返回值(以2022-01-01为例) |
| %y | 当前时间宏对应日期的年份（自然年） | today %y | 2021 | 2022 |
| %Y | 当前时间宏对应日期的年份（按年周算） | today %Y | 2022 | 2022 |
| %M | 当前时间宏对应日期的月份 | today %M | 12 | 1 |
| %d | 当前时间宏对应日期在当月的第几天 | today %d | 31 | 1 |
| %D | 当前时间宏对应日期在当年的第几天 | today %D | 365 | 1 |
| %e | 当前时间宏对应日期在当周的第几天（周日为第一天） | today %e | 6 | 7 |
| %E | 当前时间宏对应日期在当周的星期几 | today %E | 周五 | 周六 |
| %w | 当前时间宏对应日期在当年的第几周 | today %w | 1 | 1 |
| %W | 当前时间宏对应日期在当月的第几周 | today %W | 5 | 1 |
| %Q/q | 当前时间宏对应日期的季度 | today %q | 4 | 1 |
\
以上格式化参数也可组合使用，以2023年3月15日为例，如输入“{{{today %y年M月d日 E}}}”，可得到“2023年3月15日 周三”。重复的字母可以用来微调格式（例如在数字前面补零），以2023年3月15日为例，输入“{{{today %y-M}}}”，得到“2023-3”；输入“{{{today %yyyy-MM}}}”，得到“2023-03”。
注意事项
-
小写w: %w 得到的当年周数，是以周日为一周第一天来计数，和国际常用的ISO week 周数计算方法不同。如果想要周一为一周的第一天，可以尝试通过 -1 days 进行修正，比如：{{{yesterday -1 days %w}}}。
-
大写的Y：%Y代表的是Week year，当前日期所在周的年份，且只要本周跨年，那么这周就算入下一年，这个和国际常用的ISO week year也是不同的。如果需要的是自然年周，需要使用小写y。
-
基于以上两点，跨年周的展示和ISO week差距较大，请谨慎使用。例如，2021-12-31、2022-01-01这2天, {{{today %YYYY年第w周}}} 显示为“2022年第1周”，卡片里拖到维度栏的周（即ISO week）实际为“2021年第52周”；2022-12-31（周六） ，{{{today %YYYY年第w周}}} 显示为“2022年第53周”，卡片里实际为“2022年第52周”。类似这种情况通过 -1 days 无法进行修正。
-
以上格式化参数仅支持返回中文和数字格式的日期，不支持返回英文格式的日期（例如 April 1,2023）。
使用案例
1. 时间范围
| 场景 | 时间宏开始 | 时间宏结束 |
| 今年1月份 | {{{first day of this year}}} {{{today %yyyy-01-01}}} | {{{today %yyyy-01-31}}} |
| 今年2月份 | {{{first day of this year +1 months}}} {{{today %yyyy-02-01}}} | {{{last day of last year +2 months}}} {{{last day of this year -10 months}}} |
| 本季度 | {{{first day of this quarter}}} | {{{today}}} {{{yesterday}}} |
| 上季度 | {{{first day of last quarter}}} | {{{last day of last quarter}}} |
| 今年1季度 | {{{first day of this year}}} {{{today %yyyy-01-01}}} | {{{today %yyyy-03-31}}} |
| 今年2季度 | {{{first day of this year +3 months}}} {{{today %yyyy-04-01}}} | {{{today %yyyy-06-30}}} |
| 上上周日到上周周六 | {{{Sunday last week - 7 days}}} | {{{Saturday last week}}} |
| 前年 | {{{first day of last year - 1 years}}} | {{{first day of last year - 1 days}}} |
| 最近7天（不包含当天） | {{{yesterday -6 days}}} {{{today - 1 weeks}}} | {{{yesterday}}} |
| 最近7天（包含当天） | {{{today -6 days}}} | {{{today}}} |
| 最近4周（非28天） | {{{Monday this week -3 weeks}}} | {{{today}}} {{{yesterday}}} |
2. 时间点
| 场景 | 时间宏 |
| 上上月的最后一天 | {{{last day of last month-1 months}}} |
| 固定某一天 | {{{%2023-02-20}}} |
| 昨天所在月份的1号 | {{{yesterday %yyyy-MM-01}}} |
| 上个月的8号 | {{{today - 1 months %yyyy-MM-08}}} {{{first day of last month +7 days}}} |
3. 文本展示 （用于选择筛选器默认选项、卡片和订阅标题）
| 场景 | 时间宏 |
| 2023_Q01 | {{{today%yyyy_'Q'QQ}}} |
| 2023年第1季度 | {{{today%y年第Q季度}}} 、{{{today %y年第qqq}}} |
| 2023年3月15日 周三 | {{{today %y年M月d日 E}}} |
| 3月 | {{{today %MMM}}} |
| 三月 | {{{today %MMMM}}} |
| 第一季度 | {{{today %qqqq}}} |