天下事有难易乎?为之,则难者亦易矣;不为,则易者亦难矣。

牛逼!微软新出的写代码神器…

itzoo 549次浏览 0个评论

点击“ 终码一生 ”, 关注,置顶 公众号

每日技术干货,第一时间送达!



【导语】: CodeTour(代码之旅)是微软官方开发的 VS Code 扩展,允许记录和回放代码的演练和思路。



1

简介


CodeTour 是一个 VS Code 插件,允许记录和回放代码库的演练和思路。 我们通常都是通过代码注释或者文档来解释某段代码或方法的功能及逻辑,这样的方法相对简便,但是对阅读的人来说还不够友好,CodeTour 允许我们为代码添加备注,并且将这些备注串联起来,动态地展示我们的思路以及代码逻辑。


就像一个目录,可以轻松地加入到新的项目/功能,并且可视化错误报告或了解代码审查/PR 更改的上下文。 “code tour”只是一系列交互步骤,每个步骤都与特定目录或文件/行进行关联,并包括对相应代码的描述。 开发人员可以 clone 一个仓库,然后立即开始学习,而无需参考 CONTRIBUTING.md 文件或依赖他人的帮助。


VSCode 地址:

https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour

项目地址:

https://github.com/microsoft/codetour


 

2

入门


录制


单击树视图中的 + 按钮 CodeTour(如果它可见)或运行 CodeTour: Record Tour 命令。 这将启动 CodeTour,这时候我们可以开始打开文件,单击要注释的行的“注释栏”,然后添加相应的描述。 添加任意数量的步骤,完成后,单击停止。


录制时,CodeTour 树状视图将显示当前录制的预览,以及当前的一组步骤。 可以知道当前正在进行哪个 tour 的录制。


如果需要在录制时编辑或删除步骤,单击 … 步骤描述旁边的菜单,然后选择适当的操作,也可以从 CodeTour 树视图中查找编辑/删除步骤。


工作区


在录制时,系统会要求选择要将 tour 文件保存到的文件夹。 这是必要的,因为 tour 作为文件写入工作区,需要明确 tour 应保存到哪个文件夹。












代码之旅 🗺️

CodeTour 是一个 Visual Studio Code 扩展,它允许您记录和回放代码库的指导演练。 它就像一个虚拟的棕色袋子或目录,可以更轻松地加入(或重新加入! )新项目/功能区域、可视化错误报告或了解代码审查/PR 更改的上下文。 “代码之旅”只是一系列交互步骤,每个步骤都与特定目录或文件/行相关联,并包括对相应代码的描述。 这允许开发人员克隆一个 repo,然后立即开始学习它,而无需参考CONTRIBUTING.md文件和/或依赖他人的帮助。 可以将游览签入存储库,以便与其他贡献者共享,或导出 到“游览文件”,它允许任何人重播相同的游览,而无需克隆任何代码来执行此操作!




入门

首先,安装CodeTour 扩展程序,然后按照以下指南之一进行操作,具体取决于您是要录制还是回放游览:


开始游览

导航之旅

录音导览

出口旅游

参考

开始游览

要开始游览,只需打开包含一个或多个游览的代码库。 如果这是您第一次打开此代码库,您将看到一个 Toast 通知,询问您是否愿意浏览它。




否则,您可以通过以下任何一种方法手动开始游览:


在活动选项卡的CodeTour视图中选择游览(或特定步骤)Explorer



运行CodeTour: Start Tour 命令,然后选择您想参加的游览



如果当前工作区只有一个代码游览,则此命令将自动启动该游览。 否则,您将看到一个可供选择的旅游列表。


开幕式

除了参加当前打开的工作区中的导览之外,您还可以打开其他人发送给您和/或您自己创建的导览文件。 只需运行CodeTour: Open Tour File…命令和/或单击CodeTour树视图标题栏中的文件夹图标。


注意: CodeTour树状视图仅在当前打开的工作区有任何导览和/或您当前正在进行导览时才会出现。


此外,如果有人导出了游览,并将其上传到可公开访问的位置,他们可以向您发送 URL,您可以通过运行CodeTour: Open Tour URL…命令打开它。


旅游标志

在浏览代码库时,您可能会遇到一个“游览标记”,它在文件装订线中显示 CodeTour 图标。 这表明一行代码参与了开放工作区的游览,这使得更容易发现可能与您当前工作相关的游览。 当您看到标记时,只需将鼠标悬停在该线上并单击Start Tour悬停工具提示中的链接即可。 这将在特定步骤开始与这行代码相关联的游览。




