如何添加图像、媒体和资产

使用共享资产存储和使用媒体

在添加任何图像或媒体（特别是当演示一种媒体内容是次要的技术时）之前，请检查 mdn/shared-assets 存储库中是否已经存在可以使用的内容。将此存储库视为一个媒体库，您可以浏览它来为示例选择合适的资源，而无需担心存储、部署或许可。

该存储库包含音频、视频、字体、照片、图表和图标等图像，以及 PDF、字幕文件、颜色配置文件等各种文件。如果存储库中没有合适的内容，您可以添加自己的资源以及您要包含的媒体的任何源文件。您可以在 shared-assets 存储库的 HTTP 目录中找到示例。

要在 MDN 页面中使用 shared-assets 存储库中的任何内容，请参阅项目 README 的在文档中使用共享资产部分。

使用矢量格式

通常，如果您要添加图像，尤其是图表，请考虑使用 SVG 等矢量格式，原因如下：

• 作者可以使用任何 IDE 或在线工具直接编辑 SVG。编辑 .png 通常涉及从头开始重新创建资产或使用图像编辑软件，这容易出错并可能引入视觉或压缩伪影。
• SVG 可以被 Git 差异化。相比之下，.png 文件在修改时，整个文件会被作为二进制文件更改进行差异化，因此一个 1MB 的 .png 文件在每次合并提交时（如果被修改）都会使存储库大小增加 1MB。
• 灵活的用户体验。SVG 是矢量格式，因此在任何缩放比例下都不会模糊。

将图像提交到内容存储库

如果共享资产存储库不适合您的用例，您可以将图像添加到内容（en-US 或 translated-content）存储库。要将图像添加到文档中，请将图像文件添加到文档文件夹中，然后使用Markdown 图像语法或等效的 HTML <img> 元素从文档的 index.md 文件中引用图像。

我们来看一个例子。

1. 从 mdn 远程的 main 分支获取最新内容，开始一个新的工作分支。

   bash

   cd ~/path/to/mdn/content
   git checkout main
   git pull mdn main
   # Run "yarn" to make sure dependencies are up-to-date
   yarn
   git checkout -b my-images
   

2. 将图像添加到文档文件夹。例如，我们假设我们要将新图像添加到 files/en-us/web/css 文档中。

   bash

   cd ~/path/to/mdn/content
   cp ../some/path/my-cool-image.png files/en-us/web/css/
   

3. 对每个图像运行 filecheck，如果出现问题可能会报错。有关更多详细信息，请参阅压缩图像部分。

   bash

   yarn filecheck files/en-us/web/css/my-cool-image.png
   

4. 使用 Markdown 图像语法在文档中引用您的图像，在方括号之间提供alt 属性的描述性文本，或者在 files/en-us/web/css/index.md 中包含一个带 alt 属性的 <img> 元素。

   md

   ![My cool image](my-cool-image.png)
   <img src="my-cool-image.png" alt="My cool image" />
   

5. 添加并提交所有已删除、已创建和已修改的文件，并将您的分支推送到您的 fork。

   bash

   git add files/en-us/web/css/my-cool-image.png files/en-us/web/css/index.html
   git commit
   git push -u origin my-images
   

6. 现在您可以创建拉取请求了。

为图像添加替代文本

每个图像，无论是 ![] 还是 <img>，都必须包含 alt 文本。Alt 属性应简短，提供图像传达的所有相关信息。在编写图像描述时，请考虑图像的有价值信息，以及如何将这些信息传达给能够阅读页面内容但无法加载图像的人。

确保图像的替代文本基于其上下文。如果小狗 Fluffy 的照片是 Yuckymeat 狗粮评论旁边的头像，那么 alt="Fluffy" 是合适的。如果同一张照片是 Fluffy 动物救援领养页面的一部分，则图像中传达的信息与潜在狗父母相关，例如 alt="Fluffy，一只短毛三色梗，嘴里叼着一个网球。"。周围的文本可能包含 Fluffy 的大小和品种，因此包含它将是多余的。避免过于详细地描述图像：潜在的父母不需要知道狗是在室内还是室外，或者戴着红色项圈和蓝色牵引绳。

