清单：编写规则、放置位置与示例

清单是一组有限的独立操作或验证关卡，读者可以标记为未完成或已完成。其可勾选状态是含义的一部分：完成所有必需项目应证明某项命名任务、审查或就绪条件已完成。

此呈现示例具有有限范围、四个简洁操作、可见的未勾选状态和一个完成条件。将同样的文字转换为装饰性项目符号将消除该集合可被完成的承诺。

为何此元素重要

读者使用清单来减轻记忆负担。无需在草稿、浏览器、设计和发布界面之间切换时记住所有要求，他们可以一次检查一个条件并记录进度。有限的边界减少了不确定性：读者知道还剩什么、“完成"意味着什么，以及何时可以安全地继续。

这种心理契约比"这里有一些有用的想法"更有力。复选框邀请承诺，而最后一个未勾选的项目制造了有意的紧张感。因此，该元素必须诚实地对待范围。如果清单遗漏了必需的验证关卡，或包含模糊的愿望如"让页面优秀”，界面就会暗示内容尚未拥有它声称的确定性。

机器可提取性是指搜索引擎、AI 问答系统、辅助技术和发布工具能够隔离每个项目而不丢失其角色或完成模型的能力。类型化清单暴露了命名的集合、稳定的项目边界、初始状态和完成条件。解析器可以区分必需关卡与示例或收益，而 AI 系统可以引用一个自包含的操作并附带清单主题。

在选择组件之前，请遵循元素编写规则 。其优先级规则是语义性的：当一个块的目的在于完成或验证时，即使普通的项目符号可以显示相同的文字，也要使用清单元素。视觉相似性无法保留状态、验证、可访问性或适配器映射。

何时使用

在以下情况下使用清单：集合是有限的，每个项目可以独立通过或失败，并且完成必需项目确立了一个有意义的条件。适用主题包括发布前审查、采购要求、迁移就绪、事件交接、文档完整性、无障碍审查和定期维护检查。

应用三个测试：

1. 状态测试： 每个项目能否明确标记为未完成或已完成？
2. 边界测试： 列表是否包含其声明范围所需的所有检查？
3. 完成测试： 完成必需项目是否能证明一个命名的结果？

如果任何一个答案为"否"，则其他元素可能更准确。常见的近似误用包括：

• 项目符号列表 对事实、选项、示例或属性进行分组。其项目不是任务，集合不会变得"已完成"。
• 步骤列表 编码了依赖顺序。如果将第 4 项移至第 2 项之前可能导致失败，则编号和恢复指导比复选框更重要。
• 功能列表描述产品拥有什么。“支持 CSV 导出"不是一项检查，除非读者正在验证一个所述需求。
• 愿望清单记录偏好，其边界和优先级可能变化。它不应承诺完成。
• 评分卡在量表上评估维度。二进制的勾选状态会丢弃有用的性能程度。
• 冗长流程在每个点击旁放一个复选框会混淆执行与验证。先用步骤解释流程，然后添加一个简短的完成清单。

不要在每个章节末尾将清单用作装饰。重复的未勾选框施加了工作负担，并暗示读者尚未完成，即使内容仅提供了可选建议。

放置位置

放置位置遵循读者可以行动或验证的时刻。先介绍任务、范围和必要的上下文；然后将清单直接放在它所控制的决策之前或其总结的材料之后。

• 将就绪清单放在先决条件之后、不可逆或代价高昂的操作之前。
• 将质量保证清单放在草稿、配置或流程评估之后、审批或发布之前。
• 将购买需求清单放在需求和约束已解释之后、产品入围之前。
• 将定期检查清单放在维护部分内部、紧邻其周期和负责人。
• 将主清单放在专门的清单文章顶部、简短范围陈述之后，然后在下方解释困难项目。

清单不得直接与另一个范围重叠的清单相邻放置；应合并它们，或为每个清单提供独立的标题和完成条件。不得将其置于顺序步骤列表旁边而不说明哪个块是流程、哪个是验证。不得将警告与其后果或所需响应分开、不得中断比较表格、不得位于号召性用语内部。切勿在最后一个项目和完成条件之间放置促销按钮。

结构

标记的区域包括：

1. 范围标题： 命名确切的对象和决策，例如"发布前链接检查”。
2. 说明： 说明完成允许什么或证明了什么。
3. 复选框控件： 以编程方式和视觉方式暴露未完成或已完成的状态。
4. 操作标签： 以具体的动词开头，并且独立可理解。
5. 可选限定词： 提供阈值、位置、负责人或证据要求。
6. 必填指示符： 仅在契约真正允许时区分可选项目。
7. 进度摘要： 在交互变体中报告已完成和总计的必填项目数量。
8. 完成条件： 说明所有必填项目通过时所确立的结果。

文字保持权威性。勾选图标、绿色行或删除线标签可以强化状态，但不能替代原生或程序化的勾选状态。

设计示例

静态编辑清单

对于可打印或参考清单，使用可见的未勾选控件。读者可以复制或打印，但页面不声称保存进度。

交互式进度清单

