标签/角色切换器：格式、规则与示例

标签/角色切换器为多个读者在单一主题范围内提供不同的路径，而无需将它们发送到单独的页面。标签标识路径，选择一个标签会在同一位置显示其面板。只有当各面板是真正的对等内容，且每个面板都保留在页面的初始 HTML 中时，该元素才有用。

渲染状态显示一个活动面板，但其他两个面板也存在于文档对象模型（DOM）中——浏览器对页面的结构化表示。它们使用原生的 hidden 属性隐藏，而不是在点击后才请求。生产环境的渲染器会添加下面描述的键盘和指针行为；作者编写的内容契约在各个平台上保持一致。

为什么这个元素很重要

读者通过自己的角色、目标和责任级别来过滤页面。内容专员可能需要起草说明，SEO 专员可能需要验证规则，而团队领导可能需要治理规范。一个标签清晰的角色切换器可以减少将通用建议转化为"这对我意味着什么"所需的工作量。它还将共同的前提集中在一处，避免了三个几乎重复的页面竞争同一意图。

心理优势在于识别胜于解读。读者识别"SEO 团队"这样的标签，比扫描三段文字推断哪段适用要快得多。标签还保留了空间上下文：面板在原位切换，因此读者可以比较对等路径，无需反复滚动经过共同的引言。

这种便利性带来了机器可提取性方面的权衡。机器可提取性是指爬虫、搜索引擎、辅助技术或检索系统在保留其主题和关系的同时，隔离内容的能力。可见的标题和段落呈现清晰的阅读顺序。标签面板引入了一种交互状态：一个可见，多个不可见，软件必须将每个标签连接到正确的面板。弱实现只在 HTML 中保留活动面板，在点击后加载其他面板，或重复使用"优势"等通用标题而不包含角色名称。在每种情况下，机器接收到的上下文都比读者看到的少。

即使实现正确，与普通章节相比，可提取性也可能降低。有些系统优先处理初始可见文本，扁平化交互关系，或从摘要中省略隐藏内容。因此，标签是一种信息路由工具，而非隐藏关键答案的手段。将共享的答案、定义、警告、资格条件和结论放在标签集之外。在面板中使用针对特定受众的应用、示例、工作流程或证据——这些内容在共同答案已知后仍然有用。

应用元素编写规则 ：首先撰写完整的说明，然后将一组真正的对等读者路径归类为此类型化元素。本页的规则在面板映射、交互和内容限制方面具有优先权。

何时使用

当以下所有条件都成立时，使用标签/角色切换器：

1. 有两到五个可识别的受众、上下文或模式，需要对同一主题进行不同的应用。
2. 每个面板回答相同的问题，深度相当。
3. 大多数读者一次只需要一个面板，少数人可能需要比较两个或更多。
4. 共同答案可以在元素之外陈述，无需读者打开每个标签。
5. 将路径保持在同一页面上比维护内容大量重复的独立页面更清晰。

典型的应用包括"开发者/编辑者/审核者"的实施指南、“个人/团队/机构"的入门路径，以及通过"规划/制作/衡量"解释同一项能力。角色标签应反映工作流程、证据、权限或期望结果方面的实质性差异——而非人口统计猜测。

接近但不适用的情况通常来自于试图缩短页面。不要将顺序步骤放入标签中——将第二步隐藏起来直到读者选择它会破坏流程的顺序。不要将简短的定义列表做成标签，因为普通标题以更少的交互暴露相同信息。不要使用标签进行详细的功能对比：对比表格 能让标准同时可见。不要将标签用作不相关主题之间的导航，也不要仅仅因为页面感觉太长而拆分信息。

当各部分是垂直阅读流中的独立问题，或需要同时保持多个答案打开时，折叠面板 是更好的选择。当每个受众需要不同的搜索意图、标题、证据集、转化路径或超过约 300 字的独特内容时，单独的页面更合适。如果读者需要所有面板才能安全或正确地操作，则标签是错误的选择。

放置位置

将切换器放在共享答案之后、解释为什么路径不同的段落之后。读者应在选择标签之前理解共同主题。在产品或解决方案页面上，这通常意味着放在核心价值主张和共享能力解释之后，但在详细证据和主要结束行动之前。在文档中，将其紧放在它所控制的特定角色说明之前。

