提示框：何时使用及如何使用

提示框用于突出显示一个可选技巧，使附近的操作更简单、更快速、更清晰或更可靠。它不是装饰性的摘要：读者可以跳过它，仍然正确完成任务。

上面这个实例包含一个想法，出现在它所改善的操作旁边，并解释了好处。正是这三个属性——而不是彩色边框——使其成为提示。

为什么这个元素很重要

读者不会对每个句子投入同等的注意力。在指导性或决策密集型的页面中，他们首先寻找必要路径，然后扫描能让工作更出色的捷径和技巧。提示框为一个异常有用的可选想法提供了一个稳定的边界。标签在读者投入注意力之前就告知他们：“这可以改善你的结果，但不会改变"完成"的标准。”

这种区分降低了认知负荷，即读者在阅读时需要持有和分类的信息量。没有标签，读者必须推断一个旁白是要求、背景还是建议。然而，标签太多，页面就会产生第二条竞争性的阅读路径。因此，稀缺性是该元素功能的一部分：只有当大多数内容没有被框起来时，对比才有效。

机器可提取性是指软件能够隔离一个内容单元并在脱离周围页面的情况下保留其用途的能力。一个带类型的提示为搜索系统、内容迁移工具或AI代理提供了一个有边界的 type、可选的 title 和 body。它可以保留该建议是可选的这一事实，而不是将其扁平化为一个必需步骤。措辞仍需能独立存在：“试试这个"不可提取，因为缺少对象，而"一次只测试一个标题变更，以便结果有合理的原因"在被单独引用时仍然有用。

提示框本身并不是重要性的证据。元素编写规则 要求由含义来决定组件。作者必须先判断该建议是可选的且能改善结果，然后才应用提示的呈现方式。因为页面看起来视觉平面而选择框化，是颠倒了这个过程，只会产生噪音。

何时使用

在以下四个条件全部成立时使用提示：

1. 该建议是可选的：跳过它不会使任务错误、不安全或不完整。
2. 它改善了一个特定的结果，如速度、清晰度、准确性、信心或恢复的容易程度。
3. 它修改的是附近的一条指令、解释或决策，而不是整篇文章。
4. 它的有用程度足以让跳过周围段落的读者希望它被标记出来。

第四个条件是跳过测试。问：“跳过了这段文字的读者会希望这个想法被标记出来吗？“如果诚实回答是否定的，就让这句话留在正文中。如果读者不能安全地跳过它，那它就是一个要求或警告，而不是提示。提示框只在这两种结果之间的狭窄空间中才值得使用。

常见的似是而非的情况包括：

• 一个先决条件，如管理员权限。它应该放在步骤之前，因为没有它任务无法开始。
• 一个成功标准，如"状态必须显示为’已连接’"。它应该放在步骤中，因为它决定了操作是否成功。
• 理解后续章节所需的定义。在正文中定义该术语；不要让必要的理解看起来是可选的。
• 一个支持性事实或引用。将其放在它所支持的主张旁边，保持证据关系清晰。
• 一句善意提醒，如"记住为你的受众写作”。它过于宽泛，无法改变某个具体操作。
• 一个有用但带有显著风险的快捷方式。如果后果可能造成损失或不可逆的改变，应将其声明为警告，即使该快捷方式本身是可选的。

切勿使用提示框来重复旁边段落的内容。重复会消耗读者的注意力，却没有增加决策或技巧。切勿在提示框内放置行动号召（CTA）——即提示注册、购买、联系或进入商业下一步的提示。推广会将目的从实用帮助转变为转化。切勿使用提示来挽救一个未能解释清楚自己的章节。重写该章节使其必要的逻辑清晰，然后再判断是否有任何真正可选的改进需要保留。

提示、说明还是警告？

这三个标签表达的是后果，而不是语气或颜色选择。根据读者忽略它时会发生什么来对内容进行分类。

当前的Hugo组件将警告处理命名为 important；编辑上的含义仍然是警告。不要因为提示的处理方式看起来更友好而将真正的警告弱化为提示。反之，也不要使用警告样式来使可选建议显得紧迫。将警告样式用于提示会让读者学会忽略警告。当真正风险出现时，视觉语言已经失去了可信度。

当分类不明确时，使用后果测试。如果跳过提示框仅仅失去一个改进机会，选择提示。如果跳过它什么也不改变，只是移除了一些上下文，选择说明。如果跳过它可能导致损害、损失、不可逆的操作或无效结果，选择警告，并使后果明确。

放置位置

提示应紧跟在它所修改的完整段落、步骤、产品设置说明或购买标准之后。目标必须足够近，使读者不需要推断二者的联系。当使用自定义标题时，应命名目标操作而不是编造一个口号：“比较年成本"比"专业操作"更清晰。

