带注释的截图：规则与示例

带注释的截图展示真实的界面状态，并标识读者需要注意的精确区域。图像上带有编号标记；页面上带有匹配的文本图例。这种分离就是该元素的核心：既不是未标记的产品图片，也不是嵌入像素中的标签——两者都不符合约定。

内容新鲜度审计，已过滤至一个跟踪的URL。

1. 跟踪的URL： 确认审查适用于目标页面而非整个域名。
2. 状态过滤器： 将表格缩小至需要编辑决策的页面。
3. 结果日期： 显示底层审计记录的最后刷新时间。

截图尚未生成，因此注释是生产截图规范而非破损的图像引用。资产就绪后，图像、标题和编号图例会作为一个语义图形整体呈现。

为什么该元素很重要

读者使用产品图像来回答一个空间性问题：“这个指令指的是哪个控件、值或状态？“密集的界面包含导航、筛选器、标签、数据、徽章和操作按钮，它们看起来可能同样重要。未注释的截图 要求读者反向工程作者的注意力。编号标记将这种搜索简化为可见位置与简短说明之间的直接匹配。

该元素还替代了脆弱的坐标语言。“使用右侧的控件"在工具栏换行时就会出错；而"选择标记为2的状态过滤器"在截图有效期内始终保持可用。

机器可提取性意味着软件可以隔离并复用内容单元的有用含义。计算机视觉可能识别界面文本，但无法可靠推断二十个控件中哪一个对该流程重要。可见且有序的图例创建了标记到说明的显式配对，搜索系统、翻译工具、无障碍软件和内容审计都可以作为文本处理这些配对。图像提供空间证据；图例提供可搜索的含义。这遵循更广泛的元素写作规则 ：即使渲染器发生变化，内容仍保持类型化和可移植。

切勿将图例嵌入像素中。像素文本无法翻译、搜索、选中或在不编辑图像的情况下修正。它对屏幕阅读器（一种向无法看到屏幕的人宣布数字内容的软件）也不可见。只有标记编号属于图像本身。

何时使用

当读者必须在真实界面中识别特定区域，而仅凭文字留下了不止一个可能目标时，使用带注释的截图。当两个控件名称相似、重要状态不明显、结果需要在上下文中解读、或视觉配置无法用文字准确表达时，必须使用该元素。当产品页面做出具体的界面声明而图像可以证明时，该元素也很有用。

当指令已经命名了一个唯一的可见控件且交互方式常规时，截图是可选的。“选择保存更改“在页面只有一个此类按钮时通常不需要图像。如果同一屏幕上有保存草稿、保存视图和保存更改，而选错会改变结果时，则截图成为必需。

当截图增加了负担却没有消除不确定性时，它是有害的。不要为了装饰或重复表格中更清晰的内容而添加截图。一份十四步指南中的十四个截图会产生十四次中断、移动端缩放问题和过时的资产。仅对模棱两可的步骤进行截图；让精确的动词承载常规步骤。

接近但不正确的做法包括：

• 用整个仪表板解释一个图标： 裁剪到能保持方向感的最小区域。在宽界面中迷失的标记不会减少搜索工作量。
• 用截图作为数字证据： 在文字或表格中重复关键值。像素不能成为某个声明的唯一可访问副本。
• 菜单位于打开前的截图： 捕获读者需要检查的状态。关闭状态证明了产品的存在，但不足以证明选择哪个选项。
• 包含客户记录的截图： 在截图前用稳定的演示数据替换。模糊处理容易被遗漏。
• 伪装成截图的关系图： 对抽象关系使用关系图。界面真实感仅在界面本身重要时才有帮助。

放置位置

将图形放在首先要求读者检查界面的段落或步骤之后。在流程中，将其放在操作之后、成功状态或故障排除之前，这样读者可以在验证结果之前找到控件。

保持图像、标题和图例在一起。标题可以引入该组，但其他段落、提示框、广告或分页符不得将截图与其编号说明分开。标题标识整个屏幕和上下文；它不承载属于正文的指令，也不替代图例。

