Task 查询语法手册

关于查询

可以通过使用 tasks 代码块查询来列出整个保管库中的 Task。您可以通过单击 Task 旁边的小铅笔图标来编辑查询结果中的 Task。默认情况下，Task 按状态、截止日期和路径排序。您可以更改排序（请参阅下面的查询选项）。

查询 Task 最简单的方法是这样的：

```tasks

```

在实时预览和阅读模式下，这将列出您保管库中的所有 Task，无论其状态等属性如何。

这可能不是您想要的。因此，Task 允许您设置查询选项来过滤要显示的 Task。例如，您可以仅显示今天到期的 Task（来自保管库中的任何位置）：

## Due today

```tasks
due today
not done
```

过滤器 (Filters)

• Custom Filters：自定义过滤器
• Searching for dates：搜索日期
• Text filters：文本过滤器
• Matching multiple filters：匹配多个过滤器
• Filters for Task Statuses：任务状态过滤器
• Filters for Task Dependencies：任务依赖性过滤器
• Filters for Dates in Tasks：过滤任务中的日期
• Filters for Other Task Properties：其他任务属性的过滤器
• Filters for File Properties：文件属性过滤器

自定义过滤器 Custom Filters

Task 提供了许多内置的过滤选项，但有时它们并不能完全满足所有用户的需求。

现在，Tasks 拥有强大的机制，让您创建自己的自定义过滤器，提供无与伦比的灵活性。

以下文档中提供了许多自定义过滤指令 filter by function 的示例，包括解释，用于当内置到 Task 中的指令不能满足您的偏好时。

您可以在自定义过滤器 ( Custom Filters) 中了解更多关于这个非常强大的功能的信息。

搜索日期

任务在查询块内的日期方面提供了很大的灵活性。

基本上有两种主要的日期搜索类型：

• 特定日期搜索
• 日期范围搜索

特定日期搜索

```tasks
starts before 2023-04-20
due on or before today
```

日期搜索选项

绝对日期

<date> 过滤器可以使用“绝对”日期，其首选格式为 YYYY-MM-DD 。绝对日期指定日历中的特定日期。它们代表同一天，无论今天的日期如何。

Examples: 示例：

• 2021-05-25

相对日期

<date> 过滤器可以与 relative 相对日期一起提供。相对日期是根据今天的日期计算的。

当天变化时，相对日期如 due today 将被重新评估，以确保列表保持最新。

基本示例：

• yesterday
• today
• tomorrow
• next monday
• last friday
• 14 days ago
• in two weeks
• 14 October （将使用当前年份）
• May （本年度 5 月 1 日将被使用）

请注意，如果是星期三并且你写 tuesday ，任务假定你指的是“昨天”，因为那是最近的星期二。如果你想指“下个星期二”，请使用 next tuesday 。

日期范围搜索

Task 允许指定一对日期进行日期搜索， <date range> 。

本节描述日期范围搜索，例如：

```tasks
due 2023-11-25 2023-11-30
happens this week
```

绝对日期范围

相对日期范围

Tasks 支持一组非常特定的相对 <date range> 值： last|this|next week|month|quarter|year 。管道（ | ）字符表示“或”。

任务将根据今天的日期处理这些范围，并将其内部转换为绝对日期范围（ YYYY-MM-DD YYYY-MM-DD ）。

示例相对日期范围：

• in this week 本周一至周日（含）
• after this month
• next quarter
• on or before next year

编号日期范围

也可以使用独立于当前日期的编号日期范围的能力。这些编号日期范围类型得到支持：