不要将标签集放在页面的直接答案、定义或强制性警告之前。不要将其放在主张与其来源之间、先决条件与其所约束的程序之间，或价格与其限定条件之间。即使没有面板被选中，这些关系也必须存在。标签集不能与另一个标签集、折叠面板、大型对比网格或轮播并列；相邻的交互模型会产生冲突的控制和模糊的阅读顺序。

避免嵌套标签。外层选择会隐藏内层选择，造成困难的键盘行为，并使深层链接含义模糊。同样，避免将角色切换器直接放在表单或行动号召中的另一个受众选择器上方。如果两个控件使用相似的标签，读者可能不知道他们是在更改可见内容还是在提交偏好。

结构

该结构包含一个带标签的容器、一个有序的标签列表，以及每个标签对应的一个面板。截图必须同时在 DOM 检查器中显示非活动面板以及可见状态，因为在源代码中的存在是元素的一部分，而不是实现细节。

1. 共享标题： 陈述每个面板都解决的共同问题或任务。
2. 标签列表： 以稳定的作者定义顺序将两到五个对等标签分组。
3. 标签名称： 用读者能够识别的语言命名受众、上下文或模式。
4. 选中状态： 通过文字语义和可见处理（而非仅靠颜色）传达活动标签。
5. 面板： 包含自包含的标题和一个标签的内容。
6. 程序化关系： 标签上的 aria-controls 和面板上的 aria-labelledby 将每对连接起来。
7. 降级顺序： 确保共享标题、标签和所有面板内容在脚本或样式不运行时仍具意义。

间距、边框、指示器形状、动画和断点属于渲染器。作者控制标签、源代码顺序、面板内容和可选的稳定片段标识符。

设计变体

该组件支持四种变体。每种变体使用相同的内容模型和 DOM 要求。

角色标签： 当工作流程、证据或后续行动确实因读者而异时，使用角色标签。优先使用既有的客户语言如"内部团队”，而非虚构的角色名称如"增长大师"。

上下文标签： 使用非角色状态，如团队规模、运营模式或实现方式。共享标题必须指明变化的维度，以免标签被误认为是页面导航。

垂直标签： 仅当标签需要更多水平空间且不超过五个时使用。DOM 和键盘顺序保持为标签一至标签五，后跟其对应的面板，根据选定的无障碍实现方式排列。

窄视口和降级状态： 标签可以在有可见提示表明溢出时水平滚动，或者渲染器可以将面板显示为堆叠的带标签部分。不得将标签截断为含混不清的片段，或从 HTML 中移除非活动内容。

参数

内容契约保持关系明确，同时将视觉和响应行为留给渲染器。

标签是属性，因为它们操作控件；面板标题来自第一个标题，因为它们属于内容。两者可能相似，但简洁的标签可以映射到更完整、可提取的面板标题。面板内容体允许段落、短列表、内联代码、一张图片和一个上下文相关的行动。不允许包含另一个标签集、折叠面板、数据表、表单、视频播放器或多步骤流程。

语法和代码示例

所有三种表示法保持一个标题、有序标签、面板标题、面板内容体、稳定 ID 和初始默认值。可移植的 Markdown 指令是规范化的作者编写形式。

可移植 Markdown 指令

:::tabs-persona-switcher{default=content-teams variant=horizontal}
## 选择您的团队

::item{label="Content teams" id=content-teams}
### 将简报转化为可重复的草稿

从所需的答案、证据和元素集开始。在应用组件之前，先完整地起草推理过程。
::

::item{label="SEO teams" id=seo-teams}
### 验证发现和提取

检查渲染后的 HTML、内部链接、标题和结构化字段。确认每个面板都在初始响应中到达。
::

::item{label="Team leaders" id=team-leaders}
### 审查系统，而非仅看页面

一次性批准共享的承诺，然后审查每个受众在哪些地方确实需要不同的工作流程、证据或后续行动。
::
:::

父级内容体的第一个标题映射到 title。每个嵌套项从属性中获取 label 和 id，将其第一个标题映射到 item.title，其余内容映射到 item.content。

Hugo 短代码

{{< tabs-persona-switcher title="Choose your team" default="content-teams" variant="horizontal" >}}
  {{< tab-item label="Content teams" id="content-teams" title="Turn the brief into a repeatable draft" >}}
  从所需的答案、证据和元素集开始。在应用组件之前，先完整地起草推理过程。
  {{< /tab-item >}}
  {{< tab-item label="SEO teams" id="seo-teams" title="Verify discovery and extraction" >}}
  检查渲染后的 HTML、内部链接、标题和结构化字段。确认每个面板都在初始响应中到达。
  {{< /tab-item >}}
  {{< tab-item label="Team leaders" id="team-leaders" title="Review the system, not just the page" >}}
  一次性批准共享的承诺，然后审查每个受众在哪些地方确实需要不同的工作流程、证据或后续行动。
  {{< /tab-item >}}
{{< /tabs-persona-switcher >}}

