便签框：何时使用及如何使用

便签框用于隔离上下文信息，帮助读者理解附近的内容，但不会改变读者应该做什么、期待什么结果或情况有多严重。

这个渲染示例解决了一个可能的问题，而无需增加额外的步骤。跳过它的读者仍然可以正确使用报表。注意到时间差异的读者则获得了缺失的上下文信息，可以继续操作而无需改变工作流程。

为什么这个元素很重要

读者通过视觉优先级扫描页面。一个有边界的便签框传达的是：“这个上下文可能会解答一个问题，但它不是新的操作指令。” 这个信号降低了分类旁注信息所需的认知努力。读者可以暂时离开主要论点，吸收澄清信息，然后在同一位置返回，而无需担心流程是否发生了变化。

只有当这一承诺始终可靠时，该元素才能发挥作用。如果必要步骤、营销信息、定义、警告和背景信息都使用便签样式，那么标签就失去了帮助作用。读者必须检查每个框来发现其含义，这反而增加了认知负荷——即处理信息所需的心智努力——比普通正文造成的负担更大。

严重性标签也通过重复来塑造行为。当无害的背景信息使用了警告颜色时，读者反复遇到紧急信号却没有实际后果。他们学会了忽略它。下一个真正的警告就要与一连串的虚假警报作斗争。将警告样式误用于便签框，不仅使一个页面显得夸张，更削弱了整个网站的风险语言体系。

对于机器而言，有类型的便签提供了明确的边界和用途。内容迁移工具可以将该块保留为补充上下文，而不是将其合并到操作步骤中。搜索系统或 AI 代理可以提取带有其标签和正文的便签，并将其保持在其所解释的声明之下。这种关系很难从一段仅靠页面特定样式变成蓝色的段落中恢复出来。

可提取性仍然取决于写作。“这可能会看起来不同"在其段落之外是无用的，因为缺少主语。“报表时间戳使用 UTC，而非查看者的本地时间"则是自包含的。元素写作规则 优先：首先根据目的对段落进行分类，然后应用注册的元素。视觉强调永远不能创建语义类型。

何时使用

仅当所有四个条件都满足时才使用便签：

1. 该段落澄清了附近的一个声明、数值、指令、示例或序列。
2. 跳过它不会改变所需操作、预期结果、对主要声明的正确解读或风险等级。
3. 上下文回答了一个合理的读者问题，否则该问题会打断理解。
4. 该段落足够自包含，即使与其标签一起提取也仍然有意义。

好的便签素材包括时区约定、命名别名、正文已暗示的范围边界、版本之间无害的界面差异，或对预期显示状态的解释。例如：“按钮在月度账户上标记为保存，在年度账户上标记为应用；两者提交相同的设置。” 读者的操作和结果不会改变。

“有用的额外信息"这个定义太宽泛了，因此接近但不准确的案例很重要：

• 理解下一段所需的事实应放在主要解释中。将其藏在便签中会让必要的理解看起来是可选的。
• 前提条件应放在操作步骤之前。如果工作需要管理员权限才能开始，则"管理员权限"不是补充上下文。
• 使工作更快或更好的可选技巧应放在提示框 中。提示会改变结果的质量或效率；便签则不会。
• 防止删除、成本、暴露、伤害或无效操作的条件应放在警告框 中。其目的是在伤害发生前改变行为。
• 确立术语含义的正式定义应放在定义元素或主要解释中，而不是便签中。
• 引用应放在其所支持的声明旁边。当声明依赖证据时，证据不是旁注。
• 推广、注册提示或产品推荐是行动号召，而非信息。

当分类不确定时，使用无变化测试：“如果读者了解到这一事实，他们是否必须改变操作、预期、决策或安全响应？” 如果回答是肯定的，则不是便签。如果是否定的，则询问这一事实是否解决了实际的歧义。如果没有，则删除它或将其保留为普通文字，而不是制造强调。

放置位置

将便签紧接在其所澄清的完整内容块之后放置。目标可以是段落、列表项、步骤、表格、代码示例或短序列，但目标必须在便签出现之前就能独立理解。然后便签提供补充上下文，而不会打断目标内容。

当便签适用于整个部分时，将其放置在定义了该部分范围的开篇段落之后。在便签的第一句中指明该范围。当便签适用于操作流程时，仅当没有操作变化时才将其放置在介绍段落之后和第一步之前；否则该内容是前提条件或警告。关于输出的便签应在输出被介绍之后放置，而不是在几个段落之后。

每页最多使用三个便签，每个部分最多使用一个便签。三个是上限。如果多个便签聚集在一个段落周围，说明正文可能缺少解释，或者该素材值得一个专门的子章节。

便签不得放置于：

• 标题与其开篇段落之间。
• 声明与其支持的证据之间。
• 指令与其要求的成功检查之间。
• 直接与提示、警告、行动号召、推广横幅或其他便签相邻。
• 在表格单元格、常见问题解答答案、引言、代码块、折叠面板或其他标注框内部。
• 在英雄区仅为了制造视觉趣味，除非元素规范要求渲染其实时示例。
• 在页面末尾，而其目标内容出现在更早的位置。

