{"meta":{"title":"在文章中创建工具切换器","intro":"可以使用工具切换器来演示如何使用特定工具完成任务。","product":"贡献 GitHub 文档","breadcrumbs":[{"href":"/zh/contributing","title":"贡献 GitHub 文档"},{"href":"/zh/contributing/writing-for-github-docs","title":"为 GitHub 文档撰写内容"},{"href":"/zh/contributing/writing-for-github-docs/creating-tool-switchers-in-articles","title":"创建工具切换器"}],"documentType":"article"},"body":"# 在文章中创建工具切换器\n\n可以使用工具切换器来演示如何使用特定工具完成任务。\n\n## 关于工具切换器\n\n在某些文章中，我们针对不同工具（GitHub UI、GitHub CLI、GitHub Desktop、cURL、Codespaces、VS Code、GraphQL API 等）编写定制的内容。通过工具切换器，人员可以选择一种工具，仅查看与该工具相关的内容，因为各个工具可能具有不同的概念或过程信息。\n\n![文章中的工具切换器屏幕截图。 工具切换器以深橙色轮廓表示。](/assets/images/contributing/tool-switchers.png)\n\n人员在阅读文档时可以通过两种方式使用工具切换器。\n\n* **探索** - 对于可以使用不同工具完成的任务，工具切换器会向人员发出信号，告知他们可通过多种方式完成任务。 例如，使用 GitHub CLI 或 GitHub Desktop，而不是 GitHub UI。\n\n* **把握要点** - 当人员知道他们想要如何执行任务并且不需要查看其他选项时，工具切换器会移除不太相关的内容，这样他们就可以准确地找到所需的内容。\n\n## 使用工具标记\n\n可以使用 Markdown 中的工具标记将工具切换器添加到文章。 工具标记是用于包装要在特定工具切换器选项卡中显示的内容的 Liquid 标记。\n\n例如，以下代码块显示了三个不同工具的内容。\n\n```markdown\n{% vscode %}\nThis content is specific to Visual Studio Code.\n{% endvscode %}\n\n{% visualstudio %}\nThis content is specific to Visual Studio.\n{% endvisualstudio %}\n\n{% jetbrains %}\nThis content is specific to JetBrains IDEs.\n{% endjetbrains %}\n```\n\n默认情况下，将为文章选择 Markdown 中使用的第一个工具标记。 可以通过在文章的前辅文中指定 `defaultTool:` 属性，为文章定义不同的默认工具。 有关详细信息，请参阅[内容自述文件](https://github.com/github/docs/blob/main/content/README.md#defaulttool)。\n\n您还可以通过在链接末尾添加`?tool=TOOLNAME`，来链接到指定工具的文章。 有关详细信息，请参阅“[风格指南](/zh/contributing/style-guide-and-content-model/style-guide#links-to-a-specific-tool)”。\n\n一篇文章中最多只包含 8 种不同的工具。 包含更多工具会导致工具切换器与文章目录重叠，从而使人们无法使用工具切换器或目录。 不太可能需要在文章中包含 8 种独立工具。 通常，计划在文章中使用尽可能少的独立工具。\n\n### 何时使用工具标记\n\n仅当文章必须具有特定于工具的信息来帮助人员完成任务时，我们才使用工具标记。\n\n请勿仅仅为了显示不同语言的示例而使用工具切换器。 仅当文章中所述的任务或概念根据人员使用的工具发生更改时，才使用工具切换器。\n\n## 添加新工具\n\nGitHub Docs 将记录并维护 GitHub 产品、GitHub 开发的工具以及与 GitHub 协作开发的选定第三方扩展的工具标记。\n\n只有当新工具是准确记录特定用户需要的内容的唯一方式时，才会添加新工具。 如果编写者确定添加新工具是准确记录某些内容的唯一方法，则必须在内容设计阶段提出使用新工具。 审阅内容设计计划的人员应考虑是否有其他方法，可以在不添加新工具的情况下满足记录需求。 如果新工具是创建准确文档的唯一方法，则应添加新工具。 如果有不添加新工具的替代内容解决方案，则应使用该选项。\n\n若要添加新工具，请在 [`lib/all-tools.ts`](https://github.com/github/docs/blob/main/src/tools/lib/all-tools.ts) 文件中的 `allTools` 对象内添加一个条目作为键值对。 键是用于在文章中引用工具的标记，值是在文章顶部的工具选取器上标识该工具的方式。 例如，`vscode: 'Visual Studio Code'`。\n\n按字母顺序添加新工具。"}