vault backup: 2026-04-18 02:10:45

2026-04-18 02:10:45 +08:00
parent b753b28b20
commit d0f775a47b
283 changed files with 76 additions and 6884 deletions
--- a/Archive/Collection/YAML用法.md
+++ b/Archive/Collection/YAML用法.md
@@ -0,0 +1,255 @@
+---
+tags:
+  - yaml
+aliases:
+type:
+  - Source
+status:
+  - 💤 Archived
+star: false
+date:
+---
+**YAML (YAML Ain't Markup Language) 是一种以数据为中心、对人类友好的数据序列化语言。它因其简洁和高可读性而备受青睐，尤其是在配置文件和知识管理领域。**
+
+### 1. YAML的应用场景
+#### 作为Markdown知识笔记的元数据
+##### 什么是YAML Front Matter？
+
+- **定义:** 它是添加到文件第一行的一系列纯文本属性，用于在Markdown等文件中添加元数据。
+- **别称:** 也常被称为 front matter、页眉、前页、扉页、前言。
+- **作用:** 它是一种人类可读、文件级的元数据，为笔记本身添加了结构化的信息，使得软件可以基于这些信息进行强大的自动化处理，例如分类、查询和筛选。
+
+
+在Obsidian、Joplin等众多工具中，YAML Front Matter是核心功能。它为一篇笔记提供了超越其正文内容的“身份信息”。
+
+**示例：** 在一篇Obsidian笔记的开头，你可以这样定义元数据。
+
+```yaml
+---
+title: "我的Obsidian使用技巧"
+date: 2025-08-21
+tags: [Obsidian, 知识管理, YAML]
+aliases: [Obsidian技巧, 如何使用Obsidian]
+---
+```
+  
+#### 作为AI提示词的格式
+
+当构建复杂的AI提示词（Prompt）时，需要一种能够清晰组织指令、变量和上下文的格式。YAML在这方面表现出色。
+
+| 格式         | 优点                                                         | 缺点                                   | 适用场景                               |
+| ------------ | ------------------------------------------------------------ | -------------------------------------- | -------------------------------------- |
+| **YAML**     | 结构清晰，可读性高，易于手写和维护，适合表达复杂的层级关系。 | 语法依赖严格的缩进，对新手不友好。     | 复杂的、多参数的、需要模板化的AI任务。 |
+| **Markdown** | 自由流畅，接近自然语言，适合编写故事或对话型提示词。         | 结构性差，难以定义精确的配置参数。     | 文学创作、角色扮演、简单的问答。       |
+| **JSON**     | 机器解析极为友好，语法严格，不易产生歧义，是API交互的标准。  | 手写繁琐，括号和引号过多，可读性较差。 | 程序化的API调用，自动化工作流。        |
+
+#### 作为配置文件
+
+YAML是许多现代软件和工具首选的配置文件格式，因为它能清晰地表达复杂的配置结构。
+
+- **智能家居自动化:** 在流行的开源智能家居平台 Home Assistant 中，用户主要通过编辑YAML文件（如 configuration.yaml）来设置自动化场景。例如，“当太阳下山时，自动打开客厅的灯”或者“当传感器检测到湿度低于40%时，开启加湿器”这样的规则，都是通过YAML来定义的。
+    
+- **PC游戏的插件与Mod:** 许多PC游戏（尤其是沙盒类游戏如《我的世界》Minecraft）的服务器插件或Mod，都使用YAML文件作为配置文件。服务器的管理员或玩家可以通过修改这些 .yml 文件，来调整游戏规则、设置商店物品价格、或者自定义玩家加入时的欢迎信息，而无需编写任何代码。
+    
+
+### 2. YAML的基础语法
+#### <mark style="background: #FFF3A3A6;">核心规则</mark>
+
+1. **格式**：采用“关键词: 值”的键值对形式（关键词 英文冒号 空格 值）。
+样例：
+```yaml
+views:
+  - type: table
+    name: 表格
+    order:
+      - file.name
+      - file.fullname
+      - file.tags
+      - file.folder
+```
+2. **空格与缩进**：YAML 的语法对缩进和空格**极其敏感**，这是其结构的核心。理解并遵守这些规则是正确编写 YAML 的关键。
+	- **使用空格进行缩进**：通过空格缩进来表示数据的层级关系和嵌套。
+	- **严禁使用 Tab 键**：只能使用空格进行缩进，绝不能使用 Tab 键。混合使用或单独使用 Tab 键都会导致解析错误。
+	- **缩进需保持一致**：同一层级的元素必须左侧对齐（即保持相同的缩进量）。通常推荐使用 2 个或 4 个空格作为一级缩进。
+	- **冒号和短横线后的空格**：
+	    - 键值对的冒号 (:) 后面必须跟一个空格。
+	    - 列表项的短横线 (-) 后面必须跟一个空格。
+
+#### 基本数据结构
+
+YAML 主要由三种基本数据结构组成：纯量（Scalars）、序列（Sequences/Lists）和映射（Mappings/Dictionaries）。
+
+##### 1. 纯量 (Scalars)
+
+纯量是单个的、不可分割的值，是 YAML 中最基本的数据单元。
+
+- **字符串 (String)**
+    - 默认无需引号：my_string: Hello YAML
+    - 单引号 (')：不会转义特殊字符，所有内容视为字面量。
+    - 双引号 (")：会转义特殊字符，例如 \n 会被解析为换行符。
+- **数字 (Number)**：包括整数和浮点数。
+- **布尔值 (Boolean)**：true 或 false。
+- **空值 (Null)**：使用 null 或 ~ 表示。
+
+**示例代码：**
+```yaml
+# 字符串
+string_value: Hello YAML
+quoted_string: "This is a string with a \n newline."
+
+# 数字
+integer_value: 1024
+float_value: 3.14159
+
+# 布尔值
+is_active: true
+is_enabled: false
+
+# 空值
+empty_value: null
+another_empty: ~
+```
+
+##### 2. 序列 (Sequences / Lists)
+
+序列是一组有序的值，类似于编程语言中的数组或列表。每个列表项由一个短横线 (-) 和一个空格开头。
+
+**示例代码：**
+```yaml
+# 一个简单的水果列表
+fruits:
+  - Apple
+  - Orange
+  - Strawberry
+
+# 也可以使用行内（inline）格式
+fruits_inline: [Apple, Orange, Strawberry]
+```
+
+##### 3. 映射 (Mappings / Dictionaries)
+
+映射是键值对（key-value）的集合，类似于编程语言中的字典或哈希表。
+
+**示例代码：**
+```yaml
+# 描述一个用户的基本信息
+user:
+  name: John Doe
+  age: 30
+  email: john.doe@example.com
+
+# 也可以使用行内（inline）格式
+user_inline: {name: Jane Doe, age: 28}
+```
+
+#### 复合结构：数据嵌套
+
+以上三种基本结构可以自由组合，形成复杂的数据结构。这是 YAML 强大功能的核心体现。
+
+**示例代码：**
+```yaml
+# 一个用户列表，每个用户都是一个包含详细信息的映射
+users:
+  # 第一个用户
+  - name: Alice
+    age: 28
+    is_admin: true
+    roles: # "roles" 的值是一个序列
+      - editor
+      - publisher
+  # 第二个用户
+  - name: Bob
+    age: 35
+    is_admin: false
+    roles:
+      - viewer
+```
+
+#### 多行文本
+**字面量块 `|`**：保留每一个换行。适合要“按原样呈现”的文本。
+```yaml
+about: |
+  第一行
+  第二行
+  第三行
+```
+解析后：`"第一行\n第二行\n第三行\n"`（注意末尾有 1 个换行，因为默认是clip-保留一个结尾换行（\n），但丢掉多余的尾随空行）。
+
+**折叠块** `>`：把换行折叠为空格（空行保留为换行）
+```yaml
+about: >
+  这一段
+  被写成了多行
+  但会折叠成一行显示
+
+  空行用来分段
+  分段之间会出现真正的换行
+```
+解析后：`"这一段 被写成了多行 但会折叠成一行显示\n\n空行用来分段 分段之间会出现真正的换行\n"`
+（你看到：单个换行被折成空格；空行保留为 `\n`；末尾仍有一个换行，因为clip-保留一个结尾换行（\n），但丢掉多余的尾随空行）
+
+#### 注释
+
+使用井号 (#) 进行单行注释。从 # 开始到该行末尾的所有内容都会被忽略。
+```yaml
+# 这是一个注释，它将被解析器忽略。
+key: value # 这也是一个行内注释。
+```
+
+
+### 3. YAML在Obsidian中的实践
+
+在Obsidian中，YAML元数据是实现知识库从简单笔记集合升级为强大个人数据库的关键。它为每篇笔记赋予了结构化的“属性”，使得自动化管理和知识发现成为可能。
+
+#### 从YAML Front Matter到“属性”视图
+
+最初，YAML元数据需要手动在笔记顶端的`---`分隔符之间编写。为了降低使用门槛并提升体验，Obsidian推出了核心的“**属性**”（Properties）功能。
+
+*   **可视化界面**：你不再需要手动输入YAML代码，可以通过一个直观的界面在笔记顶部添加、编辑或删除属性。这个界面提供了文本、数字、日期、复选框和列表等多种属性类型，并会自动补全已存在的属性名和值，极大地保证了数据的一致性。
+*   **源码对应**：你在属性界面上的所有操作，都会实时、准确地转换成笔记源文件顶部的标准YAML Front Matter。你随时可以切换到“源码模式”查看和编辑底层的YAML代码。
+
+#### Obsidian原生支持的特殊属性
+
+Obsidian会对一些特定的YAML属性赋予特殊功能，让它们与软件的核心功能深度集成。
+
+| 属性 (Property) | 功能描述 (Description) | 格式要求 (Format Requirement) |
+| :--- | :--- | :--- |
+| `tags` | 定义笔记的标签，会自动被Obsidian的“标签面板”识别和索引。 | 必须是列表（Array）格式。 |
+| `aliases` | 为笔记设置一个或多个“别名”，方便通过别名进行链接和搜索。 | 必须是列表（Array）格式。 |
+| `cssclasses` | 为当前笔记应用一个或多个自定义的CSS样式片段，实现特定的视觉效果。 | 必须是列表（Array）格式。 |
+
+> **重要更新**：从Obsidian 1.4版本开始，官方统一并强制要求这些原生属性必须使用复数形式（`tags`, `aliases`, `cssclasses`），并且它们的值必须是列表格式。
+
+
+#### 设计你的个人化元数据系统
+
+YAML的真正威力在于自定义。通过建立一套规范的元数据体系，你可以为自己的知识库量身打造强大的分类和检索系统。
+
+| 实践建议 (Practice) | 目的与描述 (Purpose & Description) | 示例 (Example) |
+| :--- | :--- | :--- |
+| **规范命名** | 为了便于Dataview等插件查询，建议属性名全部使用小写，并用下划线代替空格。 | `creation_date` |
+| **笔记分类** | 使用`type`或`category`属性来定义笔记的类型，这是进行分类查询的基础。 | `type: book` |
+| **状态追踪** | 使用`status`属性来管理笔记的生命周期或项目的进度。 | `status: seedling` (想法) |
+| **建立关联** | 除了使用`[[链接]]`，你还可以用属性来定义更明确的关系。 | `author: [[作者A]]` |
+
+#### 通过Obsidian插件，让你的元数据“活”起来
+
+你精心维护的YAML属性，通过插件可以实现知识的自动化组织与呈现。
+
+| 插件 (Plugin) | 核心功能 (Core Function) | 应用实例 (Application Example) |
+| :--- | :--- | :--- |
+| **Dataview** | 使用简单的查询语言（DQL）从整个知识库中筛选、排序和展示笔记，自动生成动态的笔记列表和表格。 | 创建一个“动态首页”，自动汇总所有 `status: in-progress` 的任务。 |
+| **Bases** | (官方插件) 提供一个可视化的、类似Notion数据库的界面（表格、看板等）来浏览和批量编辑笔记的元数据。 | 以看板视图来管理所有 `type: project` 的笔记，并拖动卡片来改变它们的 `status` 属性。 |
+| **Metadata Menu** | 极大地增强了属性的编辑体验，可以为属性预设可选值或创建依赖关系，实现更高效、规范的元数据录入。 | 为`status`属性设置固定的下拉菜单选项："待办"、"进行中"、"完成"。 |
+
+
+
+
+### 4. YAML的编辑器或格式化工具
+
+
+| 工具                    | 类型           | 主要功能                                                           |
+| ----------------------- | -------------- | ------------------------------------------------------------------ |
+| **VS Code + YAML 插件** | 桌面编辑器     | 语法高亮、自动补全、实时错误校验、代码折叠、格式化。               |
+| **Online YAML Parsers** | 在线工具，例如[YAML Checker - The YAML Syntax Validator](https://yamlchecker.com/)       | 快速验证YAML语法是否正确，进行格式化和美化，适合临时检查。         |
+| **Prettier**            | 代码格式化工具，例如[Prettier · Opinionated Code Formatter · Prettier](https://prettier.io/) | 通过插件支持YAML，可以在项目中统一代码风格，实现保存时自动格式化。 |