如果相邻会导致框的堆叠，则将便签移入正文或重新组织该部分。不要通过将便签改为警告颜色来解决冲突——呈现方式不能修复不清晰的内容关系。

结构组成

渲染后的便签有四个可见或结构区域：

1. 类型标签： 可见文字"便签”，用于标识该块，不依赖颜色或图标。
2. 可选标题： 一个简短、事实性的短语，为上下文命名，如"时区"或"界面标签”。
3. 正文： 一个自包含的澄清说明，以及当有用时，一个将其连接到附近内容的句子。
4. 相邻目标： 正在被澄清的完整块或命名序列。放置位置承载了这一关系，尽管它不是作者编写的文本字段。

边框、背景、图标、间距和字体样式属于渲染器。作者提供意义，而不是颜色指令或装饰符号。

设计示例

支持的变体测试内容和响应式行为。它们不会创建不同的重要性级别。

默认： 渲染器提供"便签”，正文包含一个澄清说明。大多数情况下使用此形式。

自定义标题： 一个事实性标题标识主题。它不增加严重性，也不替换组件的便签语义。

最多两段： 第一段陈述上下文；第二段解决一个边界或无害的例外情况。更长的说明应成为普通内容。

行内引用： 一个行内代码值或描述性链接可澄清目标内容。两者都不应将便签变成文档中的文档。

窄视口： 标签、标题和正文保持其阅读顺序，正常换行，并在没有边框或图标的情况下仍可理解。

参数

内容模型将固定的语义类型、可选命名、正文以及与附近内容的关系分开。“来源"说明作者或渲染器从何处获取该值。

标题是可选的，因为"便签"通常已足够。便携式指令的第一个标题在默认正文规则下可以映射到 title，但对于此元素，简洁的属性形式更为推荐。其他所有内容映射到 body。当前的 Hugo 实现接受位置类型或命名 type，加上可选的命名 title；切勿混合使用位置参数和命名参数。

语法和代码示例

以下形式携带相同的类型、标题和正文。平台呈现可能有所不同，但澄清说明必须保持为便签。

便携式 Markdown 指令

:::note{title="时区"}
报表时间戳使用 UTC。当查看者的本地时区不同时，筛选条件和计算方式不会改变。
:::

指令名称提供类型，属性提供可选标题，包裹的 Markdown 提供正文。

Hugo 短代码

{{< callout type="note" title="时区" >}}报表时间戳使用 UTC。当查看者的本地时区不同时，筛选条件和计算方式不会改变。{{< /callout >}}

此示例仅使用命名参数。没有自定义标题时，位置形式 callout note 也是有效的，渲染器会提供"便签"标签。

WordPress 区块或短代码

<!-- wp:amicited/note {"title":"时区"} -->
<p>报表时间戳使用 UTC。当查看者的本地时区不同时，筛选条件和计算方式不会改变。</p>
<!-- /wp:amicited/note -->

[note title="时区"]报表时间戳使用 UTC。当查看者的本地时区不同时，筛选条件和计算方式不会改变。[/note]

注册区块是首选的 WordPress 实现方式。在该安装明确支持的情况下，短代码也是可接受的；导入系统不得将便签扁平化为警告，也不得从颜色推断不同的类型。

示例

良好示例：无害的界面差异

这是良好示例，因为它回答了一个合理的界面问题，同时保持了相同的操作和结果。它指明了两个标签，说明了每个标签出现的位置，并确认了它们是等价行为。即使从周围的操作流程中提取出来，该便签仍然有意义。

不良示例：伪装成信息的警告

便签——工作区删除： 删除工作区将永久移除其报表。请在继续之前导出所需记录。

这是不良示例，因为后果需要在不可逆操作之前改变行为。平静的措辞和中性的标签并不能使其成为补充信息。它必须是放置在删除控件之前的警告，并明确说明目标、后果和预防措施。

另一个不良便签写道：“导出必须包含所有必需的列。” 这是一个验收标准。将必需的列放在指令或规格表中。第三种情况是：“你可以先筛选导出以节省时间。” 这是可选的、改善结果的建议，因此是提示。正确的分类比视觉多样性更重要。

Schema 标记和无障碍

便签框没有专用的 Schema.org 类型或属性。它作为可见内容保持在包含它的 Article、TechArticle、产品或其他真实的页面级 schema 中。不要为其创建独立的 JSON-LD 对象。当便签澄清一个步骤时，将其与 HowToStep.text 保持分离，除非该澄清对于执行该步骤是必要的；如果必要，则它从一开始就不是可选的便签内容。

静态便签不需要 role="alert"、ARIA 活动区域或强制播报。这些机制用于传达紧急或动态变化，而便签出现在正常的文档顺序中，承载非紧急的上下文信息。激进的播报会错误地表示其重要性，并使辅助技术输出更加嘈杂。

