codetour

机器翻译正文由机器翻译自项目原始文档（英文），排版经程序统一处理，可能存在偏差，请以原项目仓库为准。

代码导览 🗺️

CodeTour 是一个 Visual Studio Code 扩展，它允许你录制和回放代码库的引导式演练。它就像一个目录表，可以让你更容易地上手（或重新上手）一个新项目/功能区，直观地查看错误报告，或理解代码审查/PR 更改的背景。“代码演练”只是一个交互式步骤系列，每个步骤都与特定目录或文件/行相关联，并包括相应代码的描述。这允许开发者克隆一个仓库，然后立即开始学习它，无需参考 CONTRIBUTING.md 文件或依赖他人的帮助。演练可以提交到仓库中，以便与其他贡献者共享，或者导出为“演练文件”，这允许任何人重放同样的演练，而无需克隆任何代码！

入门

要开始使用，请安装 CodeTour 扩展，然后根据你是想录制还是回放演练，按照以下指南之一进行操作：

• Recording Tours
• Exporting Tours
• Starting Tours
• Navigating Tours
• Maintaining Tours
• Reference

录制演练

如果你想为你的代码库录制代码演练，可以简单地点击 + 按钮在 CodeTour 树视图中（如果可见）和/或运行 CodeTour: Record Tour 命令。这将启动演练录制器，让你开始打开文件，点击你想注释的行的“评论栏”，然后添加相应的描述（包括 markdown！）。可以添加任意数量的步骤，完成后，只需点击停止演练操作（红色方块按钮）。你也可以创建目录步骤、选择步骤或内容步骤，为演练添加介绍或中间说明。

在录制时，CodeTour 树视图将显示当前录制的演练及其当前步骤集。你可以通过其名称左侧的麦克风图标识别正在录制的演练。

如果你在录制过程中需要编辑或删除某个步骤，点击步骤描述旁边的 ... 菜单，并选择相应操作。或者，你也可以从 CodeTour 树视图中编辑/删除步骤。

工作区

如果你在“多根工作区”中录制演练，将会要求你选择保存演练的文件夹。这是必要的，因为演练会以文件形式写入你的工作区，因此需要明确演练应保存到哪个文件夹。不过，当你录制演练时，可添加跨工作区任意文件夹的步骤，这允许你为特定文件夹创建演练，和/或展示跨多个工作区文件夹的概念。

步骤标题

默认情况下，CodeTour 树使用以下显示名称格式显示每个导览步骤：#<stepNumber> - <filePath>。不过，如果您想为步骤提供更友好/易识别的名称，可以使用以下方法之一：

1. 右键单击 CodeTour 树中的步骤，然后选择 Change Title。
2. 编辑步骤的描述，并在其顶部添加 Markdown 标题，使用您喜欢的标题级别（例如 #、## 等）。例如，如果您添加的步骤描述以 ### Activation 开头，则步骤和树视图将如下所示：

文本选择

默认情况下，每个步骤都与您创建评论的代码行相关联（即您在评论栏上点击 + 的那一行）。但是，如果您想将特定代码范围包括为步骤的一部分，只需在添加步骤之前突出显示代码（点击 Add Tour to Step 按钮），该选择将作为步骤的一部分被捕获。

如果您需要调整与步骤关联的选择，只需编辑步骤，重置选择，然后保存。此外，如果您想从选择中创建步骤，只需突出显示一段代码，右键单击编辑器，然后选择 Add CodeTour Step。

重新排列步骤

在录制导览时，您添加的每个新步骤都会附加到导览的末尾。不过，您可以通过执行以下操作之一来上下移动现有步骤的顺序：

• 将鼠标悬停在 CodeTour 树中的步骤上，然后点击上下箭头图标。
• 右键单击 CodeTour 树中的步骤，然后选择 Move Up 或 Move Down 菜单项。
• 点击步骤评论界面中的 ... 菜单，然后选择 Move Up 或 Move Down。

