警告框：何时以及如何使用

警告框在读者执行可能造成实质性损害的操作前将其拦停。它不是一种通用的强调样式。一个可发布的警告必须说明风险、后果以及避免或限制损害的操作。

这个实时元素之所以有效，是因为它指出了可能出现的问题，解释了会丢失什么，并在破坏性操作前给出了安全操作顺序。“删除时请小心"是不够的——它把风险评估推回给了读者，却没有告诉他们谨慎行为具体指什么。

为什么这个元素很重要

警告的存在是为了在损害发生前改变决策。按照指示操作的读者通常专注于达成预期的结果，因此他们可能会略过那些看起来像普通背景的限定说明。一个清晰界定的警告在读者仍有选择的节点打断了这一势头。它创造了一个刻意的停顿，解释了这个停顿为何重要，并提供了安全的下一步操作。

这个元素只有在作者有选择地使用时才对读者心理有益。如果常规建议、轻微不便和不可逆损失都得到同样的处理，读者就会学会忽视这个视觉信号。他们开始跳过它。因此，过度使用恰恰制造了警告本应防止的失败模式：当真正紧要的情况出现时，重要信息被忽视了。语气应当告知，而非恐吓。

机器可提取性意味着软件可以隔离警告并使其含义在周围段落之外得以保留。一个带有文字警告标签和自包含正文的类型化块比隐藏在步骤中的红色句子更容易被识别。风险–后果–操作的结构也能在呈现方式变化时保持完整。自动化发布系统可以在 Markdown、Hugo 和 WordPress 之间移动内容，而无需推断哪个句子描述了风险或读者应该做什么。

在映射元素时请遵循元素编写规则 。颜色、图标、粗体文本或名为"重要"的标题本身并不能创建警告语义。当以纯文本复制或在没有页面视觉样式的情况下阅读时，文字内容必须保持完整。

何时使用

当读者即将做出选择或执行一个具有可预见的实质性后果的操作时，请使用警告。当内容涉及以下任何触发条件时，该元素是强制性的：

• 不可逆操作： 删除、覆盖、发布、提交、关闭账户或其他无法可靠撤销的操作。
• 数据丢失或泄露： 记录可能被擦除、损坏、泄露、传输或无法访问。
• 成本影响： 某项操作会产生费用、续签承诺、消耗付费额度或造成在决策点不明显的成本。
• 安全或健康风险： 遵循、组合或跳过某个指令可能导致伤害、疾病或延误治疗。
• 法律或合规风险： 某项操作可能违反法律、合同、政策、许可证、保留规则、同意要求或受监管的审批流程。

触发条件——而非作者的偏好或可用字数——控制是否包含该元素。如果某一触发条件适用，则不能将警告压缩成模糊的标签、移到普通的免责声明中，或为适应模板而省略。应首先缩短周围的解释内容。

不要对有用的快捷方式、最佳实践、定义、轻微不便、正常前提条件或有明显恢复方法的可逆错误使用警告。这些属于近似情况——在日常语言中可能被视为"重要”，但不需要做出停止决策。将必要的前提条件放在流程中，将可选改进放在提示框中，将常规故障恢复放在其修复的步骤旁边。

不要仅仅因为结果不理想就发出警告。“低质量标题可能会降低点击量"是对效果的说明，而非警告。只有当附近的操作会产生具体的实质性后果时——例如，更改实时网站的 URL 结构而不设置重定向可能会破坏入站链接并删除已编入索引的目标——它才成为警告材料。在这种情况下，应在更改前说明预防措施。

放置位置

警告应紧邻其所涉及的最早操作之前。“操作"包括编号指令、命令、表单提交、购买控件、下载、建议或读者可能执行的决定。将警告框放在足以识别情境的上下文之后，但在第一条可执行指令之前。切勿在操作之后、尾注中或仅在结尾的 FAQ 中揭示风险。

如果一个警告适用于整个序列，请将其放在序列之前并说明其范围：“接下来的三个步骤将替换生产数据库。“不要在每个步骤中重复相同的警告。如果后续步骤引入了不同的风险，请在该步骤之前添加第二个警告。

警告不得直接放在另一个提示框、推广行动号召或装饰性横幅旁边。相邻的框会争夺注意力，并可能使警告看起来像是营销堆栈的一部分。它不得将指令与其必需的输入、声明与其证据、或表标题与表格分开。请添加一个简单的过渡或重新组织该部分，使警告明确限定一个决策。

根据适用政策放置法律性说明文字，但将操作性警告保持在风险操作旁边。仅仅因为存在免责声明而将警告移入页脚，会使其目的失效。

结构

渲染后的元素包含六个语义区域：

1. 严重性标签： 可见文本表明这是一个警告；不能仅通过颜色或图标传达。
2. 具体标题： 指出决策或危险，例如"警告：删除前导出记录”。
3. 风险： 说明什么操作或条件可能出错。
4. 后果： 说明可信的结果以及谁或什么受到影响。
5. 操作： 告诉读者如何在继续前避免、减少、验证或上报风险。
6. 位置关系： 将警告与其所管制的下一步操作关联起来。