每个页面最多使用两个提示框，每个章节最多一个。两个是上限，不是配额。一篇文章中有三个提示框意味着没有一个被当作特例来读；将这些内容转化为普通文字或一个简短的子章节。如果两个提示会相邻，保留更强的那一个，将另一个想法融入正文。

不要将提示放置在：

• 标题与解释该标题的开篇段落之间。
• 读者还不了解任务或决策前的起始区域，除非此规范将该元素本身渲染为所需的现场演示。
• 其他标注、表格单元格、FAQ回答、引用或代码块内部。
• 一个主张与它的证据之间，或一条指令与其所需的成功检查之间。
• 直接与警告相邻。可选信息和强制性信息会互相竞争，较低严重性的框会稀释警告的效果。
• 直接与CTA、推广横幅或产品推销相邻。实用建议不应看起来像被该操作赞助。
• 在有序步骤内部，当它使步骤边界不清时。先完成步骤（包括其成功条件），然后将提示放在其下方。

如果一个提示适用于整个章节，将其放在建立相关上下文的第一段之后，并在第一句中指明适用范围。不要将泛泛的提示放在长章节的末尾，期望读者自行推断它改变了前面六个操作中的哪一个。

结构

该元素有三个可见的内容区域和一个文档关系。截图标注了渲染后的区域；解释保持为可选择的实时文本，以便其可选中、可翻译和可访问。

图例说明

1. 类型标签： 可见的"提示"字样。它传达可选状态，必须以文字形式存在，而不是仅靠颜色或图标。
2. 可选标题： 一个简短短语，指明正在改善的操作或决策。省略时，类型标签即为标题。
3. 正文： 一个独立的技术技巧，后跟其实践收益或避免的低效问题。
4. 相邻目标： 框前完整的指令或解释。位置是含义的一部分，尽管它不是文本字段。

边框、背景、图标、间距和排版属于渲染器的工作。作者不在源码中描述颜色或添加表情符号作为替代标签。

设计示例

支持的图库测试的是内容压力和响应行为，而不是不同的含义。每个版本仍然是提示，并遵循相同的编辑限制。

默认： 标签为"提示”，标题省略，正文包含一个简洁的"操作-收益"对。

自定义标题： 标题标识了一个特定的附近决策。即使视觉设计强调自定义标题，提示语义也必须保持可用。

最多两段： 第一段给出技巧，第二段解释收益或边界。这是上限，不是目标。

窄视口： 标签、标题和正文保持阅读顺序、足够的对比度以及舒适的换行，无需水平滚动。

参数

接口区分为语义类型、可选命名、内容和位置。“来源"标识可移植内容模型中值的来源。

在当前Hugo实现中，正文是唯一必须由作者编写的内容。站点渲染器接受位置类型或命名 type，加上一个可选的命名 title。不要在同一个短代码中混用位置参数和命名参数。

语法和代码示例

相同的语义值必须在每个发布系统中保持一致。这些示例使用相同的文案，以便实现测试可以直接比较类型、标题和正文。

可移植Markdown指令

:::tip{title="测试一项变更"}
一次只更改一个变量，这样你可以将结果的变动与特定的编辑联系起来。
:::

指令名提供 type="tip"；属性提供可选标题；包围的Markdown提供正文。

Hugo短代码

{{< callout type="tip" title="测试一项变更" >}}一次只更改一个变量，这样你可以将结果的变动与特定的编辑联系起来。{{< /callout >}}

这仅使用了命名参数。当不需要自定义标题时，位置形式 callout tip 有效，如本页顶部的实例所示。

WordPress区块或短代码

[tip title="测试一项变更"]一次只更改一个变量，这样你可以将结果的变动与特定的编辑联系起来。[/tip]

WordPress实现可以在自定义区块中存储相同的字段。编辑器控件可以改变呈现方式，但不得改变语义类型，也不得使可见标签消失。

示例

这是好的示例，因为建议是可选的、具体的，并且与测试流程相邻。它包含一个想法——记录基准——并准确解释了这如何改善后续解读。读者无需搜索周围页面即可应用。

不好的提示——保护你的工作： 在运行迁移之前备份数据库。如果没有备份而迁移失败，客户记录可能永久丢失。

这是不好的，因为措辞描述的是强制性保障和不可逆的损失。它必须是一个放在迁移之前的警告，而不是一个放在迁移之后的可选提示。友好的类型标签低估了后果。

第二个不好的示例无需渲染：“提示：使用清晰的标题。“如果它旁边已经有一个段落告诉读者使用清晰的标题，它只是在重复那个段落。添加一个具体的可选技巧——比如单独阅读标题以测试它们是否构成有用的提纲——或者删除该框。

第三个失败的示例是一个包含功能宣传和按钮的框：“提示：开始免费试用以自动化此检查。“这是CTA，不是编辑建议。将商业行为放在页面指定的CTA位置，保持提示聚焦于执行。

Schema标记和可访问性