此外，如果您想在导览中间添加新步骤，只需导航到您想要插入新步骤之后的步骤，然后创建新步骤。

删除步骤

如果您不再需要导览中的特定步骤，可以通过以下操作之一将其删除：

• 右键单击 CodeTour 树中的步骤，然后选择 Delete Step。
• 导航到重播/评论界面中的步骤，选择评论描述旁边的 ... 菜单，然后选择 Delete Step。

如果需要删除多个步骤，CodeTour 树支持多选，因此您可以在 macOS 上使用 Cmd+click / 在 Windows/Linux 上使用 Ctrl+click 多选多个步骤节点，然后右键单击它们并选择 Delete Step。

编辑导览

如果您想编辑现有导览，只需右键单击 CodeTour 树中的导览，然后选择 Edit Tour。或者，您可以通过点击当前步骤评论栏中的铅笔图标，或运行 CodeTour: Edit Tour 命令来编辑您正在查看的导览。

在任何时候，你都可以在 CodeTour 树中右键点击一个游览，并通过选择 Change Title、Change Description 或 Change Git Ref 菜单项来更改其标题、描述或 git 引用。此外，你可以通过在 CodeTour 树中右键点击它并选择 Delete Tour 来删除一个游览。

链接游览

如果你想创建一系列用户可以按顺序导航的游览，只需在你的游览标题前加上它们在游览顺序中的编号（例如 1: Foo、2 - Bar）。当你的游览标题这样命名时，游览播放器会自动为读者提供以下好处：

1. 如果当前游览有后续游览，则其最后一步将显示一个 Next Tour 链接，而不是 Finish Tour 链接。这允许用户轻松跳转到下一个游览。

2. 如果当前游览有前一个游览，则其第一步将显示一个 Previous Tour 链接。这允许用户返回他们可能刚刚访问过的游览。

如果你不想这样给游览编号，但仍希望将一个游览链接到另一个，你可以打开它的 *.tour 文件，并将 nextTour 属性设置为你希望它链接的游览标题。

主要游览

一个代码库可以包含一个或多个游览，但它可能有一个主要游览，专门为新开发者设计。这样，当他们首次打开代码库时，可以立即看到此游览，而不是看到所有游览的列表。

为了将特定游览标记为主要游览，只需在 CodeTour 树中右键点击它，并选择 Make Primary。当你将一个游览标记为主要时，任何已标记为主要的其他游览将更新以移除该标注。此外，如果你想手动取消标记游览为主要游览，可以右键点击它并选择 Unmake Primary。

如果你更愿意给游览编号（例如 1 - Status Bar），则标题以 #1 - 或 1 - 开头的游览将自动被认为是主要游览，你无需做其他操作。

条件游览

如果你编写的游览并非对团队中每个开发者都相关，则可以通过向相应 *.tour 文件添加 when 属性来决定何时在 CodeTour 树中有条件地显示它。此属性期望一个 JavaScript 表达式，根据其计算为 true 或 false 来决定游览的可见性。默认情况下，所有游览都显示，因此，只有带有 when 属性且计算结果为 false 的游览会被隐藏。

为了简化定义条件游览的过程，以下变量可用于你的 when 子句：

• isLinux - 当前用户正在使用 Linux
• isMac - 当前用户正在使用 macOS
• isWindows - 当前用户正在使用 Windows

例如，如果您想定义一个仅显示给 Linux 用户的导览，您可以简单地将 when 属性设置为 "isLinux"。

CodeTour 风格的 Markdown

当您描述一个步骤时，您可以使用完整的 Markdown 功能来编写丰富/引人入胜的内容（例如图片、链接、标题、代码块）。但是，CodeTour 还提供了一些额外的语法功能，让您可以在导览中增加更多交互性：

文件引用

如果您希望某个步骤引用工作区内的文件，可以使用工作区相对路径添加 Markdown 链接。例如，将 [Open file](./file.html) 添加到步骤内容中，会添加一个名为 Open file 的超链接，点击该链接将打开 ./file.html 文件。

