1. 简介

Todo Tree 是一个功能强大的 Visual Studio Code 扩展，它能够快速搜索工作区中的注释标签（如 TODO、FIXME 等），并将它们以树状视图的形式展示在活动栏中。通过点击树视图中的条目，可以直接跳转到代码中对应的位置。此外，Todo Tree 还支持在打开的文件中高亮显示这些标签。

2. 安装

从 Visual Studio Code 内部安装

1. 打开 VS Code。
2. 按下 Ctrl+P (Windows/Linux) 或 Cmd+P (macOS)。
3. 输入 ext install Gruntfuggly.todo-tree 并按回车键。
4. 点击安装按钮。

从 Visual Studio Marketplace 安装

您也可以直接访问Visual Studio Marketplace 上的 Todo Tree 页面并点击“安装”按钮。

3. 基本用法

安装并启用 Todo Tree 后，您会在 VS Code 的活动栏中看到一个 Todo Tree 图标。点击该图标即可打开 Todo Tree 视图。默认情况下，它会搜索工作区中的 TODO 和 FIXME 标签。

在代码中添加类似 // TODO: 完成此功能 或 /* FIXME: 修复此 bug */ 的注释，Todo Tree 就会自动识别并显示在树视图中。

4. 配置

Todo Tree 提供了丰富的配置选项，可以通过 VS Code 的设置界面（文件 > 首选项 > 设置 或 Code > 首选项 > 设置）进行配置。搜索 todo-tree 即可找到所有相关设置。

4.1. 标签 (Tags)

默认情况下，Todo Tree 搜索 TODO 和 FIXME。您可以通过 todo-tree.general.tags 设置自定义或添加更多标签。

示例:

"todo-tree.general.tags": [  "TODO",  "FIXME",  "BUG",  "HACK",  "NOTE"]

4.2. 高亮 (Highlighting)

Todo Tree 允许您为不同的标签自定义高亮样式，包括前景色、背景色、字体样式、图标等。高亮配置分为 defaultHighlight（默认高亮）和 customHighlight（自定义高亮）。

todo-tree.highlights.defaultHighlight

用于设置所有标签的默认高亮样式。如果 customHighlight 中未指定某个标签的样式，则会使用此处的默认值。

可用设置项:

• foreground: 前景色。
• background: 背景色。
• opacity: 背景色的不透明度（0-100%）。
• fontWeight, fontStyle, textDecoration: 字体样式。
• borderRadius: 背景的边框圆角。
• icon: 树视图中显示的图标。可以是 Octicon (https://octicons.github.com) 或 Codicon (https://microsoft.github.io/vscode-codicons/dist/codicon.html)。Codicon 格式为 $(icon_name)。也可以使用 todo-tree 或 todo-tree-filled。
• iconColour: 图标颜色。
• gutterIcon: 是否在编辑器行号旁显示图标。
• rulerColour: 概览标尺（overview ruler）中的标记颜色。
• rulerOpacity: 概览标尺标记的不透明度。
• rulerLane: 概览标尺标记的位置（left, center, right, full, none）。
• type: 高亮类型，控制高亮范围。可选值包括 tag, text, tag-and-comment, tag-and-subTag, text-and-comment, line, whole-line, capture-groups:n,m…, none。
• hideFromTree: 是否在树视图中隐藏此标签。
• hideFromStatusBar: 是否在状态栏计数中排除此标签。
• hideFromActivityBar: 是否在活动栏徽章计数中排除此标签。

颜色格式: 可以使用 HTML/CSS 颜色名称（如Salmon）、RGB 十六进制值（如 #80FF00）、RGB CSS 样式值（如 rgb(255,128,0)）或主题颜色（如 peekViewResult.background）。十六进制和 RGB 值还可以指定透明度（如 #ff800080 或 rgba(255,128,0,0.5)）。

todo-tree.highlights.customHighlight

用于为特定标签设置自定义高亮样式。如果在此处为某个标签设置了样式，它将覆盖 defaultHighlight 中的相应设置。

示例:

"todo-tree.highlights.defaultHighlight": {    "icon": "alert",    "type": "text",    "foreground": "red",    "background": "white",    "opacity": 50,    "iconColour": "blue"},"todo-tree.highlights.customHighlight": {    "TODO": {        "icon": "check",        "type": "line",        "foreground": "#00FF00"    },    "FIXME": {        "foreground": "black",        "iconColour": "yellow",        "gutterIcon": true    },    "BUG": {        "icon": "bug",        "foreground": "#FF0000",        "type": "whole-line"    }}

4.3. 正则表达式 (Regex)

Todo Tree 使用正则表达式来匹配文件中的标签。您可以通过 todo-tree.regex.regex 设置自定义正则表达式。

重要提示:

•如果在 settings.json 中直接修改设置，需要对反斜杠进行转义（例如 \ 写成 \\）。

•如果在设置 GUI 中修改，则只需要一个反斜杠。

示例 (匹配 TODO 和 FIXME):

"todo-tree.regex.regex": "(//|#|<!--|;|/\\*|^)\s*($TAGS)"

其中 $TAGS 是一个占位符，会被 todo-tree.general.tags 中定义的标签列表替换。

多行正则表达式示例:

"todo-tree.regex.regex": "((//|#|;)[ ]*($TAGS)[^\\n]*)|(/\\*(\\*?\\s*)*($TAGS)(.|\\n|\\r)*?\\*/)|(<!--\\s*($TAGS)(.|\\n|\\r)*?-->)"

这个复杂的正则表达式可以匹配单行注释、多行 /* … */ 注释和  HTML 注释中的标签。

4.4. 过滤 (Filtering)

Todo Tree 允许您通过 todo-tree.filtering.excludeGlobs 设置来排除不需要扫描的文件或文件夹。

示例:

"todo-tree.filtering.excludeGlobs": [    "**/node_modules/**",    "**/dist/**",    "**/.vscode/**",    "**/*.min.*",    "**/*.map"]

4.5. 视图控制 (View Controls)

Todo Tree 视图的头部包含多个按钮，用于控制视图的显示方式：

•折叠所有节点 / 展开所有节点

•显示为平面列表：每个 TODO 显示完整的文件名。

•显示为标签列表：按标签分组显示。

•显示为树状视图：按文件夹结构显示（默认）。

•按标签分组 / 取消按标签分组

•按文件组织 / 取消按文件组织

•过滤：根据输入的文本过滤显示项。

•移除过滤器

•重建树

•仅显示打开文件中的标签

•仅显示当前文件中的标签

•仅显示工作区中的标签

•显示工作区和打开文件中的标签

•在树中显示当前文件

•导出树内容到文件

4.6. 文件夹过滤上下文菜单

在树视图中右键点击文件夹或文件，可以访问上下文菜单，提供以下选项：

•隐藏此文件夹/文件：从树中移除。

•仅显示此文件夹：只显示该文件夹及其内容。

•仅显示此文件夹及子文件夹：显示该文件夹及其所有子文件夹。

•重置文件夹过滤器：清除所有文件夹过滤器。

•切换徽章：启用/禁用 SCM 装饰。

•切换紧凑文件夹：启用/禁用压缩的文件夹名称。

•切换项目计数：启用/禁用标签计数。

•仅扫描打开的文件：只扫描 VS Code 中打开的文件。

•仅扫描当前文件：只扫描当前打开的文件。

•扫描工作区和打开的文件：扫描工作区和所有打开的文件。

•仅扫描工作区：只扫描工作区（需要手动刷新）。

•展开树/折叠树

•显示树状视图/平面视图/仅标签视图

•按标签分组/取消按标签分组

•按子标签分组/取消按子标签分组

•导出树…

5. 实际应用示例

5.1. 常见 TODO/FIXME 标记

在您的代码中，使用 TODO: 或 FIXME: 标记需要处理的任务。

# TODO: Implement user authenticationdef login_user(username, password):    pass# FIXME: This function has a known bug when handling empty inputdef process_data(data):    if not data:        # BUG: This might cause an error later        return []    # HACK: Temporary solution, refactor later    return [item.upper() for item in data]

5.2. 自定义标签与高亮

假设您想追踪 BUG 和 REVIEW 标签，并为它们设置不同的高亮样式。

settings.json 配置:

{  "todo-tree.general.tags": [    "TODO",    "FIXME",    "BUG",    "REVIEW"  ],  "todo-tree.highlights.customHighlight": {    "BUG": {      "icon": "bug",      "foreground": "#FF0000",      "background": "#330000",      "type": "whole-line"    },    "REVIEW": {      "icon": "eye",      "foreground": "#00BFFF",      "background": "#002233",      "type": "line"    }  }}

代码示例:

// BUG: This API call is failing intermittentlyfunction fetchData() {  // ...}// REVIEW: Check if this logic can be simplifiedconst calculateTotal = (items) => {  // ...};

5.3. 排除特定文件

如果您有一个 docs 文件夹，其中包含许多 TODO 标记，但您不希望它们出现在 Todo Tree 视图中，可以这样配置：

settings.json 配置:

{  "todo-tree.filtering.excludeGlobs": [    "**/node_modules/**",    "**/docs/**"  ]}

6. 常见问题与故障排除

•Todo Tree 不显示任何标签：

• 检查 todo-tree.general.tags 是否正确配置了您期望的标签。
• 检查 todo-tree.regex.regex 是否与您的注释格式匹配。
• 检查 todo-tree.filtering.excludeGlobs 是否排除了包含您标签的文件或文件夹。
• 尝试点击 Todo Tree 视图顶部的“重建树”按钮。

•高亮不生效：

• 检查 todo-tree.highlights.defaultHighlight 和 todo-tree.highlights.customHighlight 的配置是否正确。
• 确保颜色值格式正确。

•性能问题：

• 对于大型项目，todo-tree.filtering.excludeGlobs 可以显著提高性能。
• 避免使用过于复杂的正则表达式，尤其是多行正则表达式，它们可能会影响性能。

7. 总结

Todo Tree 是一个极其实用的 VS Code 扩展，通过其灵活的配置选项，您可以根据自己的工作流程和项目需求，高效地管理代码中的待办事项和重要标记。掌握其配置，将大大提升您的开发效率。

8. 参考文献

• Gruntfuggly/todo-tree GitHub Repository [1]
• Todo Tree – Visual Studio Marketplace [2]
• Todo Tree Wiki – Configuration Examples [3]