提示框不提供专用的 Schema.org 属性，也没有 TipBox 结构化数据类型。它仍然是包含在 Article、TechArticle、产品页面或其他真实页面级 Schema 中的可见内容。JSON-LD（JavaScript对象表示法链接数据的结构化数据）不得将提示升级为必需的 HowToStep。这样做会将可选建议变为步骤的一部分。

ARIA（可访问的富互联网应用程序标准）在原生HTML表达不足时添加名称、角色和状态。静态提示不需要 role="alert"，因为它既不紧急也非新出现。将其作为带标签的容器以正常文档顺序渲染。如果使用了通用区域角色，将其可访问名称连接到可见标签或标题。不要仅仅为了让屏幕阅读器更强烈地播报该框而添加角色。

标签是内容，不是装饰。它必须出现在文档对象模型（DOM）中，即浏览器和辅助技术读取的结构化树。绿色边框、灯泡图标或背景颜色的变化可以辅助识别，但都不能替代文字"提示”。阅读顺序必须是标签、可选标题，然后正文。链接需要描述性的锚文本，并且组件在文字缩放下和自定义颜色不可用时必须保持可理解。

编写规则

正常长度区间为20–60个词。硬上限为80个词，不超过两个短段落。低于20个词，提示往往变成模糊的口号；高于80个词，它们通常包含多个想法或足够的推理，值得单独设为一个子章节。按含义计数，而不是凑字数：一个精确的14词指令，如果目标和收益都很明确，也是可以接受的。

每个框使用一个想法。一个有用的模式是操作 + 理由：告诉读者尝试什么可选技巧，然后说明它如何改善结果。以动词开头，如"记录"“比较"“预览"或"测试”。使用适合可选建议的平和语言。“必须"“关键"“危险"“绝不"等词语通常表明内容被错误分类了。

提示可以包含普通强调、行内代码和最多一个描述性链接。它绝不能包含：

• 必需步骤、先决条件、验收标准、法律限制或安全条件。
• 多于一个独立建议。
• CTA、按钮、表单、产品卡、优惠券或促销优惠。
• 嵌套的标注、表格、标题、长引用、图片库、视频或多步骤列表。
• 已在相邻段落中陈述过的相同建议。
• 无根据的紧迫性、捏造的统计数据或证据无法与相关文字并列的主张。
• 模糊的口号，如"更聪明地工作"或"创建高质量内容”。

稀缺性是一条编辑规则，不仅仅是一种布局偏好。每页使用零到两个提示框，每章节不超过一个。如果草稿超出限制，对每个框运行跳过测试，保留匆忙的读者最可能后悔错过的那条建议，并将其余部分整合或移除。不要仅仅为了满足数量而将不相关的提示合并到一个框中，这违反了单一想法规则。

使用该元素的文章类型

postTypes 前置数据列出了该元素可能获得使用位置的已注册格式。它并不要求每种类型的每个页面都包含该元素。

教程使用操作指南的约定，因为两种格式都引导读者完成有序任务。购买指南最常使用最佳X-for-Y的约定，因为提示改善的是评估，而不是替代证据。产品设置通常也属于操作指南；产品页面只有在真实设置指导是页面主要内容的一部分时才可能使用提示。

提示框明确不是每篇文章的默认项。新闻、观点、术语表、案例研究和简单的信息型页面通常不需要。不要为了填充模板位置或制造视觉变化而添加提示框。

QA检查清单

发布前，审阅者检查：

• 正确类型： 跳过该建议不会使任务不安全、不正确、不完整或无效。
• 挣得的强调： 浏览了附近段落的读者会真心希望这个想法被标记出来。
• 单一想法： 框内包含一个可选技巧及其收益，而不是一个微缩子章节。
• 稀缺性： 页面不超过两个提示，章节不超过一个。
• 相邻放置： 被改进的完整指令或解释紧邻在框之前。
• 无冲突： 提示不与警告、CTA、推广面板、嵌套标注或竞争性提示相邻。
• 无重复： 正文添加了一个技巧或有用边界，而不是重复附近文字。
• 长度和语气： 正文目标20–60个词，不超过80个词，不使用虚假的紧迫性。
• 可见语义： 文字标签"提示"存在于DOM中；含义不依赖于颜色或图标。
• 提取质量： 标题和正文在脱离周围页面引用时仍然有意义。
• 安全内容： 内部没有必需步骤、风险控制、表格、表单、按钮或嵌套组件。
• 可移植映射： Markdown、Hugo和WordPress表示形式保留相同的类型、标题和正文。
• 参数语法： Hugo使用位置参数或命名参数，绝不混用。

如果框未通过类型或稀缺性检查，更改其颜色不是解决办法。重新分类内容，将其放回主叙述中，或将其删除。

常见问题

前置数据包含本页可发布的常见问题条目。它们强化了审阅者最常需要做出的运营决策：最大数量、语义分类、必需步骤、链接以及页面是否需要提示框。