此外，您还可以在步骤中引用本地图像，使用 Markdown 引用。例如，添加 ![Image](./icon.png) 会在步骤中呈现 icon.png。

步骤引用

如果您想在当前导览中添加对另一个步骤的引用，可以使用 Markdown 的“链接引用”语法，指定要导航到的步骤的 1 基数编号，并在前面加上 # 字符（例如 [#2] 或 [#23]）。此引用将自动呈现为超链接，点击它会将最终用户导航到该步骤。链接文本默认显示为 #<stepNumber>，但您可以通过在链接引用后添加标题来自定义它（例如 [title][#2]）。

此语法是手动使用 Navigate to tour step 命令链接 的简化版本。

导览引用

如果您想引用完全不同的导览，则可以创建一个链接引用，指定该导览的标题（例如 [Tree View]）。它将呈现为超链接，点击后会导航最终用户进入该导览，从第 1 步开始。如果您希望导航用户到导览中的特定步骤，可以在导览标题后附加步骤编号，并用 # 分隔（例如 [Tree View#3]）。链接文本将呈现为 <tourTitle>，但您可以通过在链接引用后附加标题进行自定义（例如 [title][Tree View]）。

此语法是使用 Start tour 命令链接 的简化版本。

代码块

如果您在步骤主体内容中添加了 Markdown 代码块，则 CodeTour 播放器将在其下方渲染一个 Insert Code 链接，允许查看者自动将代码片段插入到当前文件中与该步骤相关的行。这可以方便地使用 CodeTour 创建交互式教程或示例。

注意：代码片段插入到文档后会进行格式化，因此您无需担心在片段本身添加空格等。

Shell 命令

为了更简单地将 shell 命令嵌入到一个步骤中（例如执行构建、运行测试、启动应用程序），CodeTour 支持一种特殊的 >> 语法，后面跟着你想运行的 shell 命令（例如 >> npm run compile）。这将被转换为一个超链接，当点击时，会启动一个新的集成终端（称为 CodeTour）并运行指定的命令。

命令链接

为了向导增加更多的交互性，你可以在步骤描述中包含“命令链接”。命令链接只是使用 command: 方案（而不是 http: / https:）的 markdown 链接，并指定 VS Code 命令的名称，以及包含所需命令参数的可选查询字符串。使用这种语法，你可以调用 VS Code 中的任何命令，包括内置命令（例如 vscode.open），以及由扩展提供的命令（例如 codetour.startTour）。例如，下面显示了如何包含带参数和不带参数的命令。

<!-- Call a command that doesn't require arguments-->

[Start tour](command:codetour.startTour)

<!-- Call a command that requires arguments-->

[Open URL](command:vscode.open?["https://aka.ms/codetour"])

知名命令

为了更简单地调用常用命令，当你在步骤注释中输入 command: 时，CodeTour 会提示你一个知名命令列表。如果选择一个选项，它将生成相应的 Markdown 代码，并为任何必要的参数包含占位符。以下列表说明了当前支持的知名命令集：

• Navigate to tour step - 允许你指定一个导览步骤，当点击时，将引导最终用户导航到当前导览中的该步骤。这可以方便用户选择跳到导览的后续步骤，或者快速参考之前的步骤。

• Open URL - 允许你指定一个 URL，当点击时，将启动最终用户的默认浏览器并导航到该 URL。

• Run build task - 允许你运行构建任务，该任务由当前工作区的 task.json 文件定义。

• Run task - 允许你指定一个工作区任务名称，当点击时，将运行当前工作区 task.json 文件中定义的指定任务。

• Run test task - 允许你运行 butestild 任务，该任务由当前工作区的 task.json 文件定义。

• Run terminal command... - 允许你指定一个 Shell 命令（例如 npm run package），当点击时，将在集成终端中运行指定命令。

• Start tour... - 允许你指定工作区内另一个导览的标题，当点击时，将自动启动该导览。

导览版本控制

