时间宏使用
适用场景
在一些场景中,我们需要显示当日或者昨日的具体日期,此时需设置动态时间宏。动态时间宏在卡片标题、筛选器默认值、订阅预警等多处被使用。详见产品文档《动态时间宏》。
Demo体验
详见案例Demo《动态时间宏介绍》。
案例下载
观远应用市场下载本案例到本地环境《动态时间宏》。
使用介绍
结构:外面为3层花括号{},中间为表征日期的英文关键词。例如 {{{today}}}。
动态时间宏类型主要分为2种:时间点类型和偏移类型,可组合使用。
时间点类型
关键词 | 用法(不区分大小写) |
today | 今天 |
yesterday | 昨天 |
tomorrow | 明天 |
first day of last month | 上个月第一天。 |
Monday last week | 上周的周一。 |
偏移类型
关键词 | 用法(不区分大小写) |
today - 1 days | 1天前。 |
返回日期格式
1. 动态时间宏表达式一般返回日期类型,如 “2021-12-31“,不能精确到时分秒。
2. 若有需要,也可以对动态时间宏进行格式设置,比如返回年、月,只需在动态时间宏后面加“%”、“y”、“M”、“d”等格式化参数。
日期格式化参数具体用法如下:
参数 | 含义 | 用法举例 | 返回值 | 返回值 |
%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-31}}} |
今年2月份 | {{{first day of this year +1 months}}} | {{{last day of last year +2 months}}} |
本季度 | {{{first day of this quarter}}} | {{{today}}} |
上季度 | {{{first day of last quarter}}} | {{{last day of last quarter}}} |
今年1季度 | {{{first day of this year}}} | {{{today %yyyy-03-31}}} |
今年2季度 | {{{first day of this year +3 months}}} | {{{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}}} | {{{yesterday}}} |
最近7天(包含当天) | {{{today -6 days}}} | {{{today}}} |
最近4周(非28天) | {{{Monday this week -3 weeks}}} | {{{today}}} |
2. 时间点
场景 | 时间宏 |
上上月的最后一天 | {{{first day of last month-1 days}}} |
固定某一天 | {{{%2023-02-20}}} |
昨天所在月份的1号 | {{{yesterday %yyyy-MM-01}}} |
上个月的8号 | {{{today - 1 months %yyyy-MM-08}}} |
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}}} |