适配器仅使用命名参数。它必须在服务器响应期间渲染所有项内容体，拒绝重复的 ID，并在不重写内容模型的情况下初始化交互。

WordPress 区块

<!-- wp:amicited/tabs-persona-switcher {"title":"Choose your team","default":"content-teams","variant":"horizontal"} -->
  <!-- wp:amicited/tab-item {"label":"Content teams","id":"content-teams","title":"Turn the brief into a repeatable draft"} -->
  <p>从所需的答案、证据和元素集开始。在应用组件之前，先完整地起草推理过程。</p>
  <!-- /wp:amicited/tab-item -->
  <!-- wp:amicited/tab-item {"label":"SEO teams","id":"seo-teams","title":"Verify discovery and extraction"} -->
  <p>检查渲染后的 HTML、内部链接、标题和结构化字段。确认每个面板都在初始响应中到达。</p>
  <!-- /wp:amicited/tab-item -->
  <!-- wp:amicited/tab-item {"label":"Team leaders","id":"team-leaders","title":"Review the system, not just the page"} -->
  <p>一次性批准共享的承诺，然后审查每个受众在哪些地方确实需要不同的工作流程、证据或后续行动。</p>
  <!-- /wp:amicited/tab-item -->
<!-- /wp:amicited/tabs-persona-switcher -->

WordPress 应将内部区块限制为已注册的标签项。预览、保存的标记和前端渲染必须保留每个面板；编辑器的便利性不得将非活动项转换为客户端获取的内容。

示例

好的示例

选择实施路径

托管平台——无需维护基础设施即可启动

连接经批准的数据源，配置角色，并在暂存工作区中验证输出。供应商维护运行时更新和监控；您的团队负责内容审批和访问审查。

自托管——控制部署和数据边界

在您的环境中部署支持包，连接同一经批准的数据源，并指定负责人进行升级、监控、备份和访问审查。

这个示例有效，因为两个面板回答相同的实施问题，命名了运营差异，并包含相当的责任。“托管平台"和"自托管"是易于识别的标签。如果两个面板被扁平化为源代码顺序，共享决策仍然清晰。

差的示例

探索一切

概述： 我们的平台让现代团队更高效。

定价： 联系销售获取个性化报价和重要合同条件。

安全： 阅读我们的安全文档。

招聘： 加入我们不断壮大的团队。

这是伪装成标签的网站导航。各面板不回答同一个共享问题，标签混合了买家信息和企业内容，重要的定价条件隐藏在交互后面。用普通的页面章节和真实导航替换该集。如果定价选项需要同时评估，请使用定价或对比结构，而不是标签。

结构化标记和无障碍

标签和角色切换器不创建专用的 Schema.org 类型。当页面独立符合条件时，其内容仍属于包含它的 Article、TechArticle、Product 或 WebPage。不要仅仅因为标签重复而将其标记为 ItemList，也不要从角色标签生成多个 Person 实体。“机构"这样的标签描述的是读者路径，而非事实性实体声明。

仅当界面确实表现为标签时才使用 WAI-ARIA 标签模式。容器具有 role="tablist"；每个控件具有 role="tab"、唯一 ID、aria-controls 和准确的 aria-selected 值；每个面板具有 role="tabpanel" 和 aria-labelledby。使用按钮作为控件，不要使用带有虚假目标的链接。选中的标签应位于页面的 Tab 键顺序中；非活动标签使用轮替的 tabindex="-1" 并通过箭头键可达。Home 和 End 移到第一个和最后一个标签。仅当面板切换是即时的时，激活可以跟随焦点；否则 Enter 或 Space 激活焦点所在的标签。

焦点必须保持可预测。选择标签不会自动将焦点推入其面板。当面板的第一个内容不可聚焦时，可以使用 tabindex="0"，允许键盘用户移入其中。可见的焦点指示器和选中指示器必须不同，且两者都不能仅依赖颜色。