图例保持为页面中的实时文本而非嵌入图片中。这样每个标签都可被辅助技术访问，且设计变更不会导致规范不准确。

设计示例

当前库支持一种警告严重级别：Hugo 使用 type="important" 渲染。没有单独的 caution、warning、danger、critical 或 emergency 变体。这种有意为之的简化使作者的编写保持一致，并减少了两位作者为同一后果分配不同颜色的可能性。其代价是组件无法在视觉上区分可挽回的财务损失与即时的身体危险。作者必须通过在标题和后果中陈述严重性来弥补，而非依赖更强的颜色。

因此，示例库测试了一个严重级别在其支持的内容变体下的表现：默认标签、自定义标题、最多两段以及窄视口。这些都是渲染情况，而非不同的严重级别。

不要通过添加 emoji、全大写、重复感叹号、自定义类或不支持的类型值来发明严重级别。如果库后续增加了多个级别，其边界必须基于后果和所需响应，而非基于作者对某段文字的强烈感受。

参数

渲染器只有 type、title 和正文输入。风险、后果和操作是正文中的编辑字段；在此契约中保持其明确性，可防止一个视觉上有效的提示框发布不完整的指导。

标题应以"警告：“开头，除非受监管的词汇要求使用其他明确的严重性词语。正文可以将风险和后果合并到一个句子中，但所有三个任务必须保持可识别。链接可以指向详细的策略或恢复说明，但不能替代即时的安全操作。

语法和代码示例

三种映射方式都使用相同的 type、title 和 body。可移植指令是规范的作者编写形式。Hugo 使用现有的 callout 短代码。WordPress 可以将相同的契约实现为注册块；短代码形式仅在该安装已注册的情况下才可接受。

可移植 Markdown 指令

:::warning{title="警告：删除前导出记录"}
删除工作区会永久移除其存储的报告。请导出必须保留的记录，并在确认删除前核对工作区名称。
:::

Hugo 短代码

{{< callout type="important" title="警告：删除前导出记录" >}}删除工作区会永久移除其存储的报告。请导出必须保留的记录，并在确认删除前核对工作区名称。{{< /callout >}}

请同时使用命名参数。不要将位置参数 important 值与命名参数 title 混合使用。

WordPress 块或短代码

<!-- wp:amicited/warning {"title":"警告：删除前导出记录"} -->
<p>删除工作区会永久移除其存储的报告。请导出必须保留的记录，并在确认删除前核对工作区名称。</p>
<!-- /wp:amicited/warning -->

[warning title="警告：删除前导出记录"]删除工作区会永久移除其存储的报告。请导出必须保留的记录，并在确认删除前核对工作区名称。[/warning]

不同系统的呈现方式可能不同，但文本形式的严重性、风险、后果、操作和操作前位置必须在转换过程中保留。

示例

好示例：付费重新处理与覆盖风险

此示例指出了两个具体风险，说明了两种后果，并提供了防止它们的操作。其语气是事实性的：如果保留的导出提供了恢复途径，它不会声称账户将被毁掉或数据将无法恢复。

坏示例：有风险无指导

坏示例没有指明具体操作，没有描述可信的后果，也没有告诉读者如何安全地进行。“严重"是一个没有依据的严重性声明，而"风险自负"则是转嫁责任而非指导行为。应替换为确切的状态变化、可能丢失或泄露的内容，以及在操作前所需的检查、备份、批准、替代方案或停止条件。

另一种失败是过度危言耸听：“永远不要碰这个设置，否则你的整个网站可能会被毁掉！“即使该设置很重要，这样的措辞也没有限定在可能的后果范围内，并且没有提供安全路径。发现言过其实的读者会忽视以后的警告。

法律与受监管内容

免责声明和警告执行不同的任务。免责声明定义范围、资格、不确定性、专业身份或责任限制。警告在决策点识别可预见的危险，并改变读者接下来应该做的事情。两者不可互相替代。

对于法律、金融、健康、安全、隐私或其他受监管材料，将已批准的免责声明保留在其所需的页面位置，并在任何可能产生风险的特定操作之前添加警告。例如，关于文章仅供教育用途的通用声明并不能消除在指导读者停止处方治疗、传输受监管数据、未经批准发布声明或接受定期费用之前发出警告的必要性。

作者不得在警告内部即兴编造法律结论。使用经负责的主题或合规审核人员批准的措辞，保留任何必需的术语，并给出读者可以实际执行的操作性行动：暂停、获取同意、保留记录、咨询合格的专业人士、使用经批准的渠道或提交审核。当页面可以说明即时的停止条件时，模糊的"请参阅条款"链接是不够的。

Schema 标记与无障碍

警告框没有专用的 Schema 标记 属性，也不应创建独立的 JSON-LD 对象。它保持为包含文章中的可见内容。当它限定一个结构化流程时，其完整文本可以包含在相关步骤的可见指令和对应的 HowToStep.text 中；它不得成为虚假步骤或仅存在于结构化数据中。