不要将两个全宽截图相邻放置。插入区分它们的说明，或者当两个状态需要一起评估时创建一个带有标签的对比图。保持截图远离无关的行动呼吁、密集表格和图库。

仅当每次出现回答不同的空间性问题时才重复该元素。优先使用一个聚焦的图形；否则给不同的裁剪区域分配不同的文件名和用途。

组成部分

组成部分截图展示一个完整元素的可见和文本部分。解释性标签保留在渲染后的图例中，而不是成为源图像的一部分。

渲染后的图例

1. 上下文边界： 包含足够的周围界面以识别页面和位置，但排除无关的导航和空白区域。
2. 编号标记： 使用高对比度圆形和整数（而不仅仅是颜色）将区域与其图例条目连接起来。
3. 目标区域： 标记说明所需的最小完整控件、值或状态；绝不覆盖目标标签。
4. 方向基准： 保留一个稳定的标题、标签页或面板标签，使读者能够在实际产品中找到相同区域。
5. 标题： 在图像下方的可见文本中命名屏幕、状态和场景。
6. 图例： 使用有序列表，其编号与标记完全匹配，条目说明重要性而不仅仅是外观。

标记编号从1开始，按图例顺序排列。每张图像使用两到六个标记；一个适合困难的目标，而超过六个通常意味着截图过宽。

设计变体

支持的变体更改裁剪和视口，而非注释策略。每个变体都使用演示数据、编号图像标记、外部文本图例和可见标题。

聚焦控件： 适用于单个模棱两可的操作。保留一个方向标签，使裁剪不会成为匿名矩形。

工作流状态： 当输入、状态和结果之间的关系重要时使用。保持无关的全局导航在画面之外。

URL在上下文中： 唯一包含浏览器chrome的标准变体，即浏览器自身的标签页、地址栏和控件。仅包含地址栏和必要的权限或安全指示器。

移动端状态： 当交互在移动端宽度发生变化时，捕获实际的窄布局。不要缩小宽屏桌面屏幕并称其为移动端示例。

参数

参数构成可移植的内容约定。视觉值如标记颜色、边框粗细和标题排版属于渲染器，不是作者字段。

screenId独立于文件名标识产品界面，因此一个版本可以找到content-freshness-audit的不同裁剪。alt.yaml文件保持简单：一个文件名后跟一个折叠的alt文本字符串。

语法和代码示例

每种表示法都保留相同的元数据、标题、标记以及图像—标题—图例阅读顺序。

可移植 Markdown 指令

:::annotated-screenshot{src="/images/seo-playbook/elements/annotated-screenshot/workflow-state.webp" viewport=1440 density="2x" screenId="content-freshness-audit" captureDate="2026-08-27"}
内容新鲜度审计，已过滤至一个跟踪的URL。

1. **跟踪的URL：** 确认审计评估的是哪个页面。
2. **状态过滤器：** 将结果限制为等待审核的页面。
3. **结果日期：** 显示审计数据的刷新时间。
:::

适配器从文件夹的alt.yaml中解析alt。缺少文件名键是发布失败，而非复制标题的许可。

Hugo shortcode 映射

{{< annotated-screenshot src="/images/seo-playbook/elements/annotated-screenshot/workflow-state.webp" viewport="1440" density="2x" screenId="content-freshness-audit" captureDate="2026-08-27" >}}
内容新鲜度审计，已过滤至一个跟踪的URL。

1. **跟踪的URL：** 确认审计评估的是哪个页面。
2. **状态过滤器：** 将结果限制为等待审核的页面。
3. **结果日期：** 显示审计数据的刷新时间。
{{< /annotated-screenshot >}}

这是一个适配器约定，而非已注册的shortcode。在批准的渲染器和资产存在之前，使用已建立的语义图形管线或保留规定的捕获注释。不要使用会丢弃图例或时效性字段的渲染器替代。

WordPress 区块或短代码

