创建屏幕截图

你可以通过将屏幕截图添加到 GitHub Docs 来帮助用户找到用户界面中难以找到的元素。

本文内容

关于 GitHub Docs 中的屏幕截图

添加屏幕截图是有利有弊的。 屏幕截图可以让文章内容更直观，并使说明更易于理解，尤其是对于在阅读上有困难的人员。 在与替换文字配合提供时，屏幕截图能帮助失明和弱视用户与视力正常的同事协作。

另一方面，屏幕截图对视力正常的用户作用较小，增加了文章的长度和加载时间，还增加了需要维护的内容量。 如果捕获的屏幕截图的像素维度以及缩放度与阅读方不一致，屏幕截图可能会让人看不清。

因此我们只会将符合插入条件的屏幕截图添加到 GitHub Docs。

插入屏幕截图的条件

当某个用户界面 (UI) 元素难以找到时，请使用屏幕截图来对文本说明进行补充：

  • 元素较小或不显眼。
  • 元素不是直接可见的。 例如下拉菜单中的元素。
  • 界面中存在可能导致混淆的多个类似选项。

请勿对仅采用文本描述就很清晰的过程步骤使用屏幕截图，也不要使用屏幕截图显示代码命令或输出。

插入条件的示例

为了帮助你确定是否应该添加特定的屏幕截图，请对以下符合以及不符合插入条件的屏幕截图示例进行思考。

符合条件的屏幕截图

以下屏幕截图是符合我们的插入条件的。

元素较小或不显眼

存储库的社交媒体预览图像的编辑按钮很小且不显眼。 可能很难在存储库设置中找到它。

文章的屏幕截图，其中包含文本说明以及用于在 GitHub 存储库中编辑社交媒体图像的 UI 的屏幕截图。

该屏幕截图还提供了所需纵横比的视觉参考。

UI 元素不是直接可见的

克隆 Gist 的选项包含在标有“嵌入”的下拉菜单下。

文章的屏幕截图，其中包含说明以及用于在 GitHub 上克隆 Gist 的 UI 的屏幕截图。

该屏幕截图有助于在菜单中找到正确的选项（要打开下拉列表才能看到）。

界面中存在可能导致混淆的多个选项

存储库主页面上有三个元素可以解释为“设置”：“设置”选项卡、右侧边栏“关于”部分中的齿轮图标，以及通过个人资料图片访问的帐户设置。

文章的屏幕截图，其中包含说明以及用于在 GitHub 存储库中找到设置页面的 UI 屏幕截图。

该屏幕截图有助于找到正确的选项。

不符合条件的屏幕截图

以下屏幕截图是不符合我们的包含条件的。

UI 元素易于找到

“创建存储库”按钮在大小、颜色和位置上都非常显眼。 没有什么类似的选项。

文章的屏幕截图，其中显示有关在 GitHub 上创建新存储库的最终步骤的说明和 UI 屏幕截图。

文本说明就足以帮助用户完成此步骤。

UI 只涉及少量且直接的选项

简单明了的选项（例如选择或取消选择复选框）不需要视觉上的支持。

文章的屏幕截图，其中包含说明以及要求参与者对基于 Web 的内容提交进行签名的 UI 屏幕截图。

文本说明就足以帮助用户完成此步骤。

屏幕截图中包含的复选框下的完整文本还会对易读性产生两个影响：

  • 这句话对于视力不佳的用户而言很难阅读，因为它很小且不像 HTML 文本那么清晰。
  • 使用屏幕阅读器的人无法获取到该信息，因为它不符合替换文字字符限制。 可以通过将该文本包含在说明中来弥补这一点，但会显得有些啰嗦。

屏幕截图的要求

除了插入条件之外，屏幕截图还必须满足以下要求。

技术规范

  • PNG 文件格式
  • 仅能使用静态图像（不能是 Gif 格式文件）
  • 144 dpi
  • 通栏图像 750–1000 像素宽
  • 文件大小不超过 250 KB
  • 采用描述性的文件名，例如 gist-embed-link.png，而不是 right_side_page_03.png

辅助功能

为了满足更多用户的需求，屏幕截图必须：

  • 在过程步骤中附有完整的说明，没有完全以视觉形式传达的信息。
  • 具有充分的对比度，在界面中清晰可见，不存在模糊或者不透明度或颜色对比不足的情况。
  • 替换文字（如果有）描述图像内容及其突出显示外观。 有关详细信息，请参阅“风格指南”。
  • 清晰明了，文本和 UI 元素尽可能清晰。

视觉样式

  • 在周围用足够的文本展示 UI 元素，以帮助大家了解该元素在屏幕上的位置。
  • 通过调整浏览器窗口的大小来减少负空间，直到达到最佳状态。
  • 尽可能以浅色主题显示界面。
    • 对于 GitHub，请在外观设置中选择浅色默认值。 有关详细信息，请参阅“管理主题设置”。
    • 对于 VSCode，请在免费的 GitHub 主题扩展中选择 GitHub 浅色默认值。
    • 如果需要屏幕截图的软件仅在深色模式下可用，则可以使用深色模式。
  • 如果显示用户名和头像，请将它们替换为 @octocat 的用户名和头像。 使用浏览器中的开发人员工具将用户名替换为 @octocat，并将头像的 URL 替换为 https://avatars.githubusercontent.com/u/583231?v=4。
  • 截图中请勿包含游标。

下拉菜单的视觉样式

如果显示下拉菜单的主要目标是帮助读者找到该菜单，则显示关闭状态的菜单。

文章的屏幕截图，其中显示有关选择文件夹作为 GitHub Pages 的发布源的说明和 UI 屏幕截图。