当你录制导览时，系统会询问你要与哪个 Git "ref" 关联。这允许你定义导览在相应代码库发生更改时的稳健性。

你可以选择将导览与以下 ref 类型关联：

• None - 导览不与任何 ref 关联。此选项的好处是可以在导览过程中编辑代码，因为导览将根据用户当前检出的分支/提交进行操作（例如交互式教程）。
• Current Branch - 导览仅限于当前分支。这可能会有与 None 相同的稳健性挑战，但它允许你为导览维护一个特殊分支，可单独进行版本控制。如果最终用户检出了关联分支，那么导览将在进行时允许他们编辑文件。否则，导览将以只读文件方式回放。
• Current Commit - 导览仅限于当前提交，因此不会出现不同步的问题。如果最终用户的 HEAD 指向指定提交，那么导览在进行时会允许他们编辑文件。否则，导览将以只读文件方式回放。
• 标签 - 导览仅限于所选标签，因此不会出现不同步的问题。仓库的所有标签将显示，方便你轻松选择其中一个。

在任何时候，您都可以通过在 CodeTour 树中右键点击该游览并选择 Change Git Ref 来编辑游览的引用。这可以让您在更改/更新代码和/或代码库时，将游览“重新定位”到某个标签/提交。

内容步骤

代码游览主要用于描述代码，不过，当您正在记录游览时，提供一些关于游览本身的介绍可能会有帮助。为此，您可以创建一个“内容步骤”，这是一个包含标题和 Markdown 内容的游览步骤，但与目录或文件无关。要创建内容步骤，请执行以下操作之一：

1. 在 CodeTour 树中点击 Add tour step... 节点，它位于代表您当前正在记录的游览的节点下。注意：此选项仅当游览没有任何步骤时才可用。
2. 在 CodeTour 树中右键点击游览节点并选择 Add Tour Step。注意：此选项仅在记录游览时可用。
3. 运行 CodeTour: Add Tour Step 命令。

创建内容步骤时，系统会要求您提供步骤的标题（例如 Introduction），然后会创建一个“虚拟”文件，并附带一个您可以编辑的注释。这允许查看者在各步骤之间以一致的方式导航，无论该步骤是否关联文件。

目录步骤

如果您希望在游览中突出显示某个目录，那么在记录时，可以在 Explorer 树中右键点击该目录并选择 Add CodeTour Step。这将创建一个新步骤，允许您为选定目录添加描述。当播放游览时，目录将在 Explorer 树中被突出显示，并且查看者将看到在“虚拟”CodeTour 文档中的描述。

游览文件

在后台，游览将作为一个 JSON 文件写入当前工作区的 .tours 目录。该文件相当简单，如果愿意可以手动编辑。此外，您可以通过遵循 游览模式 手动创建游览文件。然后，您可以将这些文件存储到 .tours（或 .vscode/tours 或 .github/tours）目录，也可以在以下任意已知位置创建游览：.tour、main.tour、.vscode/main.tour。

在 .tours（或 .vscode/tours）目录中，您可以将游览文件组织到任意深度的子目录中，CodeTour 播放器将正确地发现它们。

游览模式

• title (必填) - 游览的显示名称，将在 CodeTour 树视图、快速选择等中显示。
• description - 可选的游览描述，将作为 CodeTour 树视图中游览的工具提示显示。
• ref - 可选的“git 引用”（分支/标签/提交），此游览适用于该引用。详情请参见 游览版本控制。
• isPrimary - 指示此游览是工作区内的主要游览，最终用户应按照该游览进行引导。
• nextTour - 本次巡演的名称（#linking-tours）。
• when - 指定在展示本次巡回之前必须满足的条件。该属性的值是一个字符串，以 JavaScript 形式评估。
• steps （必修） - 一系列巡演步骤
  • description （必需） - 解释当前文件/行号的文本，可包括纯文本和标记语法
  • file - 该步骤关联的文件路径（相对于工作区根节点）
  • directory - 该步骤关联的目录路径（相对于工作区根）。Note：该属性优先于file属性，因此如果两者都present.，则“获胜”
  • uri - 该步骤关联的绝对URI。注意uri和file互斥，因此每步只设置一个
  • line - 该步骤关联的以1为基础的行号
  • pattern - 用于关联步骤的正则表达式。只有在line属性未设置时才考虑，允许你将步骤关联为行内容而非序数。
  • title - 一个可选标题，将在CodeTour树视图中作为步骤名称显示。
  • commands- 一个由VS Code命令字符串组成的数组，表示命令的名称（例如：codetour.endTour）以及任何可选参数，这些参数以查询字符串数组的形式指定（例如：codetour.endTour?[2]）。
  • view - 当导航到此步骤时，VS Code 视图的 ID，会自动聚焦。