所有面板必须在初始 HTML 响应中渲染。使用 hidden、CSS 或渐进增强的等效方式隐藏非活动面板是可以接受的；仅在点击后才创建面板则不行。在没有 JavaScript 的情况下，降级方案必须按源代码顺序显示每个带标签的面板，或提供指向服务器渲染目的地的真实链接。稳定的片段可以激活面板，但规范页面保持为一个 URL。测试缩放、窄屏、长翻译标签、屏幕阅读器关系、键盘顺序和脚本失败。

编写规则

以共享问题开始。如果每个提议的面板回答不同的问题，则不要使用标签。编写两到五个项，首选三到四个。尽可能将标签控制在 1 到 4 个词和 28 个字符以内。使用平行的语法：全部用角色（“编辑者/审核者”）、全部用模式（“托管/自托管”）或全部用阶段（“规划/制作/衡量”）。不要混合角色、动词和营销用语。

为每个面板提供一个 3 到 10 个词的标题，当标签本身不足以说明时，同时命名相关路径及其结果。每个面板写 40 到 180 个词，绝对上限为 300。面板应有相当的深度，但不需要相同的字数。使用直接的语言和具体的任务、证据、权限、约束或行动差异。仅将代词从"你"改为"你的团队"不能证明另一个面板的合理性。

将共同信息保留在元素之外。在每个面板中重复相同的开头句子会造成维护偏差，并使提取的段落看起来重复。将差异放在面板内，并使每个差异足够明确以在提取后仍能理解。优先使用"机构团队可以分配客户级角色”，而不是"你获得更多控制权”——后者在脱离选中的标签后会丢失其主语。

切勿将以下内容放在标签集内：

• 页面唯一的定义、直接答案、结论、安全警告、法律限定、资格规则或来源归属。
• 每个读者都必须完成的顺序步骤，或约束一个面板之外内容的先决条件。
• 另一个标签集、折叠面板、轮播、复杂数据表、多字段表单或自动播放媒体。
• 每个面板超过一个主要行动号召，或通向不相关漏斗阶段的行动。
• 仅在交互后加载的内容，即使加载速度对人类用户来说很快。
• “其他”、“更多”、“通用"或"资源"等标签，这些标签隐藏了未定义的关系。

如果每个面板超过 300 个词、需要自己的证据集或针对不同的搜索意图，请发布专门的章节或页面。如果读者需要同时比较多个标准，请使用表格。如果内容仅是可选细节，根据关系使用散文或折叠面板。

使用该元素的文章类型

postTypes 前置元数据字段是本表的来源。包含在内意味着格式可以支持标签，但并不强制使用标签。

QA 检查清单

• 一个共享问题： 每个面板为不同的受众、上下文或模式回答相同的限定问题。
• 恰当的数量： 该集包含两到五个标签，最好三到四个，使用简洁平行的标签。
• 可见的共同答案： 定义、核心答案、强制限定和结论保留在标签集之外。
• 初始 DOM 存在： 每个面板及其完整的作者编写内容出现在初始服务器渲染的 HTML 中。
• 明确的上下文： 每个面板标题和开头句子在脱离视觉标签状态提取后仍然可理解。
• 正确的关系： 标签和面板 ID 唯一；aria-controls 和 aria-labelledby 正确配对。
• 键盘行为： 箭头键、Home、End、Enter、Space、Tab 和 Shift+Tab 的行为与选定的激活模型一致。
• 焦点清晰： 焦点和选择视觉上可区分，并且选择不会意外移动焦点。
• 稳定降级： 脚本失败会显示带标签的内容或可用的服务器渲染目的地，不会丢失信息。
• 响应式行为： 标签在窄宽度、200% 缩放以及带有较长翻译文本时保持完整且可发现。
• 安全放置： 组件不会将主张与其证据、警告与其范围、或先决条件与其说明分开。
• 无复杂嵌套： 面板包含受限的散文和简单支撑内容，而非另一个交互系统。
• 结构化数据克制： 渲染器不会从展示标签中发明列表、人物或受众模式。
• 表示法一致： Markdown、Hugo 和 WordPress 保留相同的顺序、ID、默认值、标签、标题和面板内容体。

当非活动内容需要点击触发的网络请求、当关键信息仅存在于一个面板内、或当标签未描述对等路径时，审阅者应拒绝该组件。这些是内容和架构的失败；视觉优化无法修复它们。

常见问题

前置元数据中的结构化 FAQ 条目涵盖了索引、片段 URL、标签数量、行动号召以及标签与折叠面板的区别。它们特意放在交互元素之外，以便每个读者和渲染器接收相同的实施指导。