[annotated_screenshot src="workflow-state.webp" viewport="1440" density="2x" screen_id="content-freshness-audit" capture_date="2026-08-27"]
[caption]内容新鲜度审计，已过滤至一个跟踪的URL。[/caption]
[marker number="1" label="跟踪的URL"]确认审计评估的是哪个页面。[/marker]
[marker number="2" label="状态过滤器"]将结果限制为等待审核的页面。[/marker]
[marker number="3" label="结果日期"]显示审计数据的刷新时间。[/marker]
[/annotated_screenshot]

WordPress 区块可以将这些字段作为控件暴露，但它必须将标记描述存储为文本。

示例

好示例：一个模棱两可的状态，三个有用的标记

demo.example/pricing/的内容新鲜度审核。

1. 跟踪的URL： 验证结果属于指令中选定的定价页面。
2. 需要审核： 标识将当前页面从工作队列中移除的确切过滤器。
3. 最后刷新： 防止编辑将旧的审计结果视为当前诊断。

这之所以有效，是因为每个标记都回答一个决策，裁剪保留了方向感，图例解释了像素不可见的后果。演示域名显然非客户数据。

坏示例：带标签的产品海报

坏版本一次解释整个仪表板。八个箭头交错，标签遮挡控件，嵌入的推广信息没有提供任何操作。浏览器书签造成隐私风险，客户名称使审批不确定，没有屏幕标识符支持更新，移动缩放使目标无法辨认。

修复方法是：选择一个任务，使用批准的演示数据，裁剪到相关面板，仅保留必要的标记。将说明移入文本图例，添加上下文相关的替代文本 ，并记录屏幕标识符和日期。

Schema标记和无障碍

带注释的截图没有特定的Schema.org类型。它可以填充Article的image属性或带有准确contentUrl、标题、宽度和高度的ImageObject。不要发明标记属性；保持图例可见。

使用原生图形语义：一个<figure>包含<img>、<figcaption>和有序图例。标题命名整个屏幕和状态。图像的alt属性描述屏幕在此上下文中显示的内容；不应以"截图"开头，因为图像元素本身已经说明了这一点。图例提供详细的编号说明，因此在alt文本中重复所有六个条目会造成冗长重复的宣告。

目标为80–180个字符，上限为250。命名产品区域、状态和标记用途：“内容新鲜度审计，已过滤至一个跟踪的URL，标记位于状态过滤器和最后刷新日期上。“不要转录界面、填充关键词或使用文件名。这种信息型图像通常需要非空的alt文本。

标记编号必须在无色条件下可读。对浅色和深色界面区域都使用高对比度，保持视觉大小一致，不要覆盖标签或值。图例使用正常文档顺序的有序列表；避免使用ARIA（可访问的互联网应用程序富媒体）角色将静态内容变为警报或交互式小部件。只有当测试表明aria-describedby关系能改善导航而不会导致可见图例被两次宣告时，才可选择性使用。

在窄宽度下，响应式设计 必须保持含义。只在标记和目标仍然可读时缩放宽图像；否则提供聚焦裁剪或真正的移动端捕获。切勿导致页面级水平滚动或需要缩放。标题和图例在下方换行。

内容与捕获规则

一致性使截图具有可比性和可替换性。在固定的1440 CSS像素视口和2倍像素密度（常称为Retina密度，即每个CSS像素记录两个设备像素）下捕获桌面产品屏幕。在390 CSS像素和2倍密度下捕获真实的移动端状态。在指南中一致使用批准的产品主题；不要交替使用浅色和深色模式，除非主题差异是主题本身。

仅使用演示数据：不得有真实的姓名、电子邮件地址、域名、账单详情、令牌、提示或结果。在截图前检查侧边栏、最近项目、自动填充、通知和头像。

排除浏览器chrome，除非URL、权限或浏览器控件是重点。隐藏标签页、书签、扩展程序、下载、个人资料和通知。加载完成后捕获；关闭无关的工具提示，仅在必要时显示光标。

将源截图存储在cdn-assets/seo-playbook/elements/annotated-screenshot/下。根据屏幕和状态使用小写kebab-case命名，如freshness-audit-needs-review.webp；切勿使用final、new、v2、个人姓名或日期作为文件名。稳定的名称允许在不重写每个页面的情况下替换资产。正常交付使用WebP格式，当需要在细小界面文字保持清晰时优先使用无损设置。仅当生产管线证明WebP损害文本或透明度时使用PNG。不要对包含精细文本和锐利边缘的UI捕获使用JPEG。