当读者在会话期间受益于标记进度时使用。公布计数而不移动焦点，并提供清晰的复位操作。

必填与可选清单

仅在可选任务确实不影响完成条件时使用。用文字标记可选项目；切勿仅依赖浅色。

分组清单

对于超过十个总检查项，将工作分为四到十个一组，每组有独立的标题和完成条件。每组独立可理解。

打印状态

打印输出必须保留黑白环境中未完成和已完成的标记，保持标签在其控件旁边，并避免短组跨页分隔。

参数

| title | 纯字符串 | 是 | 2–10 个词；90 个字符 | 无 | 父内容中的第一个标题 | | instruction | 纯文本 | 是 | 1 个句子；30 个词 | “完成所有必填项目。” | 第一个标题后的正文 | | items | 重复项目集合 | 是 | 每组 4–10 个 | 无 | 嵌套项目正文 | | item.label | 纯内联文本 | 是 | 3–12 个词；最多约 80 个字符 | 项目正文中的第一个标题 | 第一个标题 | | item.detail | 受限 Markdown | 否 | 0–1 个句子；140 个字符 | 省略 | 第一个标题后的项目正文 | | item.required | 布尔值 | 否 | true 或 false | true | 项目属性 | | item.checked | 布尔值 | 否 | true 或 false | false | 项目属性；仅限编写示例 | | interactive | 布尔值 | 否 | true 或 false | false | 父属性 | | persist | 枚举 | 否 | none、local 或 account | none | 父属性 | | completion | 纯文本 | 是 | 1 个句子；25 个词 | 无 | 父内容中的最终段落 | | id | 小写标识符 | 条件性 | 页面内唯一；2–8 个连字符词 | 自动生成后固定 | 父属性 |

初始的 checked 值用于已完成的示例、保存的模板或服务器拥有的任务状态。编辑型清单从非勾选状态开始；作者不得仅仅为了制作更美观的截图而预先勾选项目。如果 interactive=false，则 persist 必须为 none。

语法和代码示例

规范映射遵循基础契约中的优先级、正文和嵌套项目规则。父级提供集合行为；每个项目提供一个标签、可选详情和状态字段。

可移植 Markdown 指令

:::checklist{id="pre-publish-links" interactive=true persist=local}
## 发布前链接检查

在审批页面之前完成所有必填项目。

::item
### 打开每个内部链接并确认目标存在
::

::item
### 确认每个锚文本在脱离上下文时能描述其目标
::

::item{required=false}
### 检查可选推广链接上的广告系列参数
::

::item
### 验证每个链接控件的键盘焦点可见
::

当所有必填项目通过且不存在例外情况时完成。
:::

Hugo 短代码

{{< checklist id="pre-publish-links" title="发布前链接检查" interactive="true" persist="local" completion="当所有必填项目通过且不存在例外情况时完成。" >}}
{{< checklist-item >}}打开每个内部链接并确认目标存在。{{< /checklist-item >}}
{{< checklist-item >}}确认每个锚文本在脱离上下文时能描述其目标。{{< /checklist-item >}}
{{< checklist-item required="false" >}}检查可选推广链接上的广告系列参数。{{< /checklist-item >}}
{{< checklist-item >}}验证每个链接控件的键盘焦点可见。{{< /checklist-item >}}
{{< /checklist >}}

这是必需的 Hugo 适配器形态，并不代表仓库已提供该短代码。在注册的渲染器存在之前，请为实际示例使用语义 HTML，而非使用无关样式模仿该组件。

WordPress 块

<!-- wp:amicited/checklist {"id":"pre-publish-links","title":"发布前链接检查","interactive":true,"persist":"local","completion":"当所有必填项目通过且不存在例外情况时完成。"} -->
<!-- wp:amicited/checklist-item -->
<p>打开每个内部链接并确认目标存在。</p>
<!-- /wp:amicited/checklist-item -->
<!-- wp:amicited/checklist-item -->
<p>确认每个锚文本在脱离上下文时能描述其目标。</p>
<!-- /wp:amicited/checklist-item -->
<!-- wp:amicited/checklist-item {"required":false} -->
<p>检查可选推广链接上的广告系列参数。</p>
<!-- /wp:amicited/checklist-item -->
<!-- wp:amicited/checklist-item -->
<p>验证每个链接控件的键盘焦点可见。</p>
<!-- /wp:amicited/checklist-item -->
<!-- /wp:amicited/checklist -->

所有适配器必须保留源顺序、必填状态、可见标签、完成条件以及在脚本不可用时保持未勾选的内容。

示例

好的示例：有限范围的发布检查

• 确认发布版本与已批准的变更记录一致。
• 运行文档化的冒烟测试并附加其结果。
• 验证回滚负责人在发布窗口期间可用。
• 在事件时间线中记录部署时间。

完成条件： 所有四条记录均已存在，且指定的回滚负责人已确认窗口可用。

这是有效的，因为每个项目都以可观察的操作开头、保持在一个发布决策范围内，并具有二进制证据。完成行解释了完整集合证明的内容。

差的示例：空洞的内容列表

