A.8 Special Agenda Views

Org 提供专用钩子,用于进一步限制日程视图中的条目: agendaagenda*176todoalltodotagstags-todotags-tree 。 你可以指定一个自定义函数,对视图中每个匹配到的条目进行筛选判断。该函数也可以按需跳过任意数量的条目。

如需设置适用于所有日程视图的全局条件,可使用变量 org-agenda-skip-function-global 。Org 会将该全局条件与 org-agenda-skip-function 配合使用,实现自定义检索。

下面的示例定义了一个函数,用于创建只显示状态为 ‘waiting’ 的 TODO 条目的自定义视图。手动实现这一需求需要多步检索,而通过自定义视图可实现自动化:

该自定义函数会在子树中检索 ‘waiting’ 标签,匹配成功则返回 nil ;否则返回子树末尾位置,让检索从该处继续。

(defun my-skip-unless-waiting ()
  "Skip trees that are not waiting"
  (let ((subtree-end (save-excursion (org-end-of-subtree t))))
    (if (re-search-forward ":waiting:" subtree-end t)
        nil          ; 找到标签,不跳过
      subtree-end))) ; 未找到标签,从子树末尾继续检索

在自定义日程命令中使用该函数的方式如下:

(org-add-agenda-custom-command
 '("b" todo "PROJECT"
   ((org-agenda-skip-function 'my-skip-unless-waiting)
    (org-agenda-overriding-header "Projects waiting for something: "))))

注意,该配置同时将 org-agenda-overriding-header 绑定为更贴合该日程视图的描述性标题。

自定义检索时可对条目层级设置限制。这是 Org 中创建自定义检索的通用方式。若要包含所有层级,可使用 ‘LEVEL>0177。 随后可通过 org-agenda-skip-function 筛选匹配条目,该函数也支持直接使用 Lisp 表达式,例如 org-agenda-skip-entry-iforg-agenda-skip-subtree-if 。示例如下:

(org-agenda-skip-entry-if 'scheduled)

若当前条目已设置计划,则跳过。

(org-agenda-skip-entry-if 'notscheduled)

若当前条目未设置计划,则跳过。

(org-agenda-skip-entry-if 'deadline)

若当前条目设有截止日期,则跳过。

(org-agenda-skip-entry-if 'scheduled 'deadline)

若当前条目设有截止日期或已设置计划,则跳过。

(org-agenda-skip-entry-if 'todo '("TODO" "WAITING"))

若当前条目的 TODO 关键字为 TODO 或 WAITING,则跳过。

(org-agenda-skip-entry-if 'todo 'done)

若当前条目的 TODO 关键字为 DONE 状态,则跳过。

(org-agenda-skip-entry-if 'timestamp)

若当前条目包含任意时间戳(可能是截止日期或计划时间),则跳过。

(org-agenda-skip-entry-if 'regexp "regular expression")

若正则表达式在当前条目中匹配成功,则跳过。

(org-agenda-skip-entry-if 'notregexp "regular expression")

除非正则表达式在当前条目中匹配成功,否则跳过。

(org-agenda-skip-subtree-if 'regexp "regular expression")

功能同上,但会检查并跳过整个子树。

以下是不使用自定义函数、直接检索 ‘waiting’ 标签的示例:

(org-add-agenda-custom-command
 '("b" todo "PROJECT"
   ((org-agenda-skip-function '(org-agenda-skip-subtree-if
                                'regexp ":waiting:"))
    (org-agenda-overriding-header "Projects waiting for something: "))))

Footnotes

(176)

agenda* 视图与 agenda 基本相同,区别在于它只处理 /约会事项(appointments)/,即时间戳中包含 ‘[h]h:mm’ 格式时间的计划与截止日期条目。

(177)

注意,在 org-odd-levels-only 生效时,层级编号对应结构中的顺序,而非星号数量。