Obsidian Plugin Tasks

后果：data.json存储了所有自定义状态的定义。如果删除了它且没有备份，所有的 [/]、[-] 等符号将失去其背后的"逻辑属性"，导致查询失效。

• 多用户环境警告：在Git同步或团队共享库中，避免在不同设备上同时编辑同一任务。Tasks插件的自动修改可能导致合并冲突

⚠️ 全局过滤器陷阱

• 功能说明：Tasks插件有一个核心设置——Global Filter（例如 #task）
• 行为：如果启用了Global Filter，所有任务必须包含该标签
• 严重后果：
  • 未包含标签的任务在查询中不会显示
  • ignore global query 无法跳过此限制（因为插件根本没索引这些行）
  • 这是索引层面的限制，而非查询层面的过滤

全局过滤器副作用：

• 自动标签：开启全局过滤器后，任务模态框（Create or edit task）生成的任务会自动带上该标签
• 瞬间蒸发：如果你手动删除标签，该任务将从所有Tasks查询结果中瞬间蒸发，且不报任何错误
• 迁移警告：启用全局过滤器后，需要为所有现有任务添加标签，这是一个需要谨慎操作的迁移过程

⚠️ 数据安全附加警告

同步冲突

• 风险：如果你使用 Obsidian Sync 或 iCloud，Tasks 插件的频繁文件修改极易在同步过程中产生 .sync-conflict 副本
• 建议：
  • 关闭“任务状态自动转换”功能，或
  • 确保单设备编辑，避免多设备同时操作
  • 定期检查并清理同步冲突文件

版本控制冲突

• Git注意事项：在使用Git版本控制时，Tasks的自动修改可能导致频繁的合并冲突
• 最佳实践：使用 git pull --rebase 减少冲突，定期提交更改

Tasks插件使用指南

一、基础语法

基本任务结构

- [ ] 基本任务
- [x] 已完成任务
- [/] 部分完成（进行中）
- [-] 已取消

任务元数据字段

任务通过内联字段（行尾元数据）存储丰富信息，严格遵循格式规范：

- [ ] 任务文本 [元数据:: 值]

核心元数据字段

优先级标识（官方标准）

重要：

• 优先级Emoji只有箭头符号，没有🔴🟡🟢颜色圆点！
• 解析逻辑：Tasks插件的解析器是从行尾向前解析元数据的
  • 优先级可以放在日期之前或之后
  • 绝对不能放在描述文本中间
  • 必须与其他内容用空格分隔
• Unicode字符差异警告：这些是Unicode字符，在不同操作系统（iOS vs Windows）和字体下外观会有细微差异，手动输入极易出错。
• 强烈推荐：通过模态框设置优先级：使用 Tasks: Create or edit 命令打开模态框，避免手动输入Emoji的错误。

优先级查询语法扩展

比较查询

• 语法：
  • priority is above medium（高于中等优先级）
  • priority is below high（低于高优先级）
• 优先级顺序：Highest > High > Medium > Low > Lowest
• 示例：
  • priority is above medium 匹配 Highest 和 High
  • priority is below high 匹配 Medium、Low 和 Lowest

数值映射深度说明

• 内部数值：
  • Highest (1) < High (2) < Medium (3) < Low (4) < Lowest (5)
• 比较逻辑：
  • priority is above medium 实际上是查询数值 < 3 的任务
  • priority is below high 实际上是查询数值 > 2 的任务
• 性能优化：数值比较在大型库中比字符串比较更高效

无优先级查询

• 语法：priority is none
• 功能：匹配没有设置优先级的任务
• 使用场景：用于查找未设置优先级的任务，以便进行优先级分类

日期类型映射（官方标准）

completion与done的区别

重要区别：

• completion（完成日期）：Tasks插件自动添加的完成日期，使用✅符号，格式为✅ 2024-12-31，表示任务实际完成的时间
  • 自动添加：完成任务时会自动添加，除非在设置中禁用并重启Obsidian
• done（完成状态）：表示任务的完成状态，在Tasks查询中使用done或not done过滤，在Dataview中对应task.completed布尔值字段

使用场景：

• 使用completion字段：当你需要查询任务的具体完成时间，如completed after last week
• 使用done状态：当你只需要过滤任务的完成状态，不关心具体完成时间

Dataview中的对应关系：

• task.completed（布尔值）：对应Tasks的done状态
• task.text中可能包含✅ 2024-12-31：但需要从文本中提取，Dataview没有直接的task.completion字段

日期格式与时区注意事项

日期格式：

• 严格使用YYYY-MM-DD格式（无时间，无[[wiki links]]）
• 无效日期在查询中会被静默忽略

时区处理：

• 所有日期基于本地时区，无UTC支持
• 跨设备时区不匹配可能导致日期偏移
• 建议所有协作设备使用相同的系统时区设置

任务ID与块引用

任务ID（官方标准）

• 格式：使用🆔符号，如- [ ] 任务描述 🆔 task1
• 内联字段：id:: task1
• 用途：用于依赖引用和任务标识
• 依赖引用：在依赖中使用任务ID值，如dependsOn:: task1或⛔ task1

块引用（Obsidian标准功能）

• 格式：^block-id（Obsidian标准块引用格式）
• 特点：由字母、数字、连字符、下划线组成
• 用途：用于在Obsidian中引用特定段落或任务
• 注意：这是Obsidian的标准功能，与Tasks插件的任务ID是不同的概念

重要区别

• 任务ID：Tasks插件特有，用于依赖关系，格式为🆔 task123
• 块ID：Obsidian标准功能，用于块引用，格式为^block-id
• 依赖引用：使用任务ID值（如task123），不是块引用（如^block-id）

任务依赖详细机制

• 依赖语法：dependsOn:: task123 或使用 ⛔ 符号（如 ⛔ task123）
• 依赖目标：依赖的是任务ID，不是文件块引用（^block-id）
• 示例：
  • dependsOn:: abc123（内联字段格式）
  • ⛔ abc123（Emoji格式）
• 依赖状态：
  • ⛔ 依赖任务未完成时，被阻塞任务显示为'blocked'状态
  • ✅ 依赖任务完成后，被阻塞任务自动变为可用状态，并在查询中显示为'unblocked'
• 依赖传递：支持多级依赖链（任务A依赖任务B，任务B依赖任务C）
• 循环检测：系统会检测并警告依赖循环，避免死锁
  • 显示：在任务旁边显示⚠️图标，悬停显示"循环依赖"
  • 处理：自动将状态设为"cannot-complete"，阻止完成操作
  • 解决：需要手动打破依赖链，移除或修改导致循环的依赖关系
• 重要注意：依赖字段会从下一个重复任务中移除

依赖查询语法

官方查询语法：

• depends on <id> - 查询依赖特定ID的任务
• is blocked - 查询被阻塞的任务
• is blocking - 查询正在阻塞其他任务的任务

示例：

is blocked
not done
sort by due

严格格式要求

日期格式：必须使用ISO格式（YYYY-MM-DD），其他格式将被忽略 Emoji日期标识：系统仅识别预定义Emoji（📅⏳➕🛫），自定义Emoji无效 优先级标识：使用箭头Emoji（�⏫��⏬️），不使用颜色圆点

YAML frontmatter优先级

重要：YAML frontmatter中的字段优先级高于行内元数据。

示例：

---