Org 具备强大的映射遍历能力,可查找满足指定条件的所有条目。该功能内部用于生成日程视图,同时也提供 API,可对每个或筛选后的条目执行任意函数。该 API 的主入口为:
在 SCOPE 范围内,对 MATCH 选中的每个标题调用 FUNC。
FUNC 为函数或 Lisp 表达式。光标会定位在标题开头,无参数调用该函数。Org 返回所有函数调用的返回值列表。
为不保留光标位置,Org 会在 save-excursion 中执行 FUNC。执行后光标移至刚处理行的行尾,检索从该位置继续。在部分场景下(如当前子树已被归档删除),该行为可能不符合预期,极少数情况下会错误跳过下一条目。如需避免此类问题,可让 FUNC 将变量 org-map-continue-from 设置为指定缓冲区位置。
MATCH 为标签/属性/TODO 匹配条件。Org 仅遍历匹配的标题;若为 nil 或 t ,则遍历所有标题。
SCOPE 决定命令作用范围,可选值:
nil当前缓冲区,遵循现有限制(如有)。
tree以光标处条目为起点的子树。
region活动区域内的条目(如有)。
file当前缓冲区,无任何限制。
file-with-archives当前缓冲区及其关联归档文件。
agenda所有日程文件。
agenda-with-archives所有日程文件及其关联归档文件。
若为文件名列表,则遍历列表中所有文件。
其余参数用作扫描器的跳过规则,有效参数:
archive跳过带有 ‘ARCHIVE’ 标签的子树。
comment跳过带有 COMMENT 关键字的子树。
作为 org-agenda-skip-function 的值,当函数返回 t 时,对该条目执行 FUNC,并从函数停留位置继续检索。
映射遍历可调用任意函数,包括修改元数据或调用属性 API 的函数(见 Using the Property API)。常用函数如下:
修改条目的 TODO 状态。参数 ARG 可用值较多,详见函数文档。
修改条目的优先级。ACTION 可用值详见函数文档。
切换当前条目的 TAG 标签。将 ONOFF 设为 on 或 off 不会切换,而是直接开启或关闭标签。
提升当前条目层级。
降低当前条目层级。
下面示例将所有带有 ‘TOMORROW’ 标签的条目设为 TODO 关键字 ‘UPCOMING’ ,并忽略注释子树和归档子树。
(org-map-entries '(org-todo "UPCOMING")
"+TOMORROW" 'file 'archive 'comment)
以下示例统计所有日程文件中 TODO 关键字为 ‘WAITING’ 的条目数量。
(length (org-map-entries t "/+WAITING" 'agenda))