可访问的富互联网应用程序（ARIA）角色在原生 HTML 无法提供时，向辅助技术传达界面行为。页面加载时已存在的静态警告应保持在正常的文档顺序中，不需要 role="alert"。警报角色会导致即时播报，仅在交互后动态出现紧急警告时才适用。将其应用于每个静态提示框可能会中断屏幕阅读器用户的浏览，并使常规页面进入变得嘈杂。当前的 Hugo 渲染器输出一个带有标签的 <div>，无 ARIA 角色，这对于静态块在其文本和位置承载含义的情况下是可接受的。

颜色独立性意味着警告在黑白模式、高对比度模式、纯文本导出和屏幕阅读器输出中仍然可识别。使用明确的"警告：“标题并用文字描述严重性：“永久删除”、“开始循环收费”、“可能暴露个人数据"或"需要医疗注意”。不要写"避免红色选项"或依赖图标的替代文本来提供危险信息。

将标题和正文保持在所管制操作之前的阅读顺序中。链接需要描述性的锚文本，键盘访问不得依赖于提示框，且关键指令不能仅出现在截图中。如果未来的交互式组件允许关闭，关闭功能不得在操作仍可用时隐藏强制性的警告。

编写规则

编写一个具体的警告，字数控制在 25–90 词以内，不超过两个短段落。使用 3–9 个词的标题，通常以"警告：“开头。指出触发操作或条件、可信的后果以及安全的响应。将原因放在规则之前：读者在理解规则所预防的内容时，会更可靠地遵守。

使用适当的动词。“永久删除”、“覆盖”、“收费”、“暴露”、“使失效"和"可能导致"描述了机制或结果。“毁灭性的”、“灾难性的”、“恐怖的"和"灾难"通常会夸大其词而非具体说明。当结果取决于上下文时，诚实地表明不确定性，并且永远不要仅仅因为读者遵守了一项预防措施就保证安全。

每个框只处理一个决策点。只有在多个检查都必须发生在那一个操作之前时，才使用短列表；否则使用散文形式。不要在警告内部放置推广文案、益处、推荐语、笑话、装饰性 emoji、不相关的提示、完整流程、对比表、多个标题或行动号召。不要将必需的指令隐藏在链接后面。

切勿使用此框来为无依据的主张保驾护航、恐吓读者购买或制造人为紧迫感。如果操作是必需的，将其保留在主流程中同时在警告中说明预防步骤。该框改变注意力，但并不取代文档的操作性结构。

使用此元素的文章类型

postTypes 前置元数据记录了可预见警告触发条件的注册格式。在每行中，“强制"意味着一旦出现所述的触发条件，作者没有自由裁量权；该元素不能被移除或压缩到风险、后果和操作以下以满足长度目标。

其他文章类型只要出现相同的触发条件，也可以使用警告。该表格定义了重复性、非可选的情况；它不授予对 postTypes 中省略的格式的豁免权。

QA 检查清单

在发布前，请验证以下所有项目：

• 该框指出了创建风险的一个具体操作、条件或决定。
• 后果说明了可能发生的情况以及谁或什么会受到影响，且没有夸大。
• 操作告诉读者如何避免、减少、验证、停止或上报风险。
• 警告出现在第一个受管制操作之前，并明确说明了其范围。
• 没有提示、推广、横幅或第二个警告与之直接竞争。
• 强制性触发条件未被省略或因布局或字数而被压缩。
• important 类型和具体的文字警告标题存在。
• 在没有颜色、图标、图片或周围上下文的情况下，严重性仍然清晰。
• 静态警告未使用不必要的 alert 角色；动态紧急警告已适当播报。
• 任何免责声明保持独立，不替代操作点的指导。
• 受监管的措辞和必需的术语已获得适当的主题审核批准。
• Markdown、Hugo 和 WordPress 映射保留了相同的标题、正文和位置。
• 正文保持在 25–90 词以内，不包含营销语言，且不超过一个必要的链接。
• 截图注释仅命名所需的未来捕获内容；没有渲染不存在的图片路径。

常见问题

每个警告框必须包含什么内容？ 必须包含具体的风险、其可信的后果以及安全操作。缺少任何一项，该元素都是不完整的。

警告框可以放在风险操作之后吗？ 不可以。它必须在读者可以操作之前出现，即使需要对周围的步骤进行重组。

法律免责声明可以替代警告框吗？ 不可以。免责声明定义范围或限制；警告在具体决策点改变行为。受监管页面可能两者都需要。

警告框应该使用 alert 角色吗？ 当页面加载时已经存在，则不需要。将 alert 角色保留给在交互后动态引入的紧急信息。

一个页面可以包含多少个警告框？ 每个不同的决策点使用一个，并合并针对同一目标的警告。如果警告主导了页面，请重组流程或重新考虑是否应该提供该操作。

警告框只有在防止具体损害时才值得其视觉上的突出。冷静地陈述风险、后果和操作，将其放在决策之前，并在每个输出中保留该含义。