对于屏幕截图，请写下您从图像中学到的东西，不要详细描述屏幕截图的内容，并省略读者不需要或已经知道的信息。例如，如果您正在查看一个关于更改必应设置的页面，如果您有一个必应搜索结果的屏幕截图，请不要包含搜索词或结果数量等，因为这些不是图像的重点。将 alt 限制在当前主题：如何更改必应设置。alt 可能是 alt="设置图标在搜索字段下方的导航栏中。"。不要包含“屏幕截图”或“必应”，因为用户不需要知道它是屏幕截图，并且他们已经在解释更改必应设置的页面上，所以已经知道它是必应。

Markdown 和 HTML 中的语法

![<alt-text>](<url-of-image>)
<img alt="<alt-text>" src="<url-of-image>">

示例

![OpenWebDocs Logo: Carle the book worm](carle.png)
<img alt="OpenWebDocs Logo: Carle the book worm" src="carle.png" />

虽然纯粹装饰性的图像应该有一个空的 alt 属性，但添加到 MDN 文档中的图像应该有一个目的，因此需要一个非空字符串描述。有关 alt 文本的提示，请参阅alt 决策树，了解如何在各种情况下为图像使用 alt 属性。

压缩图像

当您向 MDN Web Docs 页面添加图像时，您应该确保它们尽可能地压缩（在不降低质量的情况下），以节省我们读者的下载大小。事实上，如果您不这样做，我们的 CI 过程将失败，并且构建结果将警告您某些图像过大。

压缩图像的最佳方法是使用内置的压缩工具。您可以使用 filecheck 命令和 --save-compression 选项适当地压缩图像。此选项会尽可能地压缩图像，并用压缩版本替换原始图像。例如：

yarn filecheck files/en-us/web/css/my-cool-image.png --save-compression

将视频添加到 MDN 页面

MDN Web Docs 不是一个视频内容很重的网站，但在某些情况下，视频内容作为文章的一部分使用是有意义的。本文讨论了何时在文章中包含视频是合适的，并提供了关于如何以低成本创建简单但有效的视频的技巧。

有几个反对在技术文档中使用视频内容的论点，特别是对于参考资料和高级指南。其中一些列举如下：

• 视频是线性的。人们在线性阅读在线文档时，不习惯从头到尾阅读。他们是浏览。视频很难浏览——它强迫用户从头到尾地消费内容。
• 视频的信息密度低于文本。观看视频解释某事所需的时间比阅读等效说明所需的时间长。
• 视频文件尺寸大，因此比文本更昂贵，性能也更差。
• 视频存在可访问性问题：它的制作成本通常高于文本，特别是本地化，或使其可供屏幕阅读器用户使用。
• 接着上一点，视频比文本内容更难编辑/更新/维护。

有许多流行的视频网站提供大量的视频教程。MDN Web Docs 不是一个视频驱动的网站，但视频在 MDN Web Docs 中在某些特定上下文中确实有其一席之地。

我们通常在描述某种指令序列或多步骤工作流程时最常用视频，这些工作流程很难用文字简洁地描述：“执行此操作，然后执行彼操作，然后会发生此情况”。当尝试描述跨多个应用程序或窗口并包含可能不容易描述的 GUI 交互的过程时，它特别有用：“现在点击左上角附近看起来有点像鸭子的按钮”。

在这种情况下，通常更有效的方法是直接展示您的意思。

视频内容指南

MDN Web Docs 的视频内容应：

• 简短：尝试将视频时长控制在 30 秒以内，理想情况下是 20 秒以内。这对于读者的注意力而言足够短。
• 简单：尽量使工作流程简单，2-4 个不同的部分。这使得它们更容易理解。
• 无声：音频使视频更具吸引力，但制作起来要耗费更多时间。此外，不得不解释您正在做什么会使视频更长，并增加本地化的成本（财务和时间方面）。

要解释更复杂的内容，您可以使用短视频和屏幕截图的组合，并穿插文本。文本可以帮助强化视频中提出的观点，用户可以根据自己的选择依赖文本或视频。有关一个很好的示例，请参阅使用动画检查器。

此外，您还应该考虑以下提示：

