如何在文档中使用图片、截图和视频

通过格式、无障碍和长期维护方面的指导，在文档中有效地使用截图、GIF 和视频。

视觉媒体可以使复杂的工作流程比纯文本更加清晰——但它伴随着维护成本。你发布的每张截图都是在承诺当界面更改时对其进行更新。每个视频在其展示的流程发生变化时都会过时。

目标不是避免使用媒体，而是有意识地使用它，使其带来的清晰度超过维护它所需的工作量。

​

何时使用媒体

并非每个步骤都需要截图。并非每个概念都需要图表。在添加媒体之前，问问自己内容是否真的因为有了媒体而更清晰，还是简洁的文字和代码示例同样能满足用户的需求。

​

截图

将截图用于难以用文字描述的任务——尤其是以界面为主的工作流程，用户需要在视觉上进行定位，或者不看到界面就无法确定正确的界面元素的情况。

避免在以下情况使用截图：

• 用户不容易误认的简单操作（“点击保存”）
• 频繁更改的内容——设置页面、仪表板和功能丰富的界面维护成本高
• 图片不提供信息的装饰性用途

​

GIF

GIF 适用于简短的循环演示——展示动画、展现多步骤交互，或捕捉一个比逐步描述更容易通过视觉跟随的工作流程。

保持 GIF 简短。超过几秒的文件会变得很大且加载缓慢，而且长 GIF 比用户可以暂停和倒退的短视频更难跟随。

​

视频

将视频用于受益于解说的抽象概念，或者顺序和时间节奏很重要的长工作流程。对于复杂内容，视频比 GIF 更具无障碍性——用户可以暂停、倒退和控制播放速度。

将视频托管在 YouTube 或 Loom 等外部平台上并嵌入它们，而不是直接提供视频文件。视频文件会显著增加页面加载时间。

​

各类媒体的指南

​

文件格式和大小

• 截图和图表使用 PNG。PNG 可以保持锐利的边缘和文字。
• 照片或文件大小很重要的图片使用 WebP。WebP 在质量相当的情况下比 PNG 和 JPEG 更小。
• 仅在需要动画时使用 GIF。对于静态图片，GIF 相比 PNG 没有优势。
• 在将图片添加到仓库之前先进行压缩。Squoosh 等工具可以在不产生可见质量损失的情况下减小文件大小。

​

尺寸

• 保持截图为原始分辨率或缩小——永远不要放大，因为这会导致模糊。
• 文档的标准宽度通常为 800–1200px。更宽的截图会自动缩小，但在移动设备上可能显得很小。
• 将截图紧密裁剪到相关的界面区域。周围的浏览器边框、空白区域和无关元素会分散对你所展示内容的注意力。

​

替代文本

每张图片都需要描述性的替代文本。替代文本使图片对屏幕阅读器用户无障碍可访问，并有助于 SEO。

编写描述图片内容以及其在上下文中重要性的替代文本：

<!-- 描述性且有上下文 -->
![API 密钥设置页面，显示三个活跃密钥的列表及其创建日期和最后使用时间戳](/images/api-keys-settings.png)

<!-- 没有用处 -->
![设置页面](/images/api-keys-settings.png)

参阅无障碍了解更多关于编写有效替代文本的信息。

​

文件命名

使用描述性的 kebab-case 文件名来表明内容：

api-keys-settings.png       ✓
screenshot-2024-01-15.png   ✗
image1.png                  ✗

描述性的文件名使查找和替换过时的图片更加容易，并对图片 SEO 有一定的贡献。

​

维护

媒体是文档中维护成本最高的部分。一次界面重新设计就可能导致数十张截图同时过时。

以下几种做法可以减轻维护负担：

• 紧密裁剪到相关元素。 仅显示正在讨论的组件的截图比包含导航栏、标题和周围界面的全页截图过时得更慢。
• 避免为频繁更改的内容使用截图。 如果一个设置页面每个季度都有界面更改，请考虑描述性文字是否比截图更容易维护。
• 保留源文件。 尽可能存储未压缩的原始文件或分层文件，这样截图可以在不需要重新截取的情况下进行更新。
• 记录每张图片展示的内容。 在 MDX 中添加注释或在共享的图片清单中注明图片描述的内容，可以在审查期间更快地识别过时的资源。

​

常见问题

分步说明应该使用截图还是文字？

优先使用文字，将截图作为补充而非替代。文字更快速浏览、更容易搜索、更新成本更低。当用户需要在界面中直观地识别某些内容，或者工作流程在没有视觉参考的情况下确实令人困惑时，再添加截图。一种常见的模式是用文字描述步骤，仅在视觉定位很重要的步骤中包含截图。

界面更新时如何处理截图？

最快的方法是重新截取发生变化的特定截图，而不是一次性批量更新所有内容。紧密裁剪且聚焦于单个元素的截图比全页截图更改频率更低。当重大界面重新设计发布时，将截图更新视为一个有明确范围的文档冲刺，而不是一个持续的干扰。

使用 GIF 和短视频有什么区别？

GIF 自动循环播放，不需要用户交互，并且可以在页面中直接嵌入而无需播放器。它们适用于循环有用的简短交互。短视频更适合超过几秒的内容、受益于音频的内容，或者足够复杂以至于用户需要暂停和参考特定帧的工作流程。视频还具有更好的无障碍支持——GIF 没有暂停控制，除了周围内容中的描述外，也没有替代文本的等效方式。

如果图片是装饰性的，还需要替代文本吗？

如果图片不提供任何信息——纯粹的装饰性分隔符或背景元素——使用空的 alt 属性（alt=""）告诉屏幕阅读器跳过它。但文档中的大多数图片是信息性的，而非装饰性的。如有疑问，请编写替代文本。