• Week 周
  • Format: YYYY-Www ( ww 为周数，总是两位数字）
  • Example: 2022-W14 示例： 2022-W14
• Month 月份
  • Format: YYYY-mm （ mm 为月份数字，总是两位数）
  • Example: 2023-10 示例： 2023-10
• Quarter 季度
  • Format: YYYY-Qq （ q 是季度编号，总是 1 位数）
  • Example: 2021-Q4
• Year 年份
  • Format: YYYY
  • Example: 2023 `

Text filters 文本过滤器

文本搜索过滤器有 2 种类型：

1. heading (includes|does not include) <search text>
2. heading (regex matches|regex does not match) /<JavaScript-style Regex>/

匹配多个过滤器

每行查询都必须匹配，任务才能列出。换句话说，行之间被视为存在一个 ‘AND’ 运算符。在每行中，您可以使用布尔运算符 NOT 、 AND 、 OR 、 AND NOT 、 OR NOT 和 XOR ，只要将单个过滤器用括号括起来即可：

```tasks
(no due date) OR (due after 2021-04-04)
path includes GitHub
```

```tasks
due after 2021-04-04
(path includes GitHub) AND NOT (tags include #todo)
```

任务状态过滤器

• Status 状态
• Status Name 状态名称
• Status Type 状态类型
• Status Symbol 状态符号
• Next Status Symbol 下一个状态符号

示例，查找具有尚未添加到任务设置中的状态符号的任何任务：

```tasks
status.name includes unknown
group by path
```

Status

• done - 匹配状态类型为 DONE 、 CANCELLED 和 NON_TASK 任务
• not done - 匹配状态类型为 TODO 和 IN_PROGRESS 任务

自 4.2.0 任务以来，现在可以使用 task.isDone 进行按状态的自定义过滤。

filter by function task.isDone

• 与 done 过滤器相同，但与其他行上的表达式结合使用可能很有用。

filter by function ! task.isDone

• 与 not done 过滤器相同，但与其他行上的表达式结合使用可能很有用。

Status Name

自定义的状态名称，例如，也许您将 [!] 命名为 Important ，因此该字段将搜索具有该状态符号的所有任务的文本 Important 。

• status.name (includes|does not include) <string>
  • 不区分大小写（忽略大小写）。
• 正则表达式匹配（默认区分大小写）。
  • 必备阅读: 正则表达式搜索。

从 Tasks 4.2.0 开始，现在可以使用 task.status.name按状态名称进行 自定义过滤。

filter by function task.status.name === 'Unknown'

• 查找尚未添加到任务设置中的具有自定义状态的所有任务。

Status Type

• status.type (is|is not) (TODO|DONE|IN_PROGRESS|CANCELLED|NON_TASK)
  • TODO 等值不区分大小写：例如，您可以使用 in_progress
• 这将搜索您为自定义状态指定的类型。
• 如果您希望找到所有处于 IN_PROGRESS 的任务，并且您已将状态设置为 [/] 、 [d] 以及可能还有其他几个 IN_PROGRESS ，则此搜索非常有效。
• 要搜索多种可能的状态类型：
  • 要排除多个值，可以使用多个 status.type is not 行。
  • 要允许多个值，请使用布尔组合，例如： ( status.type is TODO ) OR ( status.type is IN_PROGRESS ) 。
  • 或者参见下面的“自定义过滤”示例。

从 Tasks 4.2.0 开始，现在可以使用 task.status.type按状态类型进行 自定义过滤。

filter by function task.status.type === 'NON_TASK'

• 查找 NON_TASK 类型的任务。

filter by function 'TODO,IN_PROGRESS'.includes(task.status.type)

• 查找类型为 TODO 或类型 IN_PROGRESS 的任务。
• 这比执行布尔 OR 搜索更方便。

filter by function ! 'NON_TASK,CANCELLED'.includes(task.status.type)

• 查找类型不是 NON_TASK 且不是类型 CANCELLED 的任务。

Status Symbol

没有内置的指令来按状态符号进行过滤。

从 Tasks 4.2.0 开始，现在可以使用 task.status.symbol按状态符号进行 自定义过滤。

filter by function task.status.symbol === '-'

• 查找带有复选框 [-] 的任务，该复选框通常用于表示“已取消”。

filter by function task.status.symbol !== ' '

• 查找除空格字符以外的任何内容作为状态符号的任务，即不带复选框 [ ] 任务。

filter by function \
    const symbol = task.status.symbol; \
    return symbol === 'P' || symbol === 'C' || symbol === 'Q' || symbol === 'A';

• 注意，因为我们使用变量来避免重复，所以我们需要添加 return
• 查找带有状态符号 P 、 C 、 Q 或 A 的任务。
• 您想要搜索的符号越多，这可能会变得非常冗长。

filter by function 'PCQA'.includes(task.status.symbol)

• 查找带有状态符号 P 、 C 、 Q 或 A 的任务。
• 这是独立测试每个允许值的较长语句的便捷捷径。

filter by function !' -x/'.includes(task.status.symbol)

• 查找带有默认设置中的任务不支持的任何状态符号的任务。

Next Status Symbol

没有内置指令可以按下一个状态符号进行过滤。

从 Tasks 4.2.0 开始，现在可以使用 task.status.nextSymbol按下一个状态符号进行 自定义过滤。

filter by function task.status.symbol === task.status.nextSymbol

• 查找切换到自身的任务，因为下一个符号与当前符号相同。

其他任务属性的筛选器

• Description 描述
• Description without tags 没有标签的描述
• Priority 优先事项
• Urgency 紧迫性
• Recurrence 复发
• Sub-Items 子项目
• Tags 标签
• Markdown

Description

• description (includes|does not include) <string>
  • 匹配不区分大小写（忽略大小写）。
  • 匹配时忽略全局过滤器。
• description (regex matches|regex does not match) /<JavaScript-style Regex>/
  • 正则表达式是否匹配（默认区分大小写）。

对于精确搜索，了解该 description 可能会有所帮助：

• 首先删除每个任务的所有能指表情符号及其值，
• 然后删除所有全局过滤器，
• 然后删除尾随空格
• 然后搜索剩余的文本

例如：

从 Tasks 4.2.0 开始，现在可以使用 task.description按描述进行 自定义过滤。

filter by function task.description.length > 100

• 查找具有长描述的任务。

Description without tags

从 Tasks 4.2.0 开始，可以使用 task.descriptionWithoutTags 从自定义过滤器的描述中删除标签，以便在**自定义过滤**中使用。

Priority

• priority is (above|below|not)? (lowest|low|none|medium|high|highest)

可用的优先级为（从高到低）：

1. 🔺 最高优先级
2. ⏫ 高优先级
3. 🔼 中等优先级
4. 不使用指示符来表示没有优先级（使用“none”进行搜索）
5. 🔽 低优先级
6. ⏬️ 最低优先级

示例

```tasks
not done
priority is above none
```

```tasks
priority is high
```

```tasks
not done
priority is not none
```

从 Tasks 4.2.0 开始，现在可以使用 task.priorityName 和 task.priorityNumber按优先级名称和编号进行 自定义过滤。

使用优先级名称：

filter by function task.priorityName !== 'Normal'

• 与 priority is not none 。

使用优先级编号：

filter by function task.priorityNumber % 2 === 0

• 使用任务的优先级编号进行过滤，其中最高为 0，最低为 5。
• 这个人工示例找到所有具有偶数优先级编号的任务，即最高、中和低优先级。

Urgency

没有内置的指令来按紧急程度进行过滤。

从 Tasks 4.2.0 开始，现在可以使用 task.urgency按紧急程度进行 自定义过滤。

filter by function task.urgency > 8.9999

• 查找紧急度分数高于 9.0 的任务。
• 请注意，使用的限制值为 8.9999 。
• 比较两个紧急度值“小于”或“大于”（使用 > 、 >= 、 < 或 <= 之一）的搜索必须稍微调整其值以允许舍入。

filter by function task.urgency > 7.9999 && task.urgency < 11.0001

• 查找紧急度得分在 8.0 到 11.0 之间（含）的任务。

filter by function task.urgency.toFixed(2) === 1.95.toFixed(2)

• 查找为 1.95 的任务。
• 这是对任何数值进行相等或不等搜索的正确方法。
• === 两侧的 .toFixed(2) 确保要比较的两个数字都四舍五入到相同的小数位数 (2)。
• 这很重要，可以防止在比较非整数时发现 10.29 不完全相同。

filter by function task.urgency.toFixed(2) !== 1.95.toFixed(2)

• 查找除默认分数 1.95 之外的任何紧急任务。

filter by function task.urgency === 10.29

• 这样就不会发现任何任务了。
• 不要使用原始数字来搜索任何数字的相等或不相等，无论是看似整数还是浮点数。
• 通过使用 group by urgency 并查看标题，我们可以得出结论，具有以下值的任务具有紧急程度 10.19 ：
  • 明天到期，
  • 没有优先权符号。
• 由此，可以自然地假设我们可以搜索 task.urgency === 10.29 。
• 但是，我们的函数正在检查以下值是否相等：
  • task.urgency 大约是：
    • 10.292857142857140928526860079728
  • 10.29 大约为：
    • 10.289999999999999147348717087880
• 这些值并不完全相等，因此测试无法找到任何匹配的任务。没有内置的指令来按紧急程度进行过滤。

Recurrence

• is recurring
• is not recurring
• recurrence (includes|does not include) <part of recurrence rule>
  • 匹配不区分大小写（忽略大小写）。
  • 请注意，搜索的文本是以编程方式生成的并且是标准化的，因此可能与任何手动键入的任务中的文本不完全匹配。例如，带有 🔁 every Sunday 任务将按 every week on Sunday 进行搜索。
  • 查看任务的标准化重复规则的最简单方法是使用 group by recurrence ，并查看生成的组标题。
• recurrence (regex matches|regex does not match) /<JavaScript-style Regex>/
  • 正则表达式是否匹配（默认区分大小写）。

从 Tasks 4.2.0 开始，现在可以使用 task.isRecurring 和 task.recurrenceRule按重复进行 自定义过滤。

使用 task.isRecurring ：

filter by function task.isRecurring

• 这与 is recurring 相同。
• 它可以与 && （布尔 AND）或 || 一起使用（布尔或）与其他条件结合。

filter by function !task.isRecurring

• 这与 is not recurring 相同。
• 它可以与 && （布尔 AND）或 || 一起使用（布尔或）与其他条件结合。

filter by function (!task.isRecurring) && task.originalMarkdown.includes('🔁')

• 查找重复规则已损坏/无效的任务。
• 这假设使用任务表情符号格式，如果使用其他格式，当然应该更新。
• 这使用了任务实现细节的知识，即重复规则被读取并从描述中删除，即使它们是无效的。
• 所以我们必须在 task.originalMarkdown 中搜索重复标记，看看当 task.isRecurring 为 false 时，原始任务是否包含重复指示符。

使用 task.recurrenceRule - 使用前请阅读有关 task.recurrenceRule任务属性> 其他任务属性值 说明：

filter by function task.recurrenceRule.includes("every week")

• 类似于 recurrence includes every week ，但区分大小写。

filter by function !task.recurrenceRule.includes("every week")

• 类似于 recurrence does not include every week ，但区分大小写。

filter by function task.recurrenceRule.includes("every week") && task.recurrenceRule.includes("when done")

• 查找每周到期的任务，并且在其重复规则中包含when done 。

filter by function task.recurrenceRule.includes("every week") && !task.recurrenceRule.includes("when done")

• 查找每周到期且不包含重复规则中 when done 任务。

Sub-Items

• exclude sub-items
  • 设置此选项后，结果列表将仅包含文件中未缩进的任务。它只会显示列表中顶级列表项的任务。

Tags 标签

有关 标签 在任务插件中的行为方式的重要信息，请参阅标签。

• no tags
• has tags
• tags (include|do not include) <tag> 或者
• tag (includes|does not include) <tag>
  • 匹配不区分大小写（忽略大小写）。
  • 匹配时忽略全局过滤器。
  • 标签上的 # 是可选的，因此 #home 和 home 将匹配 #home 。
  • 如果给出了 # ，则它必须存在，因此搜索 #home 将匹配 #home 但不匹配 #location/home 。
  • 匹配是部分的，因此 tags include foo 将匹配 #foo/bar 和 #foo-bar 。
• tags (regex matches|regex does not match) /<JavaScript-style Regex>/ 或者
• tag (regex matches|regex does not match) /<JavaScript-style Regex>/
  • 正则表达式是否匹配（默认区分大小写）。
  • 必读：正则表达式搜索。
  • 通过在正则表达式末尾放置 $ 字符，可以实现避免子标签的标签搜索。请参阅下面的示例。
  • 如果搜索子标签，请记住转义正则表达式中的斜杠： \/

从 Tasks 4.2.0 开始，现在可以使用 task.tags按标签进行 自定义过滤。

filter by function task.tags.length === 1

• 查找恰好具有 1 个标签的任务（任何全局过滤器除外）。

filter by function task.tags.length > 1

• 查找具有多个标签的任务（任何全局过滤器除外）。

这些是更复杂的示例，如果您使用带有 嵌套标签的 任务，您可能需要复制这些示例。

filter by function task.tags.find( (tag) => tag.includes('/') ) && true || false

• 查找至少具有一个嵌套标签的所有任务。

filter by function task.tags.find( (tag) => tag.split('/').length >= 3 ) && true || false

• 查找至少具有一个双层嵌套标签的所有任务，例如 #context/home/ground-floor 。
• 这会在 / 字符处分割每个标签，如果至少有 3 个单词，则算作匹配。

标签查询示例

• tags include #todo
• tags do not include #todo
• tag regex matches /#t$/
  • 搜索单字符标签 #t ，不带子标签，因为 $ 匹配标签文本的结尾。
• tag regex matches /#book$/i
  • 尾随 i 表示不区分大小写。
  • 搜索 #book 、 #Book 、 #BOOK 等标签，而 $ 会阻止匹配 #books 、 #book/literature 等。

Markdown

从 Tasks 4.2.0 开始，现在可以使用 task.originalMarkdown按原始 Markdown 行进行 自定义过滤。

例如，这可用于从 Tasks 未解析的 task.originalMarkdown 中提取信息，以用于过滤任务。

文件属性的过滤器

这些过滤器允许搜索特定文件和文件部分中的任务。

• File Path 文件路径
• Root 根路径
• Folder 文件夹
• File Name 文件名
• Heading 标题

File Path 文件路径

请注意，该路径包含 .md 扩展名。

• path (includes|does not include) <path>
  • 匹配不区分大小写（忽略大小写）。
  • 使用 {{query.file.path}} 或 {{query.file.pathWithoutExtension}} 作为包含当前查询的文件路径的占位符。
    • 例如， path includes {{query.file.path}}
    • 有用的阅读：查询属性 和 占位符
• path (regex matches|regex does not match) /<JavaScript-style Regex>/
  • 正则表达式是否匹配（默认区分大小写）。
  • 必读：正则表达式搜索。

从 Tasks 4.2.0 开始，现在可以使用 task.file.path按文件路径进行 自定义过滤。

在任务 4.8.0 中 task.file.pathWithoutExtension 已添加。

从 Tasks 5.1.0 开始，可以在自定义过滤器中方便地使用查询的文件路径：

• query.file.path 或
• query.file.pathWithoutExtension
• 有用的阅读：查询属性。

filter by function task.file.path.includes('tasks releases/4.1.0 Release.md')

• 与“路径包含”类似，但它区分大小写：大小写很重要。

filter by function task.file.path === 'tasks releases/4.1.0 Release.md'

• 精确、区分大小写的相等搜索。
• 请注意，还需要包含文件扩展名。
• 对于内置搜索，这只能使用正则表达式来完成，使用特殊字符 ^ 和 $ ，并转义任何具有特殊含义的字符，例如 / 。

filter by function task.file.path.toLocaleLowerCase() === 'TASKS RELEASES/4.1.0 RELEASE.MD'.toLocaleLowerCase()

• 精确的、不区分大小写的相等搜索。
• 通过将这两个值都小写，我们不必担心在查询中手动将它们小写。

Root 根路径

root 是包含任务的文件的顶级文件夹，即路径中的第一个目录，对于 Vault 根目录中的文件，该目录将为 / 。

• root (includes|does not include) <root>
  • 匹配不区分大小写（忽略大小写）。
  • 使用 {{query.file.root}} 作为包含当前查询的文件根的占位符。
    • 例如， root includes {{query.file.root}}
    • 有用的阅读：查询属性 和 占位符
• root (regex matches|regex does not match) /<JavaScript-style Regex>/
  • 正则表达式是否匹配（默认区分大小写）。
  • 必读：正则表达式搜索。

从 Tasks 4.2.0 开始，现在可以使用 task.file.root按根文件夹进行 自定义过滤。

从 Tasks 5.1.0 开始，可以在自定义过滤器中方便地使用查询的文件根：

• query.file.root
• 有用的阅读：查询属性。

filter by function task.file.root === '/'

• 在 Vault 根目录的文件中查找任务。
• 请注意，这是区分大小写的：大小写很重要。

filter by function task.file.root === 'Work/'

• 在 Vault 根目录下的 Work 文件夹内的文件中查找任务。
• 请注意，这是区分大小写的：大小写很重要。

Folder 文件夹

这是包含任务的文件的文件夹，对于 Vault 根目录中的文件，该 文件夹 将为 /。

• folder (includes|does not include) <folder>
  • 匹配不区分大小写（不考虑大小写）。
  • 使用 {{query.file.folder}} 作为包含当前查询的文件文件夹的占位符。
    • 例如， folder includes {{query.file.folder}} 它将匹配包含查询的文件夹和所有子文件夹中的任务。
    • 有用的阅读材料：Query Properties 和 Placeholders
• folder (regex matches|regex does not match) /<JavaScript-style Regex>/
  • 正则表达式是否匹配（默认区分大小写）。
  • 必读：正则表达式搜索。

从 Tasks 4.2.0 开始，现在可以使用 task.file.folder 按文件夹 进行自定义筛选。

File Name 文件名

请注意，文件名包含 .md 扩展名。

• filename (includes|does not include) <filename>
  • 匹配不区分大小写（忽略大小写）。
  • 使用 {{query.file.filename}} 或 {{query.file.filenameWithoutExtension}} 作为包含当前查询的文件的文件名的占位符。
    • 例如， filename includes {{query.file.filename}}
    • 有用的阅读：查询属性 和 占位符
• filename (regex matches|regex does not match) /<JavaScript-style Regex>/
  • 正则表达式是否匹配（默认区分大小写）。

从 Tasks 4.2.0 开始，现在可以使用 task.file.filename按文件名进行 自定义过滤。

在任务 4.8.0 中 task.file.filenameWithoutExtension 已添加。

从 Tasks 5.1.0 开始，可以在自定义过滤器中方便地使用查询的文件名：

• query.file.filename 或
• query.file.filenameWithoutExtension
• 有用的阅读：查询属性。

filter by function task.file.filename === "4.1.0 Release.md"

• 在任何文件夹中具有确切文件名的文件中查找任务。
• 相等性测试 === 要求包含文件扩展名 .md 。

filter by function task.file.filename.includes("4.1.0 Release")

• 在名称包含给定文本的文件中查找任务。
• 通过使用 .includes() 并省略文件扩展名，这还将找到诸如 14.1.0 Release.md 和 4.1.0 Release Notes.md 之类的文件。

Heading 标题过滤器

1. heading (includes|does not include) <search text>
   • 它至少包含字符串 <search text> 的一次，匹配该部分中所有任务。
     • 这是，它是一个子串搜索。
     • 所以 heading includes Day Planner 将匹配第 ## Monday Day Planner 和第 ## Day Planner for typical day 节的任务。
   • 它忽略大小写。搜索不区分大小写。
     • 所以 heading includes Day Planner 将匹配第 ## Day Planner 和第 ## DAY PLANNER 节的任务。
   • 任何引号字符（ ' 和 " ）都包含在搜索文本中。
     • 所以 heading includes "Day Planner" 将匹配一个部分 ## "Day Planner" 。
     • 但是不会匹配带有标题如 ## Day Planner 的任务。
2. heading (regex matches|regex does not match) /<JavaScript-style Regex>/
   • 正则表达式匹配（默认区分大小写）。
   • 正则表达式（或“regex”）搜索是一个强大但高级的功能。
   • 它需要深入的知识才能成功使用，不会错过预期的搜索结果。
   • 它很容易编写一个看起来正确的正则表达式，但它包含一个具有非明显意义的特殊字符。
   • 必备阅读： Regular Expression Searches.

案例

```tasks
heading includes pkmerdocs
done last week
```

解释查询 (Explaining Queries)

当在实时预览和阅读模式下查看任务块时， explain 指令会在搜索结果的开头添加一些额外的输出。

这样做有很多好处：

• 基于日期的过滤器很容易理解：
  • 过滤器中的所有日期都会展开，以显示搜索中使用的实际日期。
• 布尔查询逻辑更清晰。
  • 查询的组合（通过 AND 、 OR 、 NOT 等）可以更清楚地看到。
• 如果启用了 全局过滤器，它会包含在说明中。
  • 这通常可以解释为什么结果中缺少任务。
• 如果启用了 全局查询，它也会包含在说明中。
• 列出所有 “分组依据” 指令（自任务 5.4.0 起）
• 列出所有 “排序依据” 指令（自任务 5.4.0 起）

示例：过滤器中的日期已扩展

例如，当以下文本放置在任务查询块中时：

starts after 2 years ago
scheduled after 1 week ago
due before tomorrow
explain

2022-10-21 ，结果如下：

Explanation of this Tasks code block query:

  starts after 2 years ago =>
    start date is after 2020-10-21 (Wednesday 21st October 2020) OR no start date

  scheduled after 1 week ago =>
    scheduled date is after 2022-10-14 (Friday 14th October 2022)

  due before tomorrow =>
    due date is before 2022-10-22 (Saturday 22nd October 2022)

  No grouping instructions supplied.

  No sorting instructions supplied.

请注意它如何非常清楚地显示正在搜索的日期，包括星期几。

它还表明 starts 搜索也匹配没有开始日期的任务。

排序 (Sorting)

• Sort by Task Statuses
• Sort by Task Dependencies
• Sort by File Properties
• Sort by Dates in Tasks
• Sort by Other Task Properties

示例：

```tasks
not done
due today
sort by due
```

```tasks
done
sort by done reverse
```

```tasks
not done
due before next monday
sort by status
sort by description reverse
sort by path
```

```tasks
sort by status
sort by due
sort by path
```

基本大纲：

• Sort by Task Statuses
  • Status
  • Status Name
  • Status Type
  • Status Symbol
  • Next Status Symbol
• Sort by Task Dependencies
  • Id
  • Depends On
• Sort by Dates in Tasks
  • How dates are sorted
  • Done Date
  • Due Date
  • Scheduled Date
  • Start Date
  • Created Date
  • Cancelled Date
  • Happens
• Sort by Other Task Properties
  • Description
  • Description without tags
  • Priority
  • Urgency
  • Recurrence
  • Tags
  • Original Markdown
  • Random sorting
• Sort by File Properties
  • File Path
  • Root
  • Folder
  • File Name
  • Heading

分组 (Grouping)

基础 (Basic)

默认情况下，任务在单个列表中显示任务。

要按标题划分匹配任务，您可以向查询添加 group by 。

示例

```tasks
not done
group by filename
```

分组的类型

• 按任务状态分组：Group by Task Statuses
  • 同 过滤器 (Filters)#任务状态过滤器，详见 📍官方文档
• 按任务依赖性分组：Group by Task Dependencies
  • 详见 📍官方文档
• 按任务中的日期分组：Group by Dates in Tasks
  • 详见 📍官方文档
• 按其他任务属性分组：Group by Other Task Properties
  • 同 过滤器 (Filters)#其他任务属性的筛选器，详见 📍官方文档
• 按文件属性分组：Group by File Properties
  • 同 过滤器 (Filters)#文件属性的过滤器，详见 📍官方文档

拓展：自定义分组

任务提供了许多内置的分组选项，但有时它们并不能完全满足所有用户的需求。现在，任务有一个强大的机制供您创建自己的自定义组，提供令人难以置信的灵活性。

自定义分组指令 group by function，您可以在 自定义分组 中找到有关此非常强大的功能的更多信息。

多个分组 (Multiple groups)

您可以添加多个 group by 查询选项，每个选项占一行。这将创建嵌套分组。第一个分组优先级最高。

每个后续的 group by 将在现有分组内生成新的标题层次：

• 第一个 group by 显示为 h4 标题
• 第二个 group by 显示为 h5 标题
• 第三和后续的 group by 显示为 h6 标题

示例，多个分组按顺序嵌套：

```tasks
not done
group by folder
group by filename
group by heading
```

细化分组 (Refining groups)

可以设置分组的几个参数：

1. Reverse：控制分组的排列顺序。
2. Limiting group size：限制每组中的任务数量。

Reverse

在要分组的属性名称后面，可以添加 reverse 关键字。如果指定，则该属性的组标题将相反。

例如：

• group by due 将对组标题进行排序：
  • 从最早的预定期开始…
  • 到最后的截止日期
• group by due reverse 将对组标题进行排序：
  • 从最新的预定期开始…
  • 到最早的预定期最后

Limiting group size

您可以限制每个组中的任务数量，也许首先处理最重要的事情。

使用查询字符串 limit groups to <number> tasks 。这将仅列出查询结果中每组中的前 <number> 任务。

简写是 limit groups <number> 。

限制 (Limiting)

• 限制任务总数
• 限制每组中的任务数量
• 查看找到的任务总数

限制任务总数

您可以限制显示为查询结果的任务总数。

使用查询字符串 limit to <number> tasks 。这只会列出查询的前 <number> 结果（排序后）。

简写是 limit <number> 。

限制每组中的任务数量

使用查询字符串 limit groups to <number> tasks 可以限制每个组中允许的任务数量。

简写是 limit groups <number> 。

查看找到的任务总数

如果任一 limit 选项阻止任何任务显示在结果中，则会显示总数，例如：

50 of 686 tasks

布局 (Layout)

• Task Elements
• Query Elements
• Hiding/Showing Elements
• Full Mode
• Short Mode

Task Elements

以下任务元素存在：

• id（标识）
• depends on（依赖于）
• priority（优先级）
• cancelled date（取消日期）
• created date（创建日期）
• start date（开始日期）
• scheduled date（计划日期）
• due date（截止日期）
• done date（完成日期）
• recurrence rule（重复规则）
• on completion （完成时）
• tags （标签）

所有这些任务元素默认情况下都会显示，因此如果您不想显示其中任何一个，可以使用命令“hide”。

Query Elements

存在以下查询元素：

• tree
• edit button
• postpone button
• backlink
• urgency
• task count

Hiding/Showing Elements

每个 Task元素(Task Elements) 可以都设置隐藏 (hide) 或显示 (show)，且查询中可以使用多个 show 和 hide 指令，每个指令位于单独的行上。

例如：

```tasks
no due date
path includes GitHub

hide recurrence rule
hide task count
hide backlink
show urgency
```

Hide OR Show Tree

Show Tree

show tree 指令使我们能够查看任务中的父/子关系，以及它们的嵌套任务和列表项：

```tasks
not done
filename includes Party Planner

show tree
hide backlink
```

Hide OR Show Tags

Layout - Tasks User Guide - Obsidian Publish

只有 Obsidian 识别的标签才会被 hide tags 隐藏。

hide tags

Full Mode

在**完整模式 (Full Mode)**下，查询结果将显示表情符号和具体的重复规则或日期。

这是默认模式，该命令为 full mode。

Example:

```tasks
not done
full mode
```

Short Mode

在**短模式 (Short Mode)**下，查询结果只会显示表情符号，而不显示具体的重复规则或日期。您可以将鼠标悬停在任务上以查看工具提示中的规则和日期。

该命令是 short mode 。

Example:

```tasks
not done
short mode
```

注释 (Comments)

所有以 # 字符开头的查询行都会被视为注释并被忽略。

Example:

```tasks
not done
# Uncomment the following line to enable short mode:
# short mode
```

Inline comments 行内注释

一行中的 {{! 和 }} 之间的任何文本都将被忽略。不支持多行注释。

```tasks
not done
short mode {{! 这条注释将被忽略 }}
```

当 Tasks 处理查询中的占位符时，这样的注释将被移除。

全局查询 (Global Query)

您可以在设置中设置全局查询，任务将添加到保管库中所有查询的开头。

忽略全局查询 (Ignore global query)

如果您需要忽略给定任务块中的全局查询，您可以将 ignore global query 指令添加到块的任何位置。

例如，这允许您让任务搜索默认忽略某些文件夹。然后，在少数搜索中，您可以启用在这些文件夹中搜索任务。

例子

tags include work
ignore global query

组合过滤器 (Combining+Filters)

任务提供的各个 过滤器 (Filters) 可以通过以下方式以强大的方式组合在一起：

1. 将它们中的每一个包裹在分隔符中，例如 ( 和 ) ，
2. 然后用布尔运算符（例如 AND 、 OR 和 NOT 将它们连接起来。

例如：

```tasks
not done
(due after yesterday) AND (due before in two weeks)
[tags include #inbox] OR [path includes Inbox] OR [heading includes Inbox]
```

上述任务块中的每 3 行代表一个单独的过滤器，并且仅显示与_ 所有_3 行过滤器匹配的任务。

语法 (Syntax)

一个或多个过滤器可以通过布尔运算符组合在一行中，以创建一个新的、强大的、灵活的过滤器。

下面是简单布尔指令的组件图：

+--------------------------+       +--------------------------+
|   ( tag includes #XX )   |  OR   |   ( tag includes #YY )   |
+--------------------------+       +--------------------------+
    ^                  ^               ^                  ^
    |                  |               |                  |
    +- delimiters: () -+               +- delimiters: () -+
      for left sub-expression             for right sub-expression
              |                                  |
              +--------- Operator: OR -----------+
                   Connects both sub-expressions

以下规则适用：

• 每个单独的过滤器必须由一对分隔符包围：
  • 本指南中最常用的分隔符是 ( 和 ) 。
  • 可用分隔符的完整列表是：
    • (....)
    • [....]
    • {....}
    • "...."
  • 布尔指令中不能混合使用分隔符类型：您必须为行上的过滤器选择适当的分隔符。
• 支持的运算符有： AND 、 OR 、 NOT 、 AND NOT 、 OR NOT 和 XOR 。
  • 运算符区分大小写：它们必须大写。
  • 请参阅下面的 布尔运算符。
• 您可以使用更多分隔符将更多过滤器嵌套在一起。
• 尾部反斜杠( \ ) 可用于将长过滤器分解为多行，如 行延续 中所述。
• 每行组合的过滤器数量以及括号的嵌套级别没有实际限制。

建议：

• 组合两个以上过滤器时，请随意使用 ( 和 ) （或任何其他分隔符对）以确保获得预期的逻辑。请参阅下面的 执行优先级。
• 请参阅 布尔过滤器故障排除 以获取选择分隔符的帮助，特别是在 filter by function 时。

从技术上讲，行仍然具有隐式 AND 关系（因此完全保留了向后兼容性），但一行现在可以具有由 AND 、 OR 、 NOT 、 AND NOT 、 OR NOT 和 XOR 以及括号组成的多个过滤器。

执行优先级 (Execution Priority)

运算符按以下顺序评估：

1. NOT
2. XOR
3. AND
4. OR

所以这两个过滤器是完全等价的 - 请注意第二个过滤器中的额外括号：

(tag includes #XX) OR (tag includes #YY) AND (tag includes #ZZ)

(tag includes #XX) OR ( (tag includes #YY) AND (tag includes #ZZ) )

这两者也完全等价：

(tag includes #XX) AND (tag includes #YY) OR (tag includes #ZZ)

( (tag includes #XX) AND (tag includes #YY) ) OR (tag includes #ZZ)

在构建复杂的过滤器组合时，自由使用 ( 和 ) 是最安全的，这样您就可以确信自己得到了预期的行为。

布尔运算 (Boolean Operators)

AND

当您使用 AND 将过滤器组合在一起时，只会显示与 _ 每个 _ 过滤器匹配的任务。

例如，这将显示包含单词 some 并具有开始日期的任务：

(has start date) AND (description includes some)

任务要求每个过滤器行都匹配，因此上面的示例相当于：

has start date
description includes some

当与 OR 和 NOT 结合使用时， AND 变得特别有价值。

OR

当您使用 OR 将过滤器组合在一起时，将显示 _ 至少与其中一个 _ 过滤器匹配的任务。

例如，要显示路径中带有 inbox 文件中的任务以及任务行上带有 #inbox 标签的文件：

```tasks
not done
(path includes inbox) OR (description includes #inbox)
```

NOT

对于一个简单的例子，这两个是等效的：

path does not include inbox

NOT (path includes inbox)

NOT 对于否定更复杂的表达式更有用。

举一个更现实的例子，与此相反：

(path includes x) OR (description includes #x)

…可以在不检查新逻辑的情况下表达，如下所示：

NOT ( (path includes x) OR (description includes #x) )

另一种表达方式需要更多的细心和思考：

(path does not include x) AND (description does not include #x)

AND NOT

例如：

(has start date) AND NOT (description includes some)

OR NOT

例如：

(has start date) OR NOT (description includes special)

异或

XOR 或 exclusive or 显示 _ 仅匹配所提供条件之一 _ 的任务。

例如，显示任务：

• 在其路径中带有 inbox 文件中
• 或者标签 #inbox 位于任务行的位置
• 但不是两者都：

```tasks
not done
(path includes inbox) XOR (description includes #inbox)
```

它不会显示路径中同时带有 inbox 和任务行中带有 #inbox 标签的任务。

警告

不要将两个以上的过滤器与 XOR 组合在一起，只要求其中一个为真。它不会给出您期望的结果。

(filter a) XOR (filter b) XOR (filter c) 匹配仅匹配其中一个过滤器的任务，以及匹配所有三个过滤器的任务。

反向链接 (BackLinks)

在“Task 查询结果”中，默认情况下，每个任务都显示其文件名和上一个标题的名称，例如 (ACME > Steps to world domination) 。这称为反向链接 (BackLink)。

您可以单击反向链接 (BackLink) 直接导航到 Task 的源代码行。

这遵循单击内部链接时使用的 标准Obsidian键盘修饰符， 以控制打开方式（导航、新选项卡、新选项卡组、新窗口）。

行延续 (Line Continuations)

在查询中换行长行

在任务代码块中，**反斜杠 ( \ )**是“行继续字符”。如果反斜杠位于行尾，则该行被视为在下一行继续。

这对于将长查询划分为多行非常有用，以获得更好的可读性。

例如这个查询：

(priority is highest) OR       \
    (priority is lowest)
explain

…运行此搜索：

Explanation of this Tasks code block query:

  (priority is highest) OR       \
      (priority is lowest)
   =>
  (priority is highest) OR (priority is lowest) =>
    OR (At least one of):
      priority is highest
      priority is lowest

  No grouping instructions supplied.

  No sorting instructions supplied.

此功能对于较长的 Combining Filters 、 Custom Sorting 和 Custom Grouping 行以及其他可能难以在一行中阅读的查询很有帮助。

注意事项：

• 要成为连续字符， \ 必须是该行的最后一个字符。
• 所有 \ 及其周围的所有空格都被压缩为一个空格。
• 考虑缩进第二行和后续行，以便查询的结构立即清晰。
• 考虑对齐 \ 字符以提高可读性。
• 如果有疑问，请添加 explain 指令以检查代码块的解释方式。

需要尾部反斜杠的搜索

在任务代码块中，行末的两个反斜杠 ( \\ )被视为单个反斜杠。

这使得在查询需要尾部反斜杠的极少数情况下可以进行搜索。

例如这个查询：

## Search for a single backslash:
description includes \\
explain

…运行此搜索：

Explanation of this Tasks code block query:

  description includes \\ =>
  description includes \

  No grouping instructions supplied.

  No sorting instructions supplied.

注意事项：

• 或者，您可以在尾随 \ 之后添加一个或多个空格，以防止它成为连续字符。
  • 但这是有风险的，因为一些编辑器和 linter 会删除不必要的尾随空格。
  • 所以两个反斜杠选项更安全。
• 如果有疑问，请添加 explain 指令以检查代码块的解释方式。

讨论

若阁下有独到的见解或新颖的想法，诚邀您在文章下方留言，与大家共同探讨。