现在来看模板定义的各个元素。 org-capture-templates 中的每个条目都是包含以下项的列表:
用于选择模板的按键字符串,仅支持字符,例如 ‘"a"’ 表示单键选择模板, ‘"bt"’ 表示双键选择。使用多个按键时,相同前缀的按键在列表中必须连续排列,并在前面用一个双元素条目说明该前缀按键,例如:
("b" "Templates for marking stuff to buy")
若未为 C 键定义模板,该键会打开此复杂变量的自定义缓冲区。
简短的模板描述字符串,在选择时显示。
条目类型,为符号。有效值包括:
entry带有标题的 Org 模式节点。将作为目标条目的子节点或顶层节点保存。目标文件应为 Org 文件。
item普通列表项,放置在目标位置的第一个普通列表中。目标文件同样应为 Org 文件。
checkitem复选框项。与普通列表项的区别仅在于默认模板不同。
table-line在目标位置的第一个表格中新建一行。具体插入位置取决于 :prepend 和 :table-line-pos 属性(见下文)。
plain按原样插入的纯文本。
指定捕获内容的保存位置。在 Org 文件中,目标通常指定一个节点,条目会成为该节点的子节点。其他类型内容会添加到该节点正文中的表格或列表中。大多数目标说明包含 ‘<file-spec>’ 。若为空字符串,则默认使用 org-default-notes-file 。文件也可以用变量或无参调用函数指定。若目标未指定绝对路径,则视为相对于 org-directory 。
有效值包括:
文本将放在该文件的开头或结尾。
作为该条目的子节点或在该条目正文中保存。
若目标标题在文件中唯一,可使用此快速配置。
对于非唯一标题,使用完整路径更安全。
使用正则表达式定位光标位置。
该目标85会在日期树86中为今日日期创建标题。若指定可选大纲路径,日期树会建立在该节点之下,而非顶层。更多选项可查看下方的 :time-prompt 与 :tree-type 属性。
用于在文件中查找正确位置的函数。
保存到当前正在计时的条目。
光标 ‘point’ 所在位置。
最通用的方式:自行编写函数,既打开文件又将光标移到正确位置。
用于创建捕获条目的模板。若留空,会使用合适的默认模板。否则为包含转义码的字符串,转义码会根据捕获调用的时间与上下文替换。你也可以从文件87或通过函数动态获取该模板字符串,语法如下:
(file "/path/to/template-file") (function FUNCTION-RETURNING-THE-TEMPLATE)
条目的剩余部分为附加选项的属性列表。支持的属性包括:
:prepend通常新捕获的信息会追加到目标位置(最后一个子节点、最后一行表格、最后一个列表项等)。设置该属性可改变此行为。
:immediate-finish设置后不提供编辑机会,直接保存内容。适用于模板仅需自动添加信息的场景。
:jump-to-captured设置后完成捕获时跳转到刚捕获的条目。
:empty-lines设置在新条目前后插入的空行数。默认为 0,另一个常用值为 1。
:empty-lines-after设置在新条目后插入的空行数,会覆盖 :empty-lines 中后部空行的设置。
:empty-lines-before设置在新条目前插入的空行数,会覆盖 :empty-lines 中前部空行的设置。
:clock-in对该条目启动计时。
:clock-keep保存捕获条目后保持计时继续运行。
:clock-resume若捕获操作中断了某个计时,完成捕获后恢复该计时。注意 :clock-keep 优先级高于 :clock-resume 。若两者均设为非 nil ,当前计时会继续,之前的计时不会恢复。
:time-prompt在填充模板与生成日期/周树时提示选择日期/时间。未设置该属性时,捕获使用当前日期时间。即使未设置该属性,也可通过 C-1 前缀参数调用 org-capture 强制启用该行为。
:tree-type默认按天分组条目。使用 week 可创建周树而非月-日树,即将每日标题放在当前 ISO 周标题下。使用 month 可仅按月分组条目。也可使用 (year quarter month week day) 的任意子集按指定层级分组。若同时指定 month 与 week ,周会归属到包含周四的月份,以符合 ISO 年-周规则。若指定 quarter 与 week 但未指定 month ,季度为 13 周周期;否则为 3 个月周期。
:tree-type 也可以是函数,此时该函数应接收日期作为参数,并为 org-datetree-find-create-hierarchy 生成成对列表。
:unnarrowed不对目标缓冲区进行 narrowed,直接显示完整缓冲区。默认会 narrowed 只显示新内容。
:table-line-pos指定新行在表格中的插入位置。应为类似 ‘II-3’ 的字符串,表示新行成为第二条水平分隔线前的第三行。
:kill-buffer若调用捕获时目标文件尚未打开,完成捕获后关闭该缓冲区。
:no-save完成捕获后不保存目标文件。
:refile-targets临时将 org-refile-targets 设置为该属性的值。
:hook选择模板时,在 org-capture-mode-hook 之前运行的无参函数或无参函数列表。
:prepare-finalize选择模板时,在 org-capture-prepare-finalize-hook 之前运行的无参函数或无参函数列表。
:before-finalize选择模板时,在 org-capture-before-finalize-hook 之前运行的无参函数或无参函数列表。
:after-finalize选择模板时,在 org-capture-after-finalize-hook 之前运行的无参函数或无参函数列表。
Org 曾为日期/周树捕获提供四种不同目标,现已自动转换为 file+olp+datetree ,并应用 :time-prompt 与 :tree-type 属性。请使用 file+olp+datetree 重写原有日期/周树目标,旧目标已废弃。
日期树为一种大纲结构:顶层为年份,子层级为月份或 ISO 周,最底层为具体日期。
* 2022 ** 2022-10 October *** 2022-10-07 Friday *** 2022-10-08 Saturday
树结构中允许使用 TODO 状态、优先级(priority)、标签(tag)、统计标记(statistics cookies)与 COMMENT 关键字。
文件名非绝对路径时,Org 会视为相对于 org-directory 。