VSCode 插件开发实战（十四）：创建交互式引导教程

前言

为了进一步提升用户体验，VSCode 提供了一些内置功能，其中之一就是 Walkthroughs（引导教程）。Walkthroughs 是一个交互式引导功能，可以帮助用户快速熟悉功能、学习新技能，甚至是进行项目配置。

本文将详细介绍如何为 VSCode 自定义插件添加 Walkthroughs 功能，以便更好地指导用户使用插件的各项功能。

什么是 Walkthroughs？

Walkthroughs 是 VSCode 中的一种交互式引导功能，它可以为用户提供逐步说明、任务列表和快捷操作，帮助用户更好地理解和使用某项功能。通过 Walkthroughs，用户可以更快地上手新工具、新插件以及新技术。

添加 Walkthroughs

接下来，我们将重点放在如何为这个插件添加 Walkthroughs。

1. 编辑 package.json

在 package.json 中，我们需要添加 Walkthroughs 的配置。找到 "contributes" 属性，并在其中添加 "walkthroughs" 配置。

clike 复制代码

"contributes": {
    "walkthroughs": [
        {
            "id": "getting-started",
            "title": "Getting Started with My Extension",
            "description": "Learn how to use the features of My Extension.",
            "steps": [
                {
                    "id": "welcome",
                    "title": "Welcome",
                    "description": "Welcome to My Extension! Let's start by exploring the basic features.",
                    "media": {
                        "image": "https://path.to/welcome-image.png",
                        "altText": "Welcome Image"
                    }
                },
                {
                    "id": "first-step",
                    "title": "First Step",
                    "description": "In this step, you will learn how to perform the first task using My Extension.",
                    "media": {
                        "markdown": "![外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传](https://img-home.csdnimg.cn/images/20230724024159.png?origin_url=https%3A%2F%2Fpath.to%2Ffirst-step-image.png&pos_id=img-bXXPArXL-1735308359521)"
                    },
                    "completionEvents": ["onCommand:myExtension.firstCommand"]
                }
            ]
        }
    ]
}

id: Walkthrough 的唯一标识符。
title: Walkthrough 的标题。
description: Walkthrough 的描述。
steps: 每个步骤的详细信息，包括 id、title、description 和 media。

2. 添加触发事件

在插件的 extension.ts 文件中，我们需要定义这些步骤中的触发事件。例如，在上面的配置中，我们有一个 completionEvent 是 onCommand:myExtension.firstCommand。我们需要在 extension.ts 中实现这个命令。

clike 复制代码

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {

    let disposable = vscode.commands.registerCommand('myExtension.firstCommand', () => {
        vscode.window.showInformationMessage('First command executed!');
    });

    context.subscriptions.push(disposable);
}

export function deactivate() {}

测试 Walkthroughs

完成以上配置后，按下 F5 运行插件，VSCode 会打开一个新的窗口，这时你可以通过命令面板（Ctrl+Shift+P 或 Cmd+Shift+P）输入"Walkthrough"，选择你的插件 Walkthroughs 来查看效果。

Walkthroughs 配置选项

为了让你能更灵活地使用这一功能，接下来我们将更深入地探讨 Walkthroughs 的配置选项和一些高级用法。

1. 步骤类型

除了前面提到的基本步骤配置，Walkthroughs 还支持多种不同的媒体类型来提高互动体验。

图片：可以通过 URL 或相对路径加载图片。
Markdown：支持嵌入 markdown 格式的内容，比如链接、图片、代码块等。
代码片段：直接在步骤中嵌入代码，用户可以点击复制。

例如：

clike 复制代码

"steps": [
    {
        "id": "markdown-example",
        "title": "Markdown Step",
        "description": "This step demonstrates how to use Markdown.",
        "media": {
            "markdown": "```javascript\nconsole.log('Hello, Walkthroughs!');\n```"
        }
    },
    {
        "id": "snippet-example",
        "title": "Code Snippet Step",
        "description": "Click the code to copy it to your clipboard.",
        "media": {
            "code": {
                "language": "javascript",
                "value": "console.log('Hello, World!');"
            }
        }
    }
]

2. 触发事件

触发事件用来标志某个步骤完成，主要有以下几种：

onCommand：当执行某个命令时触发。
onView：当用户打开某个视图时触发。
onEvent：通用事件触发器，基于 VSCode 的事件系统。

例如：

clike 复制代码

{
    "id": "second-step",
    "title": "Second Step",
    "description": "Complete this step by executing the second command.",
    "media": {
        "image": "https://path.to/second-step-image.png"
    },
    "completionEvents": ["onCommand:myExtension.secondCommand"]
}

在 extension.ts 中实现这个命令：

clike 复制代码

let secondCommand = vscode.commands.registerCommand('myExtension.secondCommand', () => {
    vscode.window.showInformationMessage('Second command executed!');
});

context.subscriptions.push(secondCommand);

3. 条件步骤

有时你可能需要根据某些条件来显示或隐藏某些步骤。可以使用 when 属性来指定显示条件。

clike 复制代码

{
    "id": "conditional-step",
    "title": "Conditional Step",
    "description": "This step will only show up if the condition is met.",
    "media": {
        "markdown": "This step is conditional."
    },
    "when": "extension.someCondition"
}

在插件代码中更新条件：

clike 复制代码

vscode.commands.executeCommand('setContext', 'extension.someCondition', true);

4. 自定义视图和面板

Walkthroughs 还可以与自定义视图和面板结合使用，为用户提供更细致的指导。例如，你可以创建一个自定义 Webview 来展示更复杂的内容。

clike 复制代码

vscode.commands.registerCommand('myExtension.showWelcome', () => {
    const panel = vscode.window.createWebviewPanel(
        'welcome',
        'Welcome',
        vscode.ViewColumn.One,
        {}
    );

    panel.webview.html = getWebviewContent();
});

function getWebviewContent() {
    return `<!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Welcome</title>
    </head>
    <body>
        <h1>Welcome to My Extension</h1>
        <p>This is a custom webview.</p>
    </body>
    </html>`;
}

在 Walkthroughs 配置中，添加一个步骤来打开这个视图：

clike 复制代码

{
    "id": "custom-view-step",
    "title": "Custom View Step",
    "description": "Click the button to open a custom view.",
    "media": {
        "markdown": "[Open Welcome View](command:myExtension.showWelcome)"
    }
}

总结

通过本篇指南，我们详细探讨了如何在 VSCode 插件中使用 Walkthroughs 功能，包括基础配置、高级技巧以及最佳实践。Walkthroughs 不仅能帮助用户快速上手你的插件，还能显著提升他们的使用体验，是一个非常值得投资的功能。