注意事项：配对指导规则

注意事项区块将推荐操作与相同范围的错误配对，并解释为何该错误会失败。其价值来自于对比：错误版本揭示了一个诱人的失败模式，而正确版本则为读者提供了可直接替换的方案。

这个渲染示例是生产模型。每一行在同一详细程度上讨论一个主题。“不要"部分指出一个现实的错误及其后果；“要"部分提供可用的修正方案。通过标签而非颜色或图标来传达区别。

为什么这个元素很重要

当读者能够看到规则的边界时，规则更容易被理解。单一的正面指令可能显得抽象：例如"使用具体证据"并不能揭示什么算是过于模糊。单一的负面指令则会产生摩擦：“不要做无依据的主张"告诉读者要避免什么，但未指明下一步该怎么做。将两者放在一起，就把边界转化成了读者可以采取行动的选择。

错误版本之所以具有教育意义，是因为它往往与忙碌的人自然写出的内容相似。展示这种近似错误有助于读者在自己的作品中识别它。理由同样重要。“不要使用模糊语言"要求服从；“不要在没有说明具体测量任务的情况下写’快’，因为读者无法验证或比较"则传授了一种可迁移到新示例中的原则。

对等意味着双方涵盖等价的主题、数量、细节和编辑权重。它可以防止精心打磨的"要"栏与一堆无关的警告并列。读者可以浏览一对，理解对比，然后继续阅读，而无需记住页面其他地方的某个条目。

机器可提取性是指软件在保留内容含义和关系的同时将其分离出来的能力。可见的标题、列表结构和行对齐的配对使搜索系统和答案引擎能够提取诸如"对于价格，请说明方案和日期；避免无日期的数字，因为其范围无法验证"这样的表述。如果两侧包含不相关的项目符号，或者理由仅通过图标暗示，则提取可能保留指令而丢失使其安全的前提条件。

在选择此区块之前，请先遵循元素编写规则 。目的优先于外观。主要警示即时危险的内容仍属于警告；序列仍属于步骤列表；有限的完成检查项仍属于清单。两栏彩色列并不会将这些目的转变为注意事项。

何时使用

当读者需要区分推荐做法与看似合理但后果严重的错误时，使用此元素。这种对比应比单一指令更有效地减少歧义。适合的主题包括编辑标准、实施规范、质量控制、设计行为、数据处理和流程选择。

以下所有条件均应满足：

1. 每个错误都有负责任的替代操作。
2. 避免错误的原因可以用一个短句说明。
3. 各项是独立的指导，而非必须按顺序完成的步骤。
4. 双方可以使用相同的范围和具体程度。

近似情况很常见：

• 优缺点： 优点和局限性评估的是单一选项。注意事项指导的是读者行为。“包含无限项目"是一个优点，而非"要”。
• 警告： 严重或不可逆的后果需要直接突出显示并给出应对措施，而非等重量的对等列。
• 清单： 清单追踪必需工作是否完成。其未勾选状态并不是"不要”。
• 比较表格： 表格根据共同标准评估多个选项。它不规定正确和错误的行为。
• 前后对比： 两个示例可能展示编辑过程，但并未表达可复用的行为规则。仅在对比能教授普遍做法时使用注意事项。
• 任意内部风格： 如果无法解释对读者、系统、合规性或维护性造成的后果，则将该惯例记录为规则，而不是假装另一种做法是错误的。

不要使用此区块来制造对立。“要写得清楚；不要写得不清楚"只是重复了相同的抽象概念，毫无教学意义。错误一方必须足够诱人以便识别，且足够具体以便诊断。

放置位置

将区块放在页面已定义任务、受众以及理解指导所需的任何术语之后。它应位于其所概括的说明或演示之后，或接近章节末尾，作为读者行动前的实用性回顾。

精确的放置规则：

• 在最近的标题中引入一个主题。每一对都必须在该主题下有意义，而无需借用远处段落的范围。
• 将区块放在指导性原则之后、实施清单或下一步操作之前。读者应先理解原因，再验证完成情况。
• 在重复的章节中，使用相同的位置和配对限制。移动区块位置会使跨主题的浏览变得更加困难。
• 在源顺序和视觉布局中保持配对列表在一起。解释性散文可跟随整个区块，而非将其两侧分开。

它不能直接紧邻另一个两列决策元素，因为相邻的网格会模糊哪些标签和行属于一起。不要在"要"和"不要"两侧之间放置推荐语、推广横幅、表单或行动号召。当规则依赖于读者尚未获得的术语或上下文时，不要将其作为页面上第一个有意义的内容。

结构

渲染图例