渲染宽度不超过1600 CSS像素；1440像素2倍源可能是2880物理像素。保持宽高比和固有尺寸。优化有助于图片SEO ，但压缩不得模糊文本或标记。

每个资产文件夹包含alt.yaml，每个文件名一条：

freshness-audit-needs-review.webp: >-
  AmICited 内容新鲜度审计，已过滤至一个跟踪的URL，带有审核状态和最后刷新日期的编号标记。

键与文件名完全匹配；值是alt文本，而非标题或图例。禁止使用占位符、股票仪表板和不存在图像引用。待捕获仅使用SCREENSHOT注释和screenshotsPending = true。

时效性与重新截图策略

当所描绘的控件移动或更改名称时，截图会悄然过时。将每次捕获视为注册屏幕的一个视图：screenId将产品变更与资产关联，而捕获日期标识所记录的状态。

当UI变化移动或重命名了标记目标、改变了图例所解释的状态、修改了到达目标所需的导航路径、移除了保留的方向基准，或使旧图像可能导致读者选择错误控件时，触发重新截图。重新截取该屏幕的完整图形集，包括聚焦和移动端变体。颜色令牌变化、间距调整或无关侧边栏的添加不需要自动替换，除非截图现在与实时体验或无障碍标准明显冲突。

当屏幕发生变化时，搜索其screenId，然后搜索其文件夹和文件名以发现遗留使用。替换稳定文件，审查alt.yaml，检查每个受影响的图例。不要重命名替换文件而让旧引用悬空。

产品屏幕所有者通知变更；内容所有者接受替换。使用相同的演示装置、视口、密度和主题重新捕获。在每次实质性页面刷新时审查截图。

使用该元素的文章类型

postTypes前置元数据是已注册的连接。每种类型使用相同的元素约定，但应用不同的要求阈值。

案例研究需要一个额外的边界：要么获得明确的权限以显示真实的客户信息，要么使用明确披露的演示数据重建界面并将其作为工作流说明（而非结果证据）处理。涂改不能替代同意或受控装置。

QA检查清单

审阅者在视觉完善之前检查沟通和维护风险。

• 目的： 图形解决一个空间性歧义或证明一个可见的界面声明。
• 必要性： 常规步骤保持为文本；页面不会默认给每个步骤分配一个截图。
• 真实状态： 截图显示文稿中所讨论的确切打开菜单、选定筛选器、结果或错误。
• 演示数据： 不可见客户、员工、账户、浏览器、令牌、提示或账单信息。
• 截图一致性： 视口、2倍密度、主题、界面状态和浏览器chrome规则符合标准。
• 聚焦裁剪： 保留足够的方向上下文，但无关的界面区域不与目标竞争。
• 标记： 有一到六个连续编号，每个高对比度、清晰可读、不覆盖标签和值。
• 外部图例： 每个标记在页面文本中有一条匹配的有序列表条目；没有图例文字嵌入像素中。
• 标题： 图形有简洁的可见标题，命名其屏幕、状态和场景。
• 替代文本： 文件夹的alt.yaml包含精确的文件名键和目标长度范围内的上下文描述。
• 移动端行为： 目标和标记在无需页面级水平滚动或缩放下保持可读；否则存在聚焦裁剪。
• 文件约定： 路径、小写kebab-case名称、格式、尺寸和固有大小符合交付标准。
• 时效性： screenId和捕获日期已记录，实时UI仍然匹配，所有引用可通过文本搜索找到。
• 可移植性对等： Markdown、Hugo和WordPress表示保留相同的资产、标题、标记顺序和图例措辞。
• 无破损资产： 真实图像路径仅在文件存在后出现；待捕获保持为注释并保持screenshotsPending = true。

FAQ

academy模板渲染存储在此页面[[faq]]前置元数据中的五个已审核问题。它们涵盖截图频率、外部图例、替代文本长度、重新截图触发条件和浏览器chrome例外情况。