• 视频最终会上传到 YouTube，然后进行嵌入。我们建议为此用途选择 16:9 的宽高比，这样它会填满整个观看帧，并且视频的顶部和底部（或左侧和右侧）不会出现难看的黑边。因此，例如，您可以选择 1024×576、1152×648 或 1280×720 的分辨率。
• 以高清录制视频，以便上传后效果更好。
• 对于开发者工具视频，通常最好选择与页面内容对比鲜明的主题。例如，如果示例网页是浅色主题，则选择深色主题。这样更容易看清发生了什么以及开发者工具从何处开始，页面从何处结束。
• 对于开发者工具视频，尽可能地放大开发者工具，同时仍能显示所有要显示的内容并使其看起来正常。
• 确保您要演示的内容没有被鼠标光标遮挡。
• 考虑配置屏幕录制工具以添加鼠标点击的视觉指示器是否会很有用。

视频工具和软件

您需要一个录制视频的工具。这些工具从免费到昂贵，从简单到复杂不等。如果您已经有创建视频内容的经验，那太好了。如果没有，我们建议您从一个简单的工具开始，如果您开始喜欢创建视频内容并希望创建更有趣的作品，那么再逐步使用更复杂的工具。

下表提供了一些推荐的优秀入门工具：

QuickTime Player 提示

如果您使用的是 macOS，您应该可以使用 QuickTime Player。使用此工具的录制步骤非常简单：

1. 从主菜单中选择文件 > 新建屏幕录制。
2. 在屏幕录制框中，点击录制按钮（红色圆形按钮）。
3. 拖动一个矩形框住您要录制的屏幕区域。
4. 按下开始录制按钮。
5. 执行您要录制的任何操作。
6. 按下停止按钮。
7. 从主菜单中选择文件 > 导出为... > 1080p 以高清保存。

其他资源

• 如何在 ScreenFlow 中向屏幕录制视频添加自定义标注

创建视频的工作流程

以下部分描述了创建视频并将其添加到 MDN Web Docs 文章的一般步骤。

首先，规划您要捕捉的流程：考虑最佳的起始点和结束点。确保桌面背景和您的浏览器配置文件干净整洁。规划浏览器窗口的大小和位置，特别是当您将使用多个窗口时。

仔细规划您实际要录制的内容，并在录制前练习几次这些步骤。

• 不要在一个过程的中间开始视频——考虑观看者是否有足够的上下文来理解您的操作。例如，在一个简短的 DevTools 视频中，最好从打开 DevTools 开始，让观看者熟悉环境。

• 考虑您的动作是什么，放慢速度，使其明显。每当您需要执行一个动作（例如，点击一个图标）时，请放慢速度，使其明显。例如：

  • 将鼠标移到图标上。
  • 突出显示或放大（并非总是，取决于是否需要）。
  • 暂停片刻。
  • 点击图标。

• 规划要显示的 UI 部分的缩放级别。并非所有人都能够以高清观看您的视频。您可以在后期制作中放大特定部分，但最好事先也放大应用程序。

录制

录制要展示的工作流程时，请流畅、稳定地执行流程。在关键时刻暂停一到两秒——例如，当您即将点击一个按钮时。确保鼠标指针不会遮挡对您要演示的内容重要的任何图标或文本。

请记住在结束时暂停一到两秒，以展示流程的结果。

后期处理

您可以在后期制作中突出显示关键时刻。亮点可以包含几个通常组合在一起的内容，例如：

• 放大屏幕的某些部分。
• 淡化背景。

突出显示工作流程的关键时刻，特别是细节难以看清的地方：例如，点击某个图标或输入某个 URL。目标是让突出显示持续 1-2 秒。最好在突出显示的开始和结束时添加一个短暂的过渡（200-300 毫秒）。

这里要有所克制：不要让视频不断地放大和缩小，否则观看者会感到晕眩。如果需要，将视频裁剪为所需的宽高比。

上传和嵌入视频

视频目前必须上传到 YouTube 才能在 MDN Web Docs 上显示，例如上传到 mozhacks 频道。如果您没有合适的地方放置视频，请联系 MDN Web Docs 团队成员上传视频。

嵌入

上传后，您可以使用 EmbedYouTube 宏将视频嵌入页面。方法是将其插入到页面中您希望视频出现的位置：

{{EmbedYouTube("you-tube-url-slug")}}

宏调用所需的唯一属性是视频 URL 末尾的字符串，而不是整个 URL。例如，如果视频 URL 是 https://www.youtube.com/watch?v=ELS2OOUvxIw，则所需的宏调用将是：

{{EmbedYouTube("ELS2OOUvxIw")}}

另见

• 使用 SVG 格式代替 .png 图像 MDN GitHub 讨论