举例来说，可以参考该仓库的.tours/tree.tour文件。

出口旅游

默认情况下，当你录制一个导览时，它会写入当前开放的工作区。这样你可以轻松地签入导览并与团队其他成员分享。不过，有时你可能想为自己录制一个导览，或者用来帮助别人解释一次性的导览，在这种情况下，你可能不想把导览录入仓库。

为了支持这种情况，当你开始录制新巡演时，可以点击右上角对话框中的Save tour as...按钮，该对话框要求你填写巡演标题。这样你就可以选择新巡演将被写入的文件，避免它被持久化在工作区中。此外，你可以像平常一样录制一个巡演，录制完成后，在CodeTour树中右键点击它并选择Export Tour...。这样你就可以将巡演保存到新位置，然后从仓库中删除巡演文件。当你导出巡演时，巡演文件本身会嵌入所有巡演所需的文件内容，确保无论本地是否有相应代码，都能回放。这带来了一种强大的协作形式。

GitHub 精选

如果你安装了 [GistPad]（https://aka.ms/gistpad ） 扩展，你会在CodeTour树中看到额外的 Export Tour to Gist... 选项。这允许你将导览文件导出为新的/已有的 gist，方便你创建自己的私人导览和/或创建可以与团队成员共享的导览。

一旦导览导出为gist，你可以在GistPad树中右键点击main.tour文件，选择Copy GitHub URL。如果你把它发给某人，他们运行CodeTour: Open Tour URL...命令，那么无论他们是否有本地代码，都能参加完全相同的游览。

起始巡回赛

要开始参观，只需打开一个包含一个或多个参观的代码库。如果你是第一次打开该代码库，会弹出一个祝酒通知，询问是否愿意参观。

否则，你可以通过以下任一方法手动开始行程：

1. 在Explorer活动标签页的[CodeTour视图]（#tree-view）中选择一个导览（或特定步骤）

2. 运行CodeTour: Start Tour [命令]（#contributed-commands），然后选择你想参加的旅游

   如果当前工作区只有一个代码参观，那么这个命令会自动启动该参观。否则，你会看到一个可选参观列表。

开幕巡演

除了接收当前开放工作区中的参观外，你还可以打开别人发给你和/或你自己创建的导览文件。只需运行CodeTour: Open Tour File...命令和/或点击CodeTour树视图标题栏中的文件夹图标即可。

注意：CodeTour树视图仅在当前开放的工作区有导览和/或你正在参观时才会显示。

此外，如果有人已经导出了（#exporting-tours）一个导览，并上传到公开可访问的地点，他们可以把网址发给你，你可以通过运行CodeTour: Open Tour URL...命令打开它。

巡回标志

在你探索代码库时，可能会遇到一个“巡回标记”，它会在文件页中显示CodeTour图标。这表示一行代码参与了开放工作区的巡演，方便你发现可能与当前工作相关的巡演。看到标记时，只需将鼠标悬停在该行上，点击悬停工具提示中的Start Tour链接。这会在特定步骤开始与该代码关联的巡演。

如果你想禁用巡回标志，可以执行以下操作之一：

• 运行CodeTour: Hide Tour Markers命令
• 点击CodeTour树视图标题栏中的“眼睛图标”
• 将codetour.showMarkers配置设置设置为false。Note上述两个操作能帮你做到这一点automatically.

