Obsidian中如何正确添加自定义属性？

Question

在使用 Obsidian 时，许多用户希望为笔记添加自定义属性（如作者、优先级、项目状态等）以增强元数据管理。常见问题是：**如何正确使用 YAML frontmatter 添加自定义属性，使其既能被 Obsidian 正确识别，又能与插件（如 Dataview 或 Templater）兼容？** 用户常因格式缩进错误、冒号后缺少空格或属性命名不规范导致属性无法解析。此外，在启用“Strict YAML”设置时，不当的语法会引发警告或数据读取失败。掌握标准 YAML 语法并结合 Obsidian 的解析规则，是确保自定义属性生效的关键。

Answer 1

1. YAML Frontmatter 基础语法与 Obsidian 的识别机制

在 Obsidian 中，YAML frontmatter 是添加自定义元数据的核心方式。它位于笔记顶部，由三个短横线（---）包裹，格式如下：

---
title: 我的笔记
author: Alice
priority: high
status: in-progress
---

Obsidian 通过解析该区块提取键值对作为元数据。关键点包括：

• 冒号后必须有一个空格，如 author: Alice 而非 author:Alice
• 使用空格进行缩进，禁止使用 Tab 字符
• 属性名应避免特殊字符，推荐使用小写字母和连字符（如 project-status）

若启用“Strict YAML”设置，任何格式偏差都会导致解析失败，并在编辑器中显示警告。

2. 自定义属性命名规范与插件兼容性分析

Dataview 和 Templater 等插件依赖一致的属性命名来查询和渲染数据。以下为常见命名反模式与优化建议：

不推荐写法	推荐写法	原因说明
Author Name	author	避免空格和大写，确保 Dataview 查询一致性
priority_level	priority	简化层级，提升可读性
Project Status	status	统一状态字段，便于跨笔记聚合
due date	due-date	使用连字符替代空格，符合 YAML 键名惯例

此外，Dataview 查询语句如 TABLE status FROM "projects" 依赖精确匹配的字段名。

3. 多层级结构与嵌套属性的正确使用

当需要表达复杂关系时，可使用嵌套结构。例如表示任务负责人及其联系方式：

---
project:
  owner: Bob
  contact: [e-mail]
  deadline: 2025-04-30
tags:
  - work
  - urgent
...

注意：嵌套层级需保持缩进一致（通常为 2 或 4 个空格）。Dataview 支持路径访问，如 project.owner 可直接用于表格或条件判断。

错误示例：
project:
owner: Bob # 缺少缩进，将被视为同级键

4. 插件协同：Dataview 与 Templater 的数据联动流程

结合 Dataview 进行动态内容生成时，需确保 frontmatter 属性可被脚本读取。以下为典型工作流：

graph TD A[创建笔记] --> B[添加YAML frontmatter] B --> C{启用Strict YAML?} C -- 是 --> D[严格校验格式] C -- 否 --> E[宽松解析] D --> F[保存并触发插件加载] E --> F F --> G[Dataview索引属性] G --> H[Templater调用变量] H --> I[生成报告/看板]

Templater 模板中可通过 <% tp.frontmatter.status %> 动态插入状态值，实现自动化文档组装。

5. 调试技巧与常见错误排查清单

当属性未被识别时，建议按以下步骤排查：

1. 检查 frontmatter 是否以 --- 开始和结束
2. 确认冒号后均有且仅有一个空格
3. 验证缩进是否统一为空格（推荐 2 space）
4. 禁用“Strict YAML”测试是否为格式问题
5. 在 Dataview 查询中使用 DEBUG 查看原始元数据输出
6. 避免在键名中使用中文或特殊符号（如 ＠、＃）
7. 确保数组项以 - 开头并正确缩进
8. 重启 Obsidian 以刷新缓存索引
9. 使用社区工具如 "YAML Linter" 插件预检语法
10. 查看控制台日志（Ctrl+Shift+I）获取解析异常详情

通过系统化验证，可显著降低元数据失效风险。