如果显示下拉菜单的主要目标是帮助读者区分菜单中的选项，则显示打开状态的菜单。 捕获打开的菜单，不带焦点（不处于存在光标的状态或悬停状态）。 显示具有白色背景的菜单项可确保与深橙色轮廓（存在时）形成鲜明对比。

文章的屏幕截图，其中包含说明以及用于在 GitHub 用户帐户菜单中找到“设置”菜单项的屏幕截图。

突出显示屏幕截图中的元素

若要在屏幕截图中突出显示特定 UI 元素，请使用 Snagit 的特殊主题在元素周围应用对比描边。

该描边是 Primer Design System（十六进制 #BC4C00 或 RGB 188、76、0）中的颜色 fg.severe。 这种深橙色在白色和黑色上都有很好的颜色对比度。 若要检查在其他背景色上的对比度，请使用颜色对比度分析器。

GitHub 存储库中四个选项菜单的屏幕截图。 标有“分叉”的菜单显示 58.5k 的分叉计数，并用深橙色框出。

将 GitHub Docs 主题导入 Snagit

  1. 若要下载 Snagit 主题，请在 github/docs 存储库中导航到 snagit-theme-github-docs.snagtheme，然后单击 。

    “snagit-theme-github-docs.snagtheme”的文件视图的屏幕截图。 在文件标题中，标有下载图标的按钮以深橙色框出。

  2. 打开 Snagit，然后选择“形状”工具。

  3. 在“快速样式”下选择“导入”。

  4. 从计算机的文件中选择“Snagit”主题。 这将安装形状预设。

  5. （可选）若要将主题添加到收藏夹，请选择以深橙色框出的星型图标。

向屏幕截图添加突出显示效果

  1. 在 Snagit 中打开屏幕截图。

  2. 若要设置像素深度（分辨率）和像素宽度，请在图像画布下打开“调整图像大小”对话框。

    • 像素深度：144 dpi（相当于 Snagit for Mac 上的“2x”）

    • 像素宽度：最大 1000 像素

    Note

    在 Windows 上，可能需要选择“高级”来更改分辨率****。 确保已禁用“使用重新采样”。

  3. 在“形状”边栏中打开 GitHub Docs 主题后，选择深橙色矩形。

  4. 在图像上进行拖放以创建矩形。

  5. 通过拖动边缘调整矩形的高度和宽度。 不要调整圆角，应保持 4 像素。 调整 UI 元素和描边之间的间距，使其与描边本身的宽度相等。

  6. 将图像导出为 PNG。

Note

Snagit 中的 bug 可能会影响圆角，导致矩形变为椭圆。 如果发生这种情况，请删除并重新安装 GitHub Docs 主题（Windows 和 Mac），或单击并拖动形状右上角的黄色点，已将圆角重置为 4 px（仅 Mac）。

替换屏幕截图

替换现有图像时，最佳做法是保留图像的文件名。

如果必须更改图像文件名，请在存储库中搜索对该图像的其他引用，并更新对原始文件名的所有引用。

如果在 弃用 版本的 GitHub Enterprise Server 文档中使用该图像，请不要更改文件名。

Markdown 内容中的图像版本控制

某些映像适用于所有 GitHub 计划（GitHub Free、GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server）。 在这种情况下，不需要版本控制。

当不同计划间的图像有所不同，或者图像会在更新版本的 GitHub Enterprise Server 中发生变化时，则需要使用 Liquid 条件语句对图像进行版本控制。 可能需要在最初创建内容时添加此版本控制，或者在为功能更新或 GitHub Enterprise Server 版本更新内容时添加此版本控制。

图像位置

图像位于 /assets/images 目录中。 此目录具有一些子目录，可用于按计划和版本号整理内容。

Directory使用情况
/assets/images不特定于任何 GitHub Enterprise 产品的图像。
/assets/images/enterprise/enterprise-server适用于 GitHub Enterprise Server (GHES) 的所有版本或适用于当前版本和未来版本的图像。
/assets/images/enterprise/<release number>，例如 /assets/images/enterprise/3.0/当图像在新的 GHES 版本中发生变化时，请将新图像添加到原始位置，并将旧图像移动到与该图像适用的最新版本对应的目录。

示例：再不同计划间有所不同的图像

如果在不同计划之间存在差异，可以使用 Liquid 条件对两个图像进行版本控制。


{% ifversion fpt or ghec %}
![An image of foo bar for GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud](/assets/images/foo/bar.png)
{% else %}
![An image of foo bar for GHES](/assets/images/enterprise/foo/bar.png)
{% endif %}

示例：新的 GitHub Enterprise Server 版本中更新了图像

如果 GitHub Enterprise Server 3.10 的图像将发生更改，并且更新后的图像将用于 GitHub Enterprise Server 以后的所有版本，请将现有图像移动到 /assets/images/enterprise/3.10，然后将新图像添加到原始位置 /assets/images/enterprise/foo/bar.png。

Liquid 条件如下所示：


{% ifversion fpt or ghec %}
![An image of foo bar](/assets/images/foo/bar.png)
{% elsif ghes < 3.10 %}
![An image of foo bar for GHES 3.9 and lower](/assets/images/enterprise/3.5/foo/bar.png)
{% else %}
![An image of foo bar for GHES 3.10+](/assets/images/enterprise/foo/bar.png)
{% endif %}

当 3.10 版本 弃用 时，/assets/images/enterprise/3.10 目录将被移除。

带编号的版本目录应包含仅适用于该版本号及其更早版本的图像。 例如，/assets/images/enterprise/2.22 中应包含仅适用于 2.22 或 2.22 及更早版本的图像。