导航游览

一旦您开始了一个游览，评论界面将指导您，并包含导航操作，使您能够执行以下操作：

• Move Previous - 导航到当前游览的上一步。此命令在步骤 #2 及之后可见。
• Move Next - 导航到当前游览的下一步。此命令在除最后一步之外的所有步骤可见。
• Edit Tour - 开始编辑当前游览（详见 authoring）。注意，并非所有游览都可编辑，因此根据您启动游览的方式，您可能会看到或看不到此操作。
• End Tour - 结束当前游览并移除评论界面。

此外，您可以使用 ctrl+right / ctrl+left（Windows/Linux）和 cmd+right / cmd+left（macOS）键盘快捷键在游览中向前或向后移动。CodeTour 树视图和状态栏也会与您当前的游览/步骤保持同步，以帮助开发者轻松理解他们在整个游览中的位置。

如果您离开当前步骤并需要继续，可以通过以下任意操作恢复：

• 在 CodeTour 树中右键点击活动游览并选择 Resume Tour
• 点击 CodeTour 状态栏项目
• 在命令面板中运行 CodeTour: Resume Tour 命令

您可以随时通过以下任意操作结束当前代码游览：

• 点击当前步骤评论中的停止按钮（红色方块）
• 点击 CodeTour 树中活动游览旁的停止按钮
• 在命令面板中运行 CodeTour: End Tour 命令

维护游览

为了确保您的游览在代码库演进时保持最新，您可以在 CI 管道中安装以下任务之一，以检测针对 PR/提交等的“游览漂移”。

• CodeTour Watch (GitHub Actions)
• CodeTour Watcher (Azure Pipelines)

参考

以下部分描述了 CodeTour 扩展贡献的 VS Code 集成（例如树视图、状态栏、设置）：

树视图

如果当前打开的工作区有任何代码导览，或者你正在主动进行/录制导览，你会看到一个名为 CodeTour 的新树状视图，它被添加到 Explorer 选项卡中。此视图简单地列出了可用代码导览的集合，以及它们的标题和步骤数。如果你选择一个导览，它将开始该导览，因此，这只是运行 CodeTour: Start Tour 命令的一个更方便的替代方法。不过，你也可以展开一个导览并从特定步骤开始、编辑/删除步骤、重新排列步骤，以及更改导览的描述/标题/git 引用。

此外，树状视图会显示当前正在录制的导览，这使得在创建新导览的过程中容易跟踪你的状态。

树状视图会自动保持最新状态，因为你在当前工作区中添加/编辑/删除导览。因此，请随意录制和/或编辑导览，然后完成后进行导航。

状态栏

除了 CodeTour 树状视图外，CodeTour 扩展还提供了一个状态栏项目，用于指示你当前正在进行或录制的导览的标题和步骤。当点击它时，它会打开当前导览步骤的文件/行，这允许你在进行导览时打开其他文件，然后在准备好时恢复导览。一旦结束当前导览，状态栏会自动隐藏。

提供的命令

除了 CodeTour 树状视图和状态栏项目外，CodeTour 扩展还将以下命令贡献给命令面板：

• CodeTour: Open Tour File... - 允许你选择之前导出的导览文件。

• CodeTour: Record Tour - 启动导览录制器，通过创建一系列步骤来创建新导览。

• CodeTour: Start Tour - 启动当前打开工作区的导览。此命令仅在当前工作区有一个或多个代码导览时可见。

• CodeTour: Refresh Tours - 刷新 CodeTour 视图，当你已在磁盘上创建/修改/删除导览文件时，这会非常方便。此命令仅在当前工作区有一个或多个代码导览时可见。

• CodeTour: Hide Tour Markers - 隐藏导览标记。此命令仅在当前工作区有一个或多个代码导览且导览标记目前可见时可见。