如果要禁用游览标记,可以执行以下操作之一:


运行CodeTour: Hide Tour Markers命令

单击CodeTour树视图标题栏中的“眼睛图标”

将codetour.showMarkers配置设置设置为false。 请注意,上述两个操作会自动为您执行此操作。

导航之旅

开始游览后,评论 UI 将引导您,并包含允许您执行以下操作的导航操作:


Move Previous- 导航到当前游览的上一步。 此命令在步骤 #2 及更高版本中可见。

Move Next- 导航到当前游览的下一步。 此命令对所有步骤可见,但巡视中的最后一个步骤除外。

Edit Tour- 开始编辑当前游览(有关详细信息,请参阅创作)。 请注意,并非所有导览都是可编辑的,因此根据您开始导览的方式,您可能会也可能不会看到此操作。

End Tour – 结束当前游览并删除评论 UI。



此外,您可以使用ctrl+right/ ctrl+left(Windows/Linux) 和cmd+right/ cmd+left(macOS) 键盘快捷键在导览中前后移动。 该CodeTour树视图和状态栏也保持同步与您当前旅游/步,以帮助开发人员轻松地了解他们是在更广泛的旅游语境。




如果您离开当前步骤并需要继续,您可以通过以下任何操作来实现:


右键单击CodeTour树中的活动游览并选择Resume Tour

单击CodeTour状态栏项

CodeTour: Resume Tour在命令面板中运行命令

您可以随时通过以下操作之一结束当前的代码游览:


单击当前步骤注释中的停止按钮(红色方块)

单击CodeTour树中活动游览旁边的停止按钮

CodeTour: End Tour在命令面板中运行命令

录音导览

如果您想为您的代码库记录代码浏览,您只需单击树视图中的+按钮CodeTour(如果它可见)和/或运行CodeTour: Record Tour命令。 这将启动游览记录器,它允许您开始打开文件,单击要注释的行的“注释栏”,然后添加相应的描述(包括降价! )。 添加任意数量的步骤,然后完成后,只需单击停止游览操作(红色方块按钮)。 您还可以创建目录步骤或内容步骤以向导览添加介绍性或中间说明。


在您录制时,CodeTour 树状视图将显示当前录制的游览,以及当前的一组步骤。 您可以知道正在录制哪个巡演,因为它的名称左侧会有一个麦克风图标。




如果您需要在录制时编辑或删除步骤,请单击…步骤描述旁边的菜单,然后选择适当的操作。 或者,您可以从 CodeTour树视图中编辑/删除步骤。




工作区

如果您在“多根工作区”中录制游览,系统会要求您选择要将游览保存到的文件夹。 这是必要的,因为游览作为文件写入您的工作区,因此我们需要消除游览应保存到哪个文件夹的歧义。 也就是说,当您录制游览时,您可以添加跨越工作区中任何文件夹的步骤,这允许您为特定文件夹创建游览和/或演示跨工作区中多个文件夹的概念。


步骤标题

默认情况下,CodeTour树使用以下显示名称格式显示每个游览步骤: #<stepNumber> – <filePath>. 但是,如果您想给步骤一个更友好/更容易识别的名称,您可以使用以下方法之一:


右键单击CodeTour树中的步骤并选择Change Title

使用您喜欢的任何标题级别(例如、 等)#,编辑该步骤的描述并在其顶部添加一个 Markdown 标题##。 例如,如果您添加一个描述以 开头### Activation的步骤,步骤和树视图将如下所示:



文本选择

默认情况下,每个步骤都与您创建注释的代码行相关联(即您+在注释栏上单击的行)。 但是,如果您想在步骤中调用特定范围的代码,只需在添加步骤之前突出显示代码(单击Add Tour to Step按钮),所选内容将作为步骤的一部分被捕获。




如果您需要调整与步骤关联的选择,只需编辑步骤、重置选择然后保存即可。


重新安排步骤

在录制游览时,您添加的每个新步骤都将附加到游览的末尾。 但是,您可以通过执行以下操作之一按顺序上下移动现有步骤:


将鼠标悬停在CodeTour树中的步骤上,然后单击向上/向下箭头图标

右键单击CodeTour树中的步骤并选择Move Up或Move Down菜单项

单击…步骤注释 UI 中的菜单,然后选择Move Up或Move Down

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


删除步骤

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


右键单击CodeTour树中的步骤并选择Delete Step

导航到重播/评论 UI 中的步骤,选择…评论说明旁边的菜单并选择Delete Step

