The clock table (翻译: Org 手册)

Next: Resolving idle time and continuous clocking, Previous: Clocking commands, Up: Clocking Work Time [Contents][Index]

8.4.2 The clock table ¶

Org mode 可基于计时信息生成相当复杂的报表，这类报表称为 计时表(clock table) ，会以一个或多个 Org 表格的形式呈现。

org-clock-report ¶

插入或更新计时表。携带前缀参数调用时，跳转到当前文档第一个计时表并更新。计时表包含已归档的子树。

该命令可通过调用 org-dynamic-block-insert-dblock （C-c C-x x）并选择 “clocktable” 触发（参见 Dynamic Blocks）。

C-c C-c or C-c C-x C-u (org-dblock-update) ¶

更新光标处的动态块。光标需位于动态块的 ‘BEGIN’ 行。

C-u C-c C-x C-u ¶

更新所有动态块（参见 Dynamic Blocks）。适用于缓冲区中包含多个计时表块的场景。

S-LEFT, S-RIGHT (org-clocktable-try-shift) ¶

偏移当前 ‘:block’ 时间区间并更新表格。光标需位于 ‘#+BEGIN: clocktable’ 行。若 ‘:block’ 为 ‘today’ ，会偏移为 ‘today-1’ ，依此类推。

以下是 org-clock-report 插入到缓冲区时，计时表框架的示例：

#+BEGIN: clocktable :maxlevel 2 :emphasize nil :scope file
#+END:

‘#+BEGIN’ 行包含用于定义报表范围、结构与格式的选项，所有选项的默认值可在变量 org-clocktable-defaults 中配置。

首先是用于筛选计时条目的选项：

‘:maxlevel’

表格中时间明细展示的最大层级深度，更深层级的计时会汇总到上层。

‘:scope’

统计范围，可设置为以下任意值：

‘`nil`’	当前缓冲区或缩小后的区域
‘`file`’	整个当前缓冲区
‘`subtree`’	计时表所在的子树
‘`treeN`’	所在的 N 级树，例如 ‘`tree3`’
‘`tree`’	所在的 1 级树
‘`agenda`’	所有日程文件
‘`("file" ...)`’	扫描指定文件
‘`FUNCTION`’	调用无参函数 `FUNCTION` 返回的文件
‘`file-with-archives`’	当前文件及其归档文件
‘`agenda-with-archives`’	所有日程文件（包含归档文件）

‘:block’

要统计的时间块，可使用绝对时间或相对当前时间，支持格式：

‘`2007-12-31`’	2007 年除夕夜
‘`2007-12`’	2007 年 12 月
‘`2007-W50`’	2007 年第 50 周
‘`2007-Q2`’	2007 年第二季度
‘`2007`’	2007 全年
‘`today`’, ‘`yesterday`’, ‘`today-N`’	相对日期
‘`thisweek`’, ‘`lastweek`’, ‘`thisweek-N`’	相对周
‘`thismonth`’, ‘`lastmonth`’, ‘`thismonth-N`’	相对月
‘`thisyear`’, ‘`lastyear`’, ‘`thisyear-N`’	相对年
‘`untilnow`’⁷⁹	所有历史计时时间

未设置该选项时，Org 会使用 org-clock-display-default-range 的值，默认为当前年份。

使用 S-LEFT 或 S-RIGHT 可偏移时间区间。

‘:tstart’

统计起始时间字符串，支持 ‘\"<-2w>\"’ 这类相对时间，相对时间语法参见 Matching tags and properties。

‘:tend’

统计结束时间字符串，支持 ‘\"<now>\"’ 这类相对时间，相对时间语法参见 Matching tags and properties。

‘:wstart’

一周起始日期，默认 1 为周一。

‘:mstart’

一月起始日期，默认 1 为 1 号。

‘:step’

设置为 ‘day’ 、 ‘week’ 、 ‘semimonth’ 、 ‘month’ 、 ‘quarter’ 或 ‘year’ ，将表格按时间段拆分。使用该选项时，必须指定 ‘:block=，或同时指定 =:tstart’ 与 ‘:tend’ 。

‘:stepskip0’

非 nil 时，不显示耗时为零的时间段。

‘:fileskip0’

非 nil 时，不显示无有效数据的文件对应的表格区段。

‘:match’

用于筛选条目标签匹配表达式，匹配语法参见 Matching tags and properties。

接下来是控制表格格式的选项，这些选项由函数 org-clocktable-write-default 解析，你也可以通过 ‘:formatter’ 参数指定自定义函数。

‘:emphasize’: 非 nil 时，突出显示一级和二级条目。
‘:lang’: 用于“任务”等描述单元格的语言⁸⁰。
‘:link’: 将表格中的条目标题链接到原文位置。
‘:narrow’: 限制 Org 表格中标题列宽度的整数。若写作 ‘50!’ ，导出时标题也会被缩短。
‘:indent’: 根据层级缩进标题字段。
‘:filetitle’: 若文件设有 ‘#+title’ ，在文件列显示标题。
‘:hidefiles’: 由多个文件生成表格时，隐藏文件列。
‘:tcolumns’: 时间数据所用列数。若小于 ‘:maxlevel’ ，更低层级会合并为一列。
‘:level’: 是否包含层级号列。
‘:sort’: 包含排序列与排序类型的序对。例如 ‘:sort (1 . ?a)’ 表示对第一列按字母序排序。
‘:compact’: 等价于 ‘:level nil :indent t :narrow 40! :tcolumns 1’ ，除非显式指定 ‘:narrow’ ，否则相关设置均会被覆盖。
‘:timestamp’: 条目的时间戳（若有），按顺序查找 ‘SCHEDULED’ 、 ‘DEADLINE’ 、 ‘TIMESTAMP’ 和 ‘TIMESTAMP_IA’ 特殊属性（参见 Special Properties）。
‘:tags’: 该标记非 nil 时，显示标题的标签。
‘:properties’: 要在表格中显示的属性列表，每个属性占用一列。
‘:inherit-props’: 该标记非 nil 时， ‘:properties’ 的值会沿层级继承。
‘:formula’: 要添加并计算的 ‘TBLFM’ 关键字内容。特殊用法 ‘:formula %’ 会添加一列百分比耗时。若此处未指定公式，计时表下方已有的公式会在更新时保留并计算。
‘:formatter’: 用于格式化计时数据并插入到缓冲区的函数。

如需获取当前一级树当日的计时汇总，可写作：

#+BEGIN: clocktable :maxlevel 2 :block today :scope tree1 :link t
#+END:

如需使用指定时间范围，可写作⁸¹

#+BEGIN: clocktable :tstart "<2006-08-10 Thu 10:00>"
                    :tend "<2006-08-10 Thu 12:00>"
#+END:

一周前到当前时刻的时间范围可写作：

#+BEGIN: clocktable :tstart "<-1w>" :tend "<now>"
#+END:

当前子树带百分比(%)耗时的汇总可写作：

#+BEGIN: clocktable :scope subtree :link t :formula %
#+END:

上周所有计时的紧凑横向展示可写作：

#+BEGIN: clocktable :scope agenda :block lastweek :compact t
#+END:

Footnotes

(79)

使用 :step 时， untilnow 从 2003 年初开始计算，而非从时间起点开始。

(80)

语言文本可通过变量 org-clock-clocktable-language-setup 设置。

(81)

注意所有参数必须写在同一行，此处换行仅为适配手册排版。