将可见标签作为文本渲染在文档对象模型中，而不是作为背景图像、仅图标提示或 CSS 生成的装饰。如果使用了区域角色，请将其可访问名称连接到可见标签或自定义标题。阅读顺序为标签、可选标题、正文。颜色和图标可以强化类型，但不能作为与提示和警告的唯一区别。

在 200% 文字缩放和窄视口中，正文必须换行而不出现水平滚动。链接需要描述性锚文本，并且必须可以通过键盘访问。行内代码必须在高对比度下保持可读。关键信息不能仅存在于结构组成截图或图标替代文本中。

写作规则

目标15–60 个词。硬性上限为不超过两个短段落，总计 90 个词。更长的段落通常应融入主要解释中；极短的便签往往是一个带有无用上下文的标签。

每个框写一个澄清说明，语气平静且事实性强。在第一句中陈述主题，然后解释无害的差异或边界。优先使用精确措辞，如"时间戳使用 UTC”，而不是会话填充词，如"提醒一下"等。在解释性规则之前给出原因：“已归档的项目在历史报表中仍然可见，因此其合计值可能仍会出现在过去的日期范围内。”

便签可以包含普通强调、最多两个短行内代码值，以及最多一个描述性链接。它绝不能包含：

• 必要步骤、前提条件、验证规则、成功标准或恢复指令。
• 重大风险、不可逆后果、安全条件、法律指示或成本披露。
• 目的在于提高速度、质量、准确性或便利性的可选建议。
• 完整的定义、支持声明所需的证据或来源列表。
• 多于一个独立的澄清说明。
• 表格、代码块、表单、按钮、行动号召、推荐信、推广或嵌套元素。
• 玩笑、危言耸听的语言、装饰性表情符号或诸如"关键"和"危险"之类的词语。

不要为每个便签都加上"重要"标题。重要性不是该元素的用途，这个词会错误地接近警告的严重程度。使用"便签"或一个事实性的主题标题。切勿使用便签来挽救不清晰的文字：首先修复主要解释，然后仅当确实存在补充性歧义时才保留便签。

使用该元素的文章类型

postTypes 前置元数据列出了补充上下文经常出现的格式。使用仍然是可选的；该表格定义了允许的任务和位置，而非必须使用的插槽。

其他文章类型在通过相同的无变化测试时可以使用便签。被列出并不意味着为了视觉节奏而增加一个，而被省略也不意味着可将警告转为便签。

质量检查清单

发布前，请验证每一项：

• 该块澄清了一个附近的段落，且没有改变操作、结果、优先级、解读或风险。
• 上下文回答了一个合理的读者问题，而不是重复目标内容。
• 必需信息仍保留在主要内容中。
• 便签紧接在其完整目标之后，或对于命名序列在范围段落之后。
• 它没有将标题与其引言、声明与证据、或指令与其成功检查分开。
• 没有警告、提示、行动号召、横幅或第二个便签与其直接相邻。
• 页面不超过三个便签，且每个部分不超过一个。
• 正文目标为 15–60 个词，保持在 90 词以下，包含一个澄清说明。
• 可见的文字标签不依赖颜色、边框、图标或图像而存在。
• 文字在其标签被提取但无周围样式时仍然有意义。
• 在页面加载时，该框不使用 alert 角色或活动区域。
• Markdown、Hugo 和 WordPress 映射保留了类型、标题、正文和位置。
• Hugo 参数全部为位置参数或全部为命名参数；绝不混合使用。
• 内部没有不支持的嵌套组件、代码块、表格、表单或推广操作。
• 截图标记请求未来捕获，而不渲染不存在的资源。

常见问题解答

便签、提示和警告之间有什么区别？ 便签仅作澄清，不改变任何内容。提示提供可选的改进建议。警告则通过改变行为来防止伤害、损失、成本、暴露或无效操作。根据跳过该块的后果进行分类，而非根据其颜色。

便签框可以包含必需信息吗？ 不可以。必需信息应放在主要内容中，让每位读者按顺序阅读。便签可以解释无害的差异，但跳过它不能使任务或解读变得不正确。

一个页面应包含多少个便签框？ 每页最多使用三个，每部分最多一个。大多数页面需要的更少。重复的便签表明主要解释需要重新组织。

便签框应使用警告颜色或 alert 角色吗？ 不可以。警告呈现方式传达实质性后果，而 role="alert" 传达紧急的动态信息。将任何一种应用于常规上下文都会训练人们忽略真正的信号，并误导辅助技术用户。

便签框可以包含链接或代码吗？ 当它们直接澄清目标时，可包含一个描述性链接或最多两个短行内代码值。代码块、表格、表单或多步骤文档应使用主要内容。

便签通过解决真正的歧义来赢得其边界，同时保持读者的操作方向不变。保持其语气平静、位置相邻、内容自包含，并在视觉上与建议和风险区分开来。