mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
e72b4fb295
Generated-By: mintlify-agent Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
132 lines
6.7 KiB
Plaintext
132 lines
6.7 KiB
Plaintext
---
|
||
title: "如何在文档中使用图片、截图和视频"
|
||
sidebarTitle: "媒体"
|
||
description: "了解何时以及如何在文档中使用截图、GIF 和视频，包括格式选择、替代文本和长期维护方面的指导。"
|
||
keywords: ["文档图片", "截图", "文档视频", "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
|
||
<!-- 描述性且有上下文 -->
|
||
|
||
|
||
<!-- 没有用处 -->
|
||
|
||
```
|
||
|
||
参阅[无障碍](/zh/guides/accessibility)了解更多关于编写有效替代文本的信息。
|
||
|
||
<div id="file-naming">
|
||
### 文件命名
|
||
</div>
|
||
|
||
使用描述性的 kebab-case 文件名来表明内容：
|
||
|
||
```text
|
||
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>
|