• CodeTour: Show Tour Markers - 显示导览标记。此命令仅在当前工作区有一个或多个代码导览且导览标记目前隐藏时可见。

• CodeTour: Edit Tour - 将当前活动导览置于编辑模式。此命令仅在你正在主动播放导览且尚未编辑时可见。

• CodeTour: End Tour - 结束当前活动导览。此命令仅在你正在主动录制/播放导览时可见。

• CodeTour: Resume Current Tour - 通过导航到与当前步骤关联的文件/行号来恢复当前演示。仅在您正在主动录制/播放演示时，此命令才可见。

• CodeTour: Add Tour Step - 在活动演示的当前步骤之后添加一个新的仅内容步骤。仅在您正在主动录制演示时，此命令才可见。

配置设置

CodeTour 扩展提供以下设置：

• Codetour > Prompt For Workspace Tours - 指定在首次打开包含演示的工作区时是否显示通知。

• Codetour > Record Mode - 指定在录制新演示时希望如何将演示步骤与代码关联。可以是 lineNumber 或 pattern。默认值为 lineNumber。

• Codetour > Show Markers - 指定是否显示演示标记。默认值为 true。

• Codetour > Custom Tour Directory - 指定在打开的工作区中可存储演示的自定义目录路径的名称（例如 docs/tours）。

键绑定

除了现有命令外，Code Tour 扩展还提供以下命令，这些命令在您正在进行演示时是有效的：

Windows/Linux	macOS	描述
ctrl+right	cmd+right	移动到演示中的下一步
ctrl+left	cmd+left	移动到演示中的上一步
ctrl+down ctrl+down	cmd+down cmd+down	结束当前演示
ctrl+up ctrl+up	cmd+up cmd+up	开始新演示

扩展 API

为了使其他扩展能够贡献/管理它们自己的代码演示，CodeTour 扩展公开了以下方法的 API：

• startTour(tour: CodeTour, stepNumber: number, workspaceRoot: Uri, startInEditMode: boolean = false, canEditTour: boolean): void - 启动指定的演示，在特定步骤和使用特定工作区根路径解析相对文件路径时启动。此外，您可以指定演示是否应以编辑/录制模式启动，以及演示是否可编辑。一旦演示启动，最终用户可以像使用“普通”演示一样，通过状态栏、命令面板、键绑定和注释 UI 导航和编辑演示。

• startTourByUri(tourUri: vscode.Uri, stepNumber?: number = 0): void - 与上述相同，但允许指定文件 Uri，并且可选择指定步骤编号。

• endCurrentTour(): void - 结束当前正在运行的演示（如果有）。请注意，这只是以编程方式结束演示的方法，最终用户也可以像往常一样通过命令面板（运行 CodeTour: End Tour 命令）或注释 UI（点击红色方块停止图标）结束演示。

• exportTour(tour: CodeTour): Promise<string> - 将 CodeTour 实例导出为完全嵌入的导览文件，然后可以将其写入某些持久存储（例如 GitHub Gist）。

除了前述功能外，扩展 API 还允许订阅以下导览事件：

• onDidStartTour(([tour: CodeTour, stepNumber: number]) => void): Disposable - 注册一个回调函数，每当导览开始或导航时触发。提供的回调函数会接收一个 CodeTour 实例以及当前可见的步骤编号。

• onDidEndTour((tour: CodeTour) => void): Disposable - 注册一个回调函数，每当导览结束时触发。提供的回调函数会接收一个 CodeTour 实例，该实例表示已结束导览的元数据。

// Check if the end-user has the CodeTour extension installed.
const codeTourExtension = vscode.extensions.getExtension(
  "vsls-contrib.codetour"
);
if (codeTourExtension) {
  // Grab the extension API.
  const codeTourApi = codeTour.exports;

  // Use the API object as needed
  codeTourApi.onDidStartTour(([tour, stepNumber]) => {
    console.log("Tour started: ", tour.title);
  });

  codeTourApi.onDidEndTour(tour => {
    console.log("Tour ended: ", tour.title);
  });
}