> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify-docs-automation-github-pr-review.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 了解何时以及如何在文档中使用截图、GIF 和视频，包括格式选择、替代文本和长期维护方面的指导。

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

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

<div id="when-to-use-media">
  ## 何时使用媒体
</div>

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

<div id="screenshots">
  ### 截图
</div>

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

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

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

<div id="gifs">
  ### GIF
</div>

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

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

<div id="videos">
  ### 视频
</div>

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

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

<div id="guidelines-for-every-media-type">
  ## 各类媒体的指南
</div>

<div id="file-format-and-size">
  ### 文件格式和大小
</div>

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

<div id="dimensions">
  ### 尺寸
</div>

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

<div id="alt-text">
  ### 替代文本
</div>

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

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

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

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

参阅[无障碍](/zh/guides/accessibility)了解更多关于编写有效替代文本的信息。

<div id="file-naming">
  ### 文件命名
</div>

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

```text theme={null}
api-keys-settings.png       ✓
screenshot-2024-01-15.png   ✗
image1.png                  ✗
```

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

<div id="maintenance">
  ## 维护
</div>

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

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

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

<div id="frequently-asked-questions">
  ## 常见问题
</div>

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

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

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

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