1. 主题标题： 指定每对共享的有边界任务或决策。
2. “要"标签： 标识推荐行为的可见文本；图标或绿色处理为补充信息。
3. “不要"标签： 标识需避免行为的可见文本；标点使用本地化的编辑形式。
4. 操作说明： 一个祈使句或陈述句指令，说明可观察的行为。
5. 理由： 将指令与后果、失败模式或指导性原则相关联的一句话。
6. 配对关系： 源顺序和布局保持了哪个"要"对应哪个"不要”。
7. 可选的来源说明： 标识管控事实要求的政策、测试、法规或证据。

作者提供主题、配对和理由。渲染器提供均等的呈现、响应式堆叠、无障碍标签以及适当时的装饰性图标。

设计示例

以下变体是完整的受支持集合。它们改变密度和排列方式，从未改变对等性或推理约定。

标准配对行

在宽屏上使用三到七组水平对齐的行。每行包含一个关于同一主题的"要"和一个"不要”。

移动端堆叠配对

在窄宽度下，保持每对在一起：“要”、“不要”，然后下一对。将所有正面项目堆叠在所有负面项目之前会隐藏对应关系。

示例引导变体

当具体语言、标记或界面行为比抽象指令更有用时使用。每侧显示一个简短示例及其理由。代码保持为可选择文本。

紧凑回顾变体

仅在管控理由已在紧邻上方解释过时使用。理由仍出现在每个项目中，但采用短短语而非独立段落的形式。

不要创建仅图标、轮播、标签或可独立折叠的变体。它们会将配对分离、隐藏一侧内容，或使比较依赖交互操作。

参数

该合约将配对建模为成对记录而非两个无关的列表。“来源"描述渲染器从何处获取每个值。

正文中的第一个标题映射到 heading。每个嵌套的 pair 拥有两个操作和两个理由。源模型不得将所有正面项目与所有负面项目分开存储，因为那样会使行的对应关系依赖于数组位置，在编辑过程中容易被破坏。

语法和代码示例

所有三种格式保留相同的主题、配对顺序、操作和理由。它们不会从操作中推断理由，也不会自动创建正面项目。

可移植 Markdown 指令

:::dos-and-donts
## 撰写对比声明

::item{do="说明确切方案和日期" dont="不要发布无日期价格"}
### 要
商业事实会变化，因此明确范围能让读者验证并复用该声明。

### 不要
读者无法判断无日期的数据描述的是哪个方案或时期。
::

::item{do="在同一标准上比较两个产品" dont="不要比较不相关的能力"}
### 要
共同的衡量标准使差异具有意义。

### 不要
不同的标准制造了比较的表象，却没有提供有效的选择依据。
::
:::

此元素覆盖了默认的项目映射：父级标题提供 heading；项目属性提供操作；第一个"要"和"不要"子标题将其后续文本映射到两个理由。

Hugo 短代码

目前没有正式的生产级 Hugo 短代码实现了配对记录合约。在存在之前，请像现场示例那样渲染语义化的 HTML，而不是使用两个无关的列表辅助工具。预期的适配器是：

{{< dos-and-donts >}}
## 撰写对比声明

{{< do-dont-pair do="说明确切方案和日期" dont="不要发布无日期价格" >}}
### 要
商业事实会变化，因此明确范围能让读者验证并复用该声明。
### 不要
读者无法判断无日期的数据描述的是哪个方案或时期。
{{< /do-dont-pair >}}
{{< /dos-and-donts >}}

未来的渲染器必须生成一个带有配对记录列表的标记区域。它不得创建两个数组并通过索引进行 zip 操作。

WordPress 区块或短代码

[dos_and_donts heading="撰写对比声明" variant="standard"]
[pair]
[do action="说明确切方案和日期"]商业事实会变化，因此明确范围能让读者验证并复用该声明。[/do]
[dont action="不要发布无日期价格"]读者无法判断无日期的数据描述的是哪个方案或时期。[/dont]
[/pair]
[pair]
[do action="在同一标准上比较两个产品"]共同的衡量标准使差异具有意义。[/do]
[dont action="不要比较不相关的能力"]不同的标准制造了比较的表象，却没有提供有效的选择依据。[/dont]
[/pair]
[/dos_and_donts]

自定义 WordPress 区块应将每对编辑为一个记录，并在操作或理由缺失时阻止发布。

示例

好：等价、可操作且有理由

每对在每一行中共享一个主题：方案范围、时间窗口和证据状态。两个操作都足够具体，可以在草稿中审查，且每个理由都解释了可能出现的问题。即使确切的价格、产品或时期发生变化，读者也能应用该原则。

差：两个命令堆叠

这样做失败的原因是各列之间无关且不对等。“要准确"没有可观察的完成条件，而"绝不要使用术语"禁止了语言使用，却没有区分必要术语与未加解释的术语。没有一个负面条目说明了后果，空单元格暴露了作者创建了两个列表而非四组配对。

通过选择一个主题，然后编写等价的行来修复此区块。对于术语，配对可以是：“在首次使用时定义必要的专业术语，因为定义能让新手跟上讨论"和"不要用模糊的日常用语替代精确术语，因为替换可能改变含义。“这个修正教授的是判断力，而非强制执行口号。

