关于 GitHub 文档中的截图
添加截图既有正面也有负面影响。截图可以让文章更具视觉可扫描性，使说明更易于理解，尤其是对阅读有困难的用户。当提供 alt 文本时，截图还能帮助盲人和低视力用户与视力正常的同事协作。
另一方面，截图偏向于视力正常的用户，会给文章增加长度和加载时间，并增加需要维护的内容量。当截图的像素尺寸和缩放程度与读者的使用情况不一致时，可能会导致混淆。
因此，我们仅在截图符合我们的包含标准时才将其添加到 GitHub 文档中。
包含截图的标准
当用户界面（UI）元素难以找到时，使用截图来补充文字说明
- 该元素体积小或视觉上不明显。
- 该元素并非立即可见。例如，它位于下拉菜单中。
- 界面中有多个相互竞争的选项，可能会导致混淆。
不要在文字说明已经足够明确的步骤中使用截图，也不要用截图来展示代码命令或输出。
符合标准的示例
为了帮助您判断是否需要添加特定截图，请参考以下满足或不满足我们包含标准的截图示例。
符合标准的截图
以下截图符合我们的包含标准。
UI 元素体积小或视觉上不明显
仓库社交媒体预览图的编辑按钮体积小且视觉上不显眼。它在其他仓库设置中可能难以发现。
该截图还提供了所需宽高比的视觉参考。
UI 元素并非立即可见
克隆 gist 的选项位于标记为 “Embed” 的下拉菜单下。
该截图有助于定位菜单中正确的选项，因为在展开下拉菜单之前该选项不可见。
界面中有多个可能导致混淆的选项
在仓库主页上，有三个元素可能被解释为 “设置”：位于右侧侧栏 “About” 部分的齿轮图标、页面顶部的 “Settings” 选项卡，以及通过个人头像访问的账户设置。
该截图有助于找到正确的选项。
不符合标准的截图
以下截图不符合我们的包含标准。
UI 元素易于找到
“创建仓库”按钮通过尺寸、颜色和位置在视觉上非常突出。竞争选项很少。
文字说明已经足以帮助用户完成该步骤。
UI 选项少且直观
诸如选中或取消选中复选框等简单直接的选项不需要视觉辅助。
文字说明已经足以帮助用户完成该步骤。
在截图中将复选框下方完整句子包含进去，还会产生以下两点可访问性问题：
- 该句子对视力低下的用户而言难以阅读，因为文字小且不如 HTML 文本清晰。
- 使用屏幕阅读器的用户无法获取该信息，因为它超出了 alt 文本字符限制。将文字放入说明中可以解决此问题，但会导致说明冗长。
截图的要求
除了包含标准外，截图还必须满足以下要求。
技术规格
- PNG 文件格式
- 仅限静态图像（不支持 GIF）
- 144 dpi
- 全列宽图像宽度 750–1000 像素
- 文件大小不超过 250 KB
- 使用描述性的文件名，例如
gist-embed-link.png而不是right_side_page_03.png - 在 macOS 上捕获的图像必须为 Retina 图像
- 在 Snagit 中，选择 Snagit > Preferences > Advanced，并取消勾选 “Scale down retina images when sharing”
可访问性
为了满足更多用户的需求，截图必须：
- 配合完整的步骤说明，且不能仅通过视觉形式传达信息。
- 保持完整的对比度，和界面本身一致，不能有遮挡、透明度降低或对比度下降的情况。
- 提供描述图像内容及其（若有）高亮外观的 alt 文本。更多信息请参见 样式指南。
- 图像应清晰锐利，文本和 UI 元素尽可能易读。
视觉风格
- 仅显示足够的上下文，以帮助用户了解在屏幕上如何找到该 UI 元素。
- 通过调整浏览器窗口大小来减少空白区域，直至达到最佳效果。
- 尽可能使用浅色主题展示界面。
- 在 GitHub 中，请在外观设置中选择 “Light default”。更多信息请参见 管理主题设置。
- 在 VSCode 中，请在免费 GitHub Theme 扩展中选择 “GitHub light default”。
- 如果您需要截图的软件只能使用深色模式，则使用深色模式即可。
- 如果截图中出现了您的用户名和头像，请将它们替换为 @octocat 的用户名和 头像。使用浏览器的开发者工具将用户名替换为
@octocat，并将头像的 URL 替换为https://avatars.githubusercontent.com/u/583231?v=4。 - 请勿在截图中包含光标。
下拉菜单的视觉风格
如果展示下拉菜单的主要目的是帮助读者定位该菜单本身，请显示闭合状态的菜单。
如果展示下拉菜单的主要目的是帮助读者区分菜单内的各选项，请显示展开状态的菜单。捕获展开的菜单时不要带有焦点（光标或悬停状态）。使用白色背景的菜单项可确保在有深橙色轮廓的情况下保持对比度。
在截图中突出显示元素
要在截图中突出特定 UI 元素，请使用我们为 Snagit 定制的主题，在该元素周围添加对比度高的描边。
描边颜色为 fg.severe，来自 Primer Design System（HEX #BC4C00 或 RGB 188, 76, 0）。这种深橙色在白色和黑色背景上都有良好的对比度。要检查其他背景颜色的对比度，请使用 Color Contrast Analyzer。
将 GitHub Docs 主题导入 Snagit
-
要下载 Snagit 主题，请前往
snagit-theme-github-docs.snagtheme（位于github/docs仓库），然后点击.
-
打开 Snagit，选择 Shape 工具。
-
在 “Quick styles” 下，选择 Import。
-
从计算机文件中选择 Snagit 主题。这将安装形状预设。
-
可选：要将该主题加入收藏，请为深橙色矩形添加星标。
给截图添加高亮
-
在 Snagit 中打开截图。
-
要设置像素深度（分辨率）和像素宽度，请在图像画布下方打开 “Resize image” 对话框。
-
像素深度：144dpi（相当于 Mac 版 Snagit 的 “2x”）
-
像素宽度：最大 1000 像素
注意
在 Windows 上，可能需要选择 Advanced 才能更改分辨率。确保 Use resampling 已禁用。
-
-
在形状侧边栏打开 GitHub Docs 主题后，选择深橙色矩形。
-
在图像上拖放以创建矩形。
-
通过拖动边缘调整矩形的高度和宽度。不要更改圆角，圆角应保持 4 像素。将 UI 元素与描边之间的间距调整至约等于描边宽度本身。
-
将图像导出为 PNG。
注意
Snagit 的一个 bug 可能会破坏圆角，使矩形变成椭圆。如果出现此情况，请删除并重新安装 GitHub Docs 主题（Windows 和 Mac），或在形状右上角的黄色点上点击并拖动以将圆角重置为 4 像素（仅限 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 目录中。此目录下有若干子目录，可用于按计划和发布号组织内容。
| 目录 | 用途 |
|---|---|
/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 %}
{% else %}
{% endif %}
示例：在新的 GitHub Enterprise Server 发布中更新图像
如果图像将在 GitHub Enterprise Server 3.10 中更改，并且更新后的图像将在所有后续版本中使用，请将现有图像移动到 /assets/images/enterprise/3.10，然后将新图像添加到原始位置 /assets/images/enterprise/foo/bar.png。
您的 Liquid 条件语句应如下所示
{% ifversion fpt or ghec %}
{% elsif ghes < 3.10 %}
{% else %}
{% endif %}
当 3.10 版本停用时，/assets/images/enterprise/3.10 目录将被删除。
带编号的发布目录应仅包含适用于该发布号本身或该发布号及更早版本的图像。例如，/assets/images/enterprise/2.22 中的图像应仅适用于 2.22 或 2.22 及更早的版本。