如果您需要删除多个步骤,CodeTour树状结构支持多选,因此您可以Cmd+click(macOS)/ Ctrl+click(Windows/Linux)多个步骤节点,然后右键单击它们并选择Delete Step。


编辑游览

如果要编辑现有游览,只需右键单击CodeTour树中的游览并选择Edit Tour。 或者,您可以通过单击当前步骤注释栏中的铅笔图标或运行CodeTour: Edit Tour命令来编辑您正在查看的游览。


在任何时候,您都可以右键单击CodeTour树中的游览并通过选择Change Title、Change Description或Change Git Ref菜单项来更改其标题、描述或 git ref 。 此外,您可以通过在CodeTour树中右键单击游览并选择 来删除游览Delete Tour。


初级旅游

代码库可以包含一个或多个导览,但它可能有一个主要导览,供新开发人员开始使用。 这样,当他们第一次打开代码库时,他们可以立即看到这次巡演,而不是所有巡演的列表。


要将特定游览标记为主要游览,只需在CodeTour树中右键单击它,然后选择Make Primary。 当您将游览标记为主要游览时,任何其他标记为主要游览的游览将更新以删除该注释。 此外,如果您想手动取消将游览标记为主要游览,您可以右键单击它并选择Unmake Primary。


CodeTour 风格的 Markdown

当您描述一个步骤时,您可以使用全面的降价功能来编写丰富/引人注目的内容(例如图像、链接、标题、代码围栏)。 但是,CodeTour 还提供了一些额外的语法功能,允许您为您的旅行添加额外的交互性:



步骤标题


默认情况下,CodeTour 树使用以下显示名称格式显示每个游览步骤:


# 步骤-文件名
#<stepNumber> - <filePath>


如果想给步骤一个更友好/更容易识别的名称,可以使用以下方法之一:


  • 右键单击 CodeTour 树中的步骤并选择 Change Title

  • 支持 Markdown 语法,可以使用任何标题级别。 例如,如果添加一个描述以 ### Activation 开头的步骤,步骤和树视图将如下所示:



选择文本


默认情况下,每个步骤都与创建注释的代码行相关联,但是,如果想调出特定范围的代码作为步骤的一部分,只需在添加步骤之前突出显示代码(单击 Add Tour to Step 按钮),所选内容将作为步骤的一部分被捕获。


调整录制步骤


在录制时,添加的每个新步骤都将附加到录制的末尾,可以通过执行以下操作之一按顺序上下移动现有步骤:


  • 将鼠标悬停在 CodeTour 树中的步骤上,然后单击向上/向下箭头图标

  • 右键单击 CodeTour 树中的步骤并选择 Move Up 或 Move Down 菜单项

  • 单击 … 步骤注释 UI 中的菜单,然后选择 Move Up 或 Move Down

如果想在录制中间添加一个新步骤,只需导航到要在其后插入新步骤。


代码块


可以将 Markdown 代码块添加到步骤的正文内容,则 CodeTour 播放器将 Insert Code 在其下方呈现一个链接,该链接允许查看器自动将代码片段插入当前文件中与步骤关联的行,使得 CodeTour 创建交互式教程或示例变得容易。


Shell 命令


为了更简单地将 shell 命令嵌入到一个步骤中(例如执行构建、运行测试、启动应用程序),CodeTour 支持一个特殊的 >> 符号,在后面紧跟想要运行的 shell 命令(例如 >> npm run compile)。 这将被转换为一个超链接,当点击该链接时,将启动一个新的集成终端并运行指定的命令。


 

3

开启 Tour


要开始预览,只需打开包含一个或多个 tour 的代码库。 通过以下任意一种方法都可以开始一个 tour:


  • 在活动选项卡的 CodeTour 视图中选择 Explorer



  • 运行CodeTour: Start Tour 命令,然后选择想启用的 tour


PS: 防止找不到本篇文章,可以收藏点赞,方便翻阅查找哦。


往期推荐



新版 IntelliJ IDEA2021.3 即将来袭,这次又出了哪些神仙功能!

为什么国内 996 干不过国外的 955呢?

每日开源 | 告别造轮子,试试这个单点登录框架…

字节二面: 说说 SpringMVC 工作原理! !

真的坑,这个 MySQL 的 bug 99% 的人会踩!

这几款国产开源项目! 是真滴牛逼…



ITZOO版权所有丨如未注明 , 均为原创丨转载请注明来自IT乐园 ->牛逼!微软新出的写代码神器…
发表我的评论
取消评论
表情 贴图 加粗 删除线 居中 斜体 签到

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址