Schema 标记与无障碍

Schema.org 没有提供通用的 DoAndDont 类型。将可见区块保留在包含它的 Article、TechArticle、HowTo 或其他页面级结构化数据中（当该页面确实符合条件时）。不要将正面项目转换为 HowToStep 记录，除非它们构成有序的操作步骤；也不要仅因为配对包含简短解释就将它们作为 FAQPage 发布。

使用原生的标题和列表。一个外部区域从其主题标题获取无障碍名称。每对应为一条列表项或包含可见的"要"标签和可见的"不要"标签的分组记录。在源顺序中保留每对，以便屏幕阅读器用户能同时听到推荐及其匹配的错误。

颜色和图标是补充性的。绿色不能是"要"的唯一信号，叉号也不能是"不要"的唯一信号。装饰性图标使用空的替代文本或对辅助技术隐藏。不要使静态区块可聚焦。如果示例表格不可避免地需要水平滚动，则应包含并标记滚动区域；生产级组件应改为堆叠配对。

缩写"Don’t"在可见的编辑文案中是可以接受的。代码字段使用 ASCII 安全的 dont，因为撇号会使属性名称复杂化。渲染器本地化标签而不更改存储的操作或理由。

编写规则

在最终确定指令之前先写理由。这迫使作者识别对读者、系统、安全、合规性或维护性造成的后果。如果无法写出合理的理由，则该项禁止可能只是个人偏好而非指导性内容。

使用三到七对。每个操作应描述一个可观察的行为，实际情况下不超过 110 个字符。每侧给予一个理由句子，不超过 180 个字符。该限制保持两侧易于浏览；更长的说明应属于周边的散文字段。

在五个维度上保持对等：

• 主题： 两个操作针对同一决策或工件。
• 层级： 精确的标记规则不能与"写得好"这样的宽泛准则配对。
• 语法： 使用平行的祈使句或平行的陈述句。
• 证据： 对双方应用相同的事实和来源门槛。
• 视觉权重： 任何一侧都不应获得更多的空间、强调、细节或默认可见性。

使用直接、中立的语言。优先使用"不要发布未经核实的价格"而非羞辱性语言，如"只有粗心的作者才会忘记核实价格”。避免讽刺、恐惧和绝对化的措辞，除非该规则确实是绝对的并且其范围已明确说明。

切勿将以下内容放入元素内部：

• 为了填充一侧或强制数量对等而添加的无关提示。
• 没有后果、原则或替代操作的禁止事项。
• 有序操作步骤、复选框、评分、裁决或产品优点和局限性。
• 安全关键警告、法律免责声明、紧急指示或不可逆操作通知。
• 推荐语、长引用、媒体、表单、行动号召、推广按钮或优惠券代码。
• 嵌套的折叠面板、标签页、轮播、比较表或另一个注意事项区块。
• 将个人或群体行为定性为道德失败而非可观察行为的声明。

当要求来自政策、法规、测试或外部标准时，添加附近的来源说明。准确注明规则来源，以便编辑可以重新核查；不要让区块携带冗长的引用工具。

使用此元素的文章类型

postTypes 前置元数据数组驱动此使用矩阵。包含该元素表示在所述条件下该元素可用；并不表示该类型的所有页面都必须使用此区块。

QA 检查清单

• 区块有一个有边界的主题，从其最近的标题即可明确。
• 管控性原则出现在区块之前，因此配对强化而非发明规则。
• 有三到七组完整的配对，且"要"和"不要"操作数量完全相同。
• 每对针对相同的主题、受众、范围和具体程度。
• 每个"不要"指出一个现实的错误并解释其后果或失败模式。
• 每个"要"提供可操作的替代方案并解释其为何有效。
• 没有任何条目只是否定其配对、重复口号或使用循环措辞。
• 操作包含一个行为，并保持在 110 个字符目标附近。
• 理由包含一个句子，并在 180 个字符以内。
• 双方使用平行的语法、证据标准、细节和视觉权重。
• 事实性要求在必要时标明其政策、法规、测试或来源。
• 区块不包含步骤、检查状态、产品权衡、严重警告、推广内容、表单或嵌套的复杂元素。
• 可见文本显示"要"和"不要”；颜色、位置和图标不是唯一信号。
• 响应式输出使每对保持在一起，而非将所有正面项目堆叠在所有负面项目之前。
• 主题标题和配对结构在纯文本以及样式或脚本不可用时仍然可理解。
• 结构化数据仅描述包含页面，不编造注意事项 schema 类型。
• 截图注释在真实资源存在前保持为非渲染的捕获说明。

常见问题

学院模板会渲染此页面 [[faq]] 前置元数据中存储的五个问题。它们涵盖配对完整性、数量对等、理由、结构化数据和条目数量。