• 思考受众。
• 让文章引人入胜。
• 改进 SEO。
• 添加任何其他有帮助的内容。

此示例失败，因为没有一个项目定义了通过条件，“任何其他"使集合变为无限，且勾选框不会证明文章已就绪。将空泛目标替换为可验证的关卡，如"在简报中指定一个主要受众”，或将不可操作的建议移至正文中。

Schema 标记与无障碍

不存在通用的 Schema.org Checklist 类型。除非页面确实描述了一个有序流程且可见内容包含这些步骤，否则不要将独立检查映射到 HowToStep。清单可以作为可见内容存在于 Article、TechArticle、Product 或其他合理的页面类型内部，但其复选框不会创建额外的架构资格。

对于交互状态，使用原生 <input type="checkbox"> 控件，并通过包裹或匹配 for 和 id 值将每个控件与 <label> 关联。不可更改的静态显示不得伪装为可用的控件。在显式非交互示例中使用禁用的复选框，或在表单控件会产生误导的上下文中使用带有文本等效项（如"未勾选"）的列表。

键盘用户必须按源顺序到达每个启用的复选框，使用空格键切换其状态，并看到持续的焦点指示器。勾选后不要移动焦点。如果进度消息更新，通过礼貌的活动区域宣布简明的摘要，如"已完成四个必填项目中的三个"；不要再次宣布整个列表。

已勾选和未勾选状态不仅仅依赖颜色。勾选后保留标签内容，而不是将其替换为"完成"，因为操作必须保持可识别。如果进度持久化，请说明存储范围并提供"重置进度"。有用的内容、必填指示符和完成条件必须在 JavaScript 失败时保留在服务器渲染的 HTML 中。

编写规则

清单项目应保持简洁，因为读者在执行或验证，而非在控件内学习整个主题。在陈述规则之前，用周围的散文解释原因。

• 将一个清单保持在四到十个项目。四个项目即可构成一个有意义的有限集合；超过十个则难以扫描，并表明存在多个阶段。
• 将每个操作保持在约 80 个字符和三到十二个词。短的标签在控件旁仍可用，且无需相邻散文即可提取。
• 以具体的命令式动词开头：确认、打开、比较、记录、测试、附加或验证。避免弱动词，如考虑、记住或思考。
• 给每个项目一个通过条件。“检查标题和链接"可能部分通过，因此将其拆分为两个项目。
• 保持项目独立。如果一个操作解锁下一个操作，请将流程转为步骤，并仅将清单用于最终验证。
• 保持语法和层次并列。不要将"确认法务审批"与"在所有渠道发布广告系列并监控一周"混在一起。
• 当完成状态不直接可见时，指定证据：附加报告、记录时间戳或获取审批人确认。
• 明确标记可选项目，并将其排除在必填进度之外。可选意味着没有它们，完成条件仍然成立。
• 一致使用句子大小写和句末标点。当项目包含限定词时，通常优先使用完整句子。

切勿将以下内容放入清单项目：

• 多个有序子步骤、分支故障排除逻辑或第二个嵌套清单。
• 必须在操作前看到的安全警告、法律免责声明或不可逆后果。
• 一段解释、长引用、推荐语、截图、视频、表单或促销号召性用语。
• 主观评分、开放式目标、无依据的阈值或没有可观察证据的要求。
• 仅标记为"此处"的链接，因为项目必须能在没有周围上下文的情况下存活。

使用清单的文章类型

以下关联由本页面的 postTypes 前置元数据驱动。“必需"表示该文章类型的核心任务依赖于有限的完成模型；“推荐"和"可选"取决于页面主题。

QA 清单

内容与放置

• 标题命名了一个有边界的目标、决策或就绪状态。
• 引言说明了完成必填项目所证明的内容。
• 使用四到十个项目，将更大的工作拆分为命名的组。
• 每个项目保持在约 80 个字符范围内，并以具体动词开头。
• 每个项目有一个可观察的通过条件，并且可以独立勾选。
• 确认重新排序项目不会破坏任务。
• 集合是有限的，并包含其声明范围内的所有必需检查。
• 可选项目已明确标记，并排除在必填进度之外。
• 删除嵌套流程、警告、长篇解释、媒体和推广内容。

完成条件： 集合具有一个有限的目的，每个项目简洁、独立且可验证。

渲染与无障碍

• 完成条件直接出现在最后一个项目之后。
• 启用的控件有关联标签、键盘操作和可见焦点。
• 状态不单独通过颜色、图标、删除线或位置传达。
• 交互式进度无需移动焦点即可工作，并说明任何持久化方式。
• 标签和完成标准在没有 CSS 或 JavaScript 的情况下仍可用。
• 在包含页上保留结构化数据；不要发明 Checklist 架构。
• 在所有三个平台映射中保留相同的字段和顺序。
• 截图注释保留为说明；不引用不存在的图像。

完成条件： 状态、标签、顺序和完成意义在所有支持的渲染路径中均能保持。

常见问题解答

学院模板渲染本页 [[faq]] 前置元数据中已审阅的五个问题。它们涵盖项目数量、与项目符号和步骤的区别、保存状态以及结构化数据。