Home Assistant YAML 风格指南官方文档示例的编写规范与模板实践【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io本篇指南系统讲解 Home Assistant 官方文档中 YAML 示例automation、script、service action、template、configuration 片段的统一编写风格。无论你是文档贡献者、集成开发者还是希望自动化配置保持规范可读的普通用户读完本文都能掌握缩进、布尔值、引号、注释、服务动作target、标量/列表/映射取舍以及模板书写等一整套可落地规则并了解这些规范背后的站点渲染机制。风格规范的目标与适用范围本规范定义在仓库的 .claude/skills/home-assistant-yaml-style/SKILL.md 中适用于 Home Assistant 文档中出现的所有 YAML 示例包括configuration.yaml配置片段automation自动化示例script脚本示例service action calls服务动作调用templates模板trigger / condition 片段其核心目标是让所有文档示例风格统一、可直接复制到真实配置中运行同时尽量简短——只保留教读者某件事所必需的内容。通用 YAML 风格缩进、布尔值与块样式缩进与布尔值缩进统一使用 2 个空格不使用 Tab布尔值一律写作true和false禁止使用yes、no、on、off这类 truthy 写法。YAML 1.1 的兼容布尔值在 Home Assistant 的配置解析环境中容易产生歧义显式布尔值是最稳妥的选择。序列与映射的块样式优先使用块样式block style序列即每个元素单独一行、以-开头块样式序列要缩进在其所属键之下与键值对齐关系清晰避免使用流样式flow style序列即[a, b, c]这种写法。若确需使用逗号后必须有一个空格且开闭方括号内侧不得有空白例如[a, b, c]映射只使用块样式不要使用形如 JSON 的流式映射{key: value}。空值与引号空值采用隐式省略不要显式写出~或null。在 YAML 中键存在但值为空通常直接不写该键或写作key:后留空字符串优先使用双引号具体例外见下文字符串例外一节。长字符串与代码块行宽需要跨行的长字符串优先使用字面量风格literal style|和折叠风格folded style不要堆砌\n转义也不要写超长的单行字符串除非示例确实需要去尾换行strip operator|-、-或保留换行keep operator|、否则优先使用无 chomping 操作符no-chomping的|和围栏代码块内的内容每行不超过 80 个字符便于在窄屏和 diff 中阅读。YAML 注释的编写规范当注释能帮助读者理解示例时才使用注释不为注释而注释注释优先放在其说明的那一行之上而不是行尾注释的缩进要与当前层级保持一致注释以大写字母开头#与注释文本之间留一个空格。example: # Comment one: true从渲染机制看这些代码块在站点构建时会经过 plugins/raw_code_fences.rb 的处理Jekyll 渲染前代码围栏内的{{ }}、{% %}、{# #}等 Liquid 语法会被替换为占位符避免被模板引擎误解析渲染完成后再恢复原文。这意味着文档中 YAML 示例里的模板语法可以安全书写不会与站点本身使用的 Liquid 模板冲突。Home Assistant YAML 示例的内容取舍为了让示例短小精悍、聚焦主题编写示例时应主动省略不必要的内容省略使用默认值的配置项除非该示例专门要讲解这个选项省略空条件例如conditions: []省略mode: single因为它是 automation 的默认模式省略空的data段例如data: {}YAML 参数中的文本内容必须遵循文档书写风格例如title参数的内容应使用句子式大小写sentence-style capitalization而不是标题式大小写除明确说明外所有示例都应格式化为可直接放进configuration.yaml的内容需要读者替换的值用大写字母加下划线标识例如api_key: YOUR_API_KEY或api_key: REPLACE_ME让读者一眼看出哪里需要改动。这一少即是多的原则与站点上配置变量的渲染逻辑相互印证在 plugins/configuration.rb 中每个配置键都必须声明type、description可选布尔值必须给出default否则构建时会抛出ArgumentError——文档追求精确到每个键都有明确类型与默认值示例正文则追求只保留教学所需的最小集。字符串例外哪些值可以不加引号字符串优先使用双引号但以下值类型可以保持不加引号因为不加引号能显著提升可读性实体 ID例如binary_sensor.motion实体属性例如temperature设备 IDdevice ID区域 IDarea ID平台类型例如light或switch条件类型例如numeric_state或state触发器类型例如state或time动作名称例如light.turn_on设备类别device class例如problem或motion事件名称只接受有限硬编码取值集合的值例如 automation 中的modeactions: - action: notify.frenck data: message: Hi there! - action: light.turn_on target: entity_id: light.office_desk area_id: living_room data: transition: 10注意上面示例中notify.frenck、light.turn_on、light.office_desk、living_room均不加引号而人类可读的文本Hi there!和数值10保持了最清晰的写法——不加引号的值全部是系统内部标识符或受限枚举不存在被 YAML 解析器误解的风险。服务动作目标优先使用 target服务动作目标service action target用于指定实体 ID、区域 ID 和设备 ID是 Home Assistant 最新、最灵活的定位方式文档示例中应优先使用。actions: - action: light.turn_on target: entity_id: light.living_room - action: light.turn_on target: area_id: living_room - action: light.turn_on target: area_id: living_room entity_id: light.office_desk device_id: 21349287492398472398关键规则target下可以组合使用entity_id、area_id、device_id三者可同时出现语义为取并集当target可用时不要把实体 ID 放在 action 层级如entity_id:直接作为动作的子键也不要把实体 ID 塞进data中。这条规则也体现在仓库的自动化文档示例中例如 source/_actions/light.turn_on.markdown 这类动作参考页均以target为标准写法。文档站点通过 plugins/options_yaml.rb 为 action、trigger、condition 页面渲染 YAML 受众的选项块它复用了ConfigurationBlock的config-vars布局、类型链接与 Required/Optional 徽章渲染——target作为动作核心参数正是通过这些页面向用户呈现的。标量、列表与映射的正确姿势单值 vs 多值对于接受单个标量或标量列表的属性不要把多个值写进一个逗号分隔的字符串如果使用列表必须用块样式不要使用只含单个标量元素的列表单个标量值可以直接写。entity_id: light.living_room entity_id: - light.living_room - light.office上面第一行与第二、三行语义等价——单个实体时用标量多个实体时用块样式列表。映射 vs 映射列表对于接受单个映射或映射列表的属性例如condition、action、sequence即使只传单个映射也使用映射列表。统一列表形式让读者能直观地看出这可以有多项也为后续扩展多个条目留下空间。actions: - action: light.turn_on target: entity_id: light.living_roomactions的值是列表列表元素是映射即使只有一条动作也保持这种形态。模板Templates书写规范模板是 Home Assistant YAML 中最容易出错的部分规范给出了五条明确指引如果纯 YAML 就能表达就不要用模板。例如能用condition: numeric_state直接表达的数值比较就不要写condition: template模板本质是字符串必须用双引号包裹模板内部的字符串使用单引号避免过长的单行模板将其拆分成多行以便阅读优先使用简写风格shorthand模板。当简写形式可用时优先于更啰嗦的condition: template完整格式在过滤器管道符两侧加空格|如果可读性受损可以加括号。数值状态条件示例纯 YAML 简写形式conditions: - condition: numeric_state entity_id: sun.sun attribute: elevation below: 4多行模板示例注意 -折叠风格 多行 Jinja 表达式value_template: - {{ is_state(sensor.bedroom_co_status, Ok) and is_state(sensor.kitchen_co_status, Ok) and is_state(sensor.wardrobe_co_status, Ok) }}模板函数优先使用辅助方法而非 states 对象不要直接使用states对象——当对应辅助方法可用时优先使用states()、is_state()、state_attr()、is_state_attr()。这些方法在实体尚未就绪例如 Home Assistant 启动过程中时能安全返回合理结果避免直接访问states对象导致的错误。one: {{ states(sensor.temperature) }} two: {{ state_attr(climate.living_room, temperature) }}这两行的含义分别是读取sensor.temperature的当前状态值以及读取climate.living_room实体的temperature属性。这与仓库 plugins/example.rb 中example标签对 template 类型的处理方式一致——模板示例以language: template渲染其余 action、automation、condition、script、trigger 以language: yaml渲染说明模板与纯 YAML 示例在文档体系中是区分对待的。结合站点渲染机制理解规范的为什么上述风格不是随意约定它与文档站点的构建流水线紧密耦合代码围栏保护如上文所述plugins/raw_code_fences.rb 在 Liquid 渲染前后保护代码块中的模板语法。正因为有这个机制YAML 示例里的{{ }}才能作为教学内容而非待执行模板被展示出来配置变量校验plugins/configuration.rb 在构建时校验每个配置键的类型boolean、string、integer、float、template、map、list等、必填性Required/Optional与默认值。示例规范中省略默认值选项的做法与文档同时提供完整默认值信息的机制互补——正文示例保持精简config-vars区块负责穷尽参数细节示例渲染标签plugins/example.rb 将{% example %}标签中的 action/automation/condition/script/template/trigger 内容渲染为带标签的输入/输出对比块样式上强调可运行的片段这一属性进一步要求示例本身必须符合上述书写规范。常见误区速查错误写法正确写法说明on: yeson: true只使用true/falsecondition: []省略该键省略空条件mode: single省略该键这是默认值data: {}省略data省略空的 data 段entity_id: light.a, light.b块样式列表禁止逗号分隔多值字符串target可用时把实体放data放入target.entity_idtarget 是现代标准写法{{ states.sensor.x.state }}{{ states(sensor.x) }}优先辅助方法启动期更安全~、null隐式省略不写显式空值流式映射{a: 1}块样式映射只用块样式按照本指南编写 YAML 示例可以让文档中的每个片段既符合 Home Assistant 官方规范又能被读者安全复制进自己的configuration.yaml或自动化编辑器中直接运行。对于文档贡献者而言遵守这套风格也是通过站点构建校验类型声明、描述缺失、可选布尔默认值等检查的前提。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考