如何添加图片和媒体

添加图片

要将图片添加到文档中，请将图片文件添加到文档的文件夹中，然后使用 Markdown 图片语法 或等效的 HTML <img> 元素在文档的 index.md 文件中引用图片。

让我们来看一个例子

  1. 从一个新的工作分支开始，该分支包含来自 mdn 远程仓库的 main 分支的最新内容。
    bash
    cd ~/path/to/mdn/content
git checkout main
git pull mdn main
# Run "yarn" again just to ensure you've
# installed the latest Yari dependency.
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 的体型和品种，因此包含它会显得重复。避免对图片进行过多的描述：潜在的养狗人不需要知道狗是在室内还是室外，也不需要知道它是否戴着红色项圈和蓝色牵引绳。

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

Markdown 和 HTML 中的语法

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

示例

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

虽然纯装饰性图片应该有一个空的 alt，但添加到 MDN 文档中的图片应该有目的，因此需要一个非空字符串描述。

压缩图片

当你将图片添加到 MDN Web Docs 的页面上时，你应该确保它们尽可能地压缩（不降低质量），以节省读者下载的大小。事实上，如果你没有这样做，我们的 CI 流程将会失败，构建结果会警告你一些图片太大了。

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

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

添加视频

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 的分辨率。
  • 以高清录制视频，这样上传后看起来会更好。
  • 对于 DevTools 视频，通常建议选择与页面内容形成对比的主题。例如，如果示例网页是浅色主题，请选择深色主题。这样更容易看到发生了什么，以及 DevTools 的开始和页面结束位置。
  • 对于 DevTools 视频，尽可能放大 DevTools，同时仍然显示所有想要显示的内容，并使其看起来正常。
  • 确保你想要演示的内容没有被鼠标光标遮挡。
  • 考虑是否需要配置屏幕录制工具以添加鼠标点击的视觉指示器。

视频工具指南

你需要一个工具来录制视频。这些工具从免费到昂贵，从简单到复杂。如果你已经熟悉创建视频内容，那么很棒。如果不是，我们建议你从一个简单的工具开始，然后如果你开始享受创建视频内容并想创建更多有趣的制作，则可以升级到更复杂的工具。

下表提供了一些针对良好入门工具的建议

工具 操作系统 成本 是否提供后期制作功能？
Open Broadcaster Software macOS、Windows、Linux 免费 是
CamStudio Windows 免费 有限
Camtasia Windows、macOS 高 是
QuickTime Player macOS 免费 否，只允许简单录制
ScreenFlow macOS 中等 是
Kazam Linux 免费 最小

QuickTime Player 小贴士

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

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

其他资源

创建视频的工作流程

以下小节描述了创建视频并将其添加到 MDN Web Docs 文章中所需遵循的常规步骤。

准备

首先，规划要捕获的流程：考虑最佳的开始和结束点。

确保桌面背景和浏览器配置文件干净。规划浏览器窗口的大小和位置，尤其是在使用多个窗口时。

仔细规划要记录的内容，并在录制前练习几次步骤

  • 不要在流程的中间开始录制视频 - 考虑一下观众是否有足够的上下文信息来理解你的操作。例如，在 DevTools 的简短视频中，最好从打开 DevTools 开始，让观众可以了解情况。
  • 考虑你的操作，放慢速度，并使其变得明显。每当你必须执行一个操作（例如，点击一个图标）时，放慢速度并使其变得明显。例如：
    • 将鼠标移到图标上。
    • 突出显示或放大（并非总是，取决于是否觉得需要）。
    • 暂停一下。
    • 点击图标。
  • 规划要显示的 UI 部分的缩放级别。并非每个人都能以高清观看你的视频。你可以在后期制作中放大特定部分，但最好事先也放大应用程序。

注意：不要放大到显示的 UI 开始看起来陌生或难看的地步。

录制

在录制要显示的工作流程时，平稳而稳定地完成流程。当你处于关键时刻时，暂停一秒或两秒 - 例如，当你即将点击按钮时。确保鼠标指针不会遮挡任何对你正在演示的内容重要的图标或文本。

记住在最后暂停一秒或两秒以显示流程的结果。

注意：如果你使用的是 QuickTime Player 这样的简单工具，并且由于某种原因后期制作不可用，则应将窗口设置成合适的尺寸以显示要显示的区域。在 Firefox DevTools 中，可以使用标尺工具来确保视窗具有正确的纵横比以进行录制。

后期制作

你将能够在后期制作中突出显示关键时刻。突出显示可能包含一些内容，你通常会将这些内容组合在一起，例如：

  • 放大屏幕的一部分。
  • 淡出背景。

突出显示工作流程的关键时刻，尤其是难以看到的细节：例如，点击特定图标或输入特定 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")}}