我不知道的 VSCode 扩展:交互面板的无限可能

757 字 13 min read
前端开发 VSCode 扩展开发 Webview OutputChannel 交互面板

引言

🚀 在前几篇文章中，我们学习了 VSCode 扩展开发的基础知识，以及如何添加菜单、视图和状态栏等用户界面元素。今天，我们将更进一步，探索 VSCode 扩展中两种强大的交互面板:Webview 和 输出通道 (Output Channel)。它们能为你的扩展带来更丰富的用户交互和信息展示方式,使扩展功能更加强大和灵活。让我们一起开启交互面板的无限可能！

Webview:打造自定义的交互界面

🌐 Webview 允许你在 VSCode 中嵌入完整的 Web 页面。这意味着你可以使用 HTML, CSS, JavaScript 等 Web 技术，在 VSCode 内部创建高度自定义的交互界面。Webview 非常适合展示复杂的数据可视化、创建自定义编辑器、或者集成 Web 应用到 VSCode 中。

创建和显示 Webview

🛠️ 要创建和显示 Webview，我们需要使用 vscode.window.createWebviewPanel() 方法。

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    // ...

    let disposable = vscode.commands.registerCommand('extension.showWebview', () => {
        // 创建 Webview 面板
        const panel = vscode.window.createWebviewPanel(
            'myWebview', // Webview 的标识符，用于区分不同的 Webview
            '我的 Webview', // Webview 面板的标题
            vscode.ViewColumn.One, // Webview 面板显示的位置，例如 ViewColumn.One, ViewColumn.Two, ViewColumn.Beside
            {
                enableScripts: true, // 启用 JavaScript 脚本
                retainContextWhenHidden: true // 隐藏时保持 Webview 状态
            }
        );

        // 设置 Webview 内容
        panel.webview.html = getWebviewContent();
    });

    context.subscriptions.push(disposable);
}

function getWebviewContent() {
    return `<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>我的 Webview</title>
</head>
<body>
    <h1>Hello Webview!</h1>
    <p>This is a webview created by VSCode extension.</p>
</body>
</html>`;
}

  • vscode.window.createWebviewPanel(viewType, title, showOptions, options): 创建 Webview 面板。

    • viewType: Webview 的标识符，字符串类型，用于在 VSCode 中唯一标识你的 Webview。
    • title: Webview 面板的标题，显示在面板的标签页上。
    • showOptions: 控制 Webview 面板的显示位置，vscode.ViewColumn 枚举类型，例如 ViewColumn.One, ViewColumn.Two, ViewColumn.Beside (在当前编辑器旁边打开)。
    • options: Webview 的配置选项，对象类型。
      • enableScripts: 是否启用 Webview 中的 JavaScript 脚本，布尔值，默认为 false。通常需要设置为 true 以实现交互功能。
      • retainContextWhenHidden: 当 Webview 面板被隐藏 (例如切换到其他面板) 时，是否保持 Webview 的状态 (例如 JavaScript 运行状态、DOM 状态)，布尔值，默认为 false。如果需要保持 Webview 状态，建议设置为 true，避免每次显示 Webview 都重新加载。

  • panel.webview.html: 设置 Webview 的 HTML 内容，字符串类型。你可以直接设置 HTML 字符串，也可以加载外部 HTML 文件。

Webview 与扩展通信

✉️ Webview 运行在独立的上下文中，与扩展主进程之间需要通过消息传递进行通信。VSCode 提供了 webview.postMessage() 和 webview.onDidReceiveMessage API 来实现双向通信。

  1. 扩展发送消息到 Webview: 使用 panel.webview.postMessage(message) 方法，将消息发送到 Webview。message 可以是任意 JavaScript 对象。

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

// 发送消息到 Webview
panel.webview.postMessage({ command: 'hello', text: 'Hello from Extension!' });

  2. Webview 接收消息: 在 Webview 的 JavaScript 代码中，监听 message 事件，接收来自扩展的消息。

    <!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Webview 示例</title>
</head>
<body>
    <div id="message-container"></div>
    <script>
        const messageContainer = document.getElementById('message-container');

        // 监听 message 事件
        window.addEventListener('message', event => {
            const message = event.data; // 消息内容

            switch (message.command) {
                case 'hello':
                    messageContainer.textContent = message.text;
                    break;
            }
        });
    </script>
</body>
</html>

  3. Webview 发送消息到扩展: 在 Webview 的 JavaScript 代码中，使用 vscode.postMessage(message) 方法，将消息发送回扩展。注意:这里的 vscode 对象是由 VSCode 注入到 Webview 中的全局对象，需要确保 enableScripts: true 选项已启用。

    <!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Webview 示例</title>
</head>
<body>
    <button id="send-button">发送消息给扩展</button>
    <script>
        const sendButton = document.getElementById('send-button');

        sendButton.addEventListener('click', () => {
            // 发送消息给扩展
            vscode.postMessage({ command: 'webview-message', text: 'Hello from Webview!' });
        });
    </script>
</html>

  4. 扩展接收消息: 在扩展代码中，监听 panel.webview.onDidReceiveMessage 事件，接收来自 Webview 的消息。

    // ...
panel.webview.onDidReceiveMessage(
    message => {
        switch (message.command) {
            case 'webview-message':
                vscode.window.showInformationMessage(`Webview message: ${message.text}`);
                return;
        }
    },
    undefined,
    context.subscriptions
);
Webview 安全性

⚠️ Webview 安全性 是一个非常重要的问题。由于 Webview 可以执行任意 HTML, CSS, JavaScript 代码，如果 Webview 内容来源不可信，可能会存在安全风险，例如跨站脚本攻击 (XSS)。

为了提高 Webview 安全性，你需要注意以下几点:

  • 限制 Webview 权限: 在创建 Webview 面板时，尽量限制 Webview 的权限，例如禁用本地文件系统访问、禁用 Node.js API 等。
  • 内容安全策略 (CSP): 使用内容安全策略 (CSP) 来限制 Webview 可以加载的资源来源，防止恶意脚本注入。
  • 输入验证和输出编码: 对 Webview 接收的用户输入进行严格的验证，并对输出到 Webview 的内容进行 HTML 编码，防止 XSS 攻击。
  • 避免加载外部不可信内容: 尽量避免在 Webview 中加载来自外部不可信来源的内容，例如用户上传的 HTML 文件、不可信的 CDN 资源等。

示例:创建简单的 Webview 交互

📝 按照上述步骤，我们创建了一个简单的 Webview 示例，实现了扩展和 Webview 之间的双向通信。

  1. 注册命令 extension.showWebview: 在 package.json 中注册命令 extension.showWebview，并在 extension.ts 中实现命令处理函数，创建和显示 Webview 面板 (参考上面的代码示例)。

  2. 创建 getWebviewContent 函数: 在 extension.ts 中创建 getWebviewContent 函数，返回 Webview 的 HTML 内容 (参考上面的代码示例)。

  3. 实现 Webview 接收消息: 在 webview.html 中，编写 JavaScript 代码，监听 message 事件，接收并处理来自扩展的消息 (参考上面的代码示例)。

  4. 实现 Webview 发送消息: 在 webview.html 中，编写 JavaScript 代码，监听按钮点击事件，调用 vscode.postMessage() 方法发送消息给扩展 (参考上面的代码示例)。

  5. 实现扩展接收消息: 在 extension.ts 中，监听 panel.webview.onDidReceiveMessage 事件，接收并处理来自 Webview 的消息 (参考上面的代码示例)。

  6. 重新加载扩展: 重新加载 VSCode 窗口。

  7. 测试: 执行命令 extension.showWebview，打开 Webview 面板。你将在 Webview 中看到 "Hello Webview!" 标题，以及来自扩展的消息 "Hello from Extension!" (如果已实现消息接收)。点击 Webview 中的 "发送消息给扩展" 按钮，你将在 VSCode 右下角看到来自 Webview 的消息 "Webview message: Hello from Webview!" (如果已实现消息发送和接收)。

输出通道 (Output Channel):展示扩展日志和信息

📺 输出通道 (Output Channel) 是 VSCode 中用于展示扩展输出信息和日志的面板。你可以使用输出通道来显示扩展的运行状态、调试信息、错误日志等。输出通道支持多种输出格式，例如纯文本、Markdown、JSON 等，并可以方便地进行日志记录和查看。

创建和显示输出通道

🛠️ 要创建和显示输出通道，我们需要使用 vscode.window.createOutputChannel() 方法。

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    // ...

    // 创建输出通道
    const outputChannel = vscode.window.createOutputChannel('My Output Channel');

    let disposable = vscode.commands.registerCommand('extension.showOutputChannel', () => {
        // 显示输出通道
        outputChannel.show(true); // true: 保持焦点在输出通道，false: 不保持焦点
    });
    context.subscriptions.push(disposable);

    // 输出信息到输出通道
    outputChannel.appendLine('Extension "xxx" is now active!');
    outputChannel.appendLog('This is a log message.'); // VSCode 1.75+
    outputChannel.appendInfo('This is an info message.'); // VSCode 1.75+
    outputChannel.appendWarn('This is a warning message.'); // VSCode 1.75+
    outputChannel.appendError('This is an error message.'); // VSCode 1.75+
    outputChannel.appendObject({ key: 'value' }); // 输出 JSON 对象
}

  • vscode.window.createOutputChannel(name, options): 创建输出通道。

    • name: 输出通道的名称，显示在 "输出" 面板的下拉列表中。
    • options: 输出通道的配置选项，可选。目前没有常用选项。

  • outputChannel.show(preserveFocus): 显示输出通道面板。

    • preserveFocus: 布尔值，可选，默认为 false。true 表示显示输出通道时，焦点保持在输出通道面板；false 表示不保持焦点，焦点仍然在之前激活的编辑器或视图。

  • outputChannel.append(value): 向输出通道追加文本，不换行。

  • outputChannel.appendLine(value): 向输出通道追加文本，并换行。

  • outputChannel.appendLog(value): 向输出通道追加日志消息 (VSCode 1.75+)。日志消息在输出通道中会以 "日志" 级别显示，并带有时间戳和图标。

  • outputChannel.appendInfo(value): 向输出通道追加信息消息 (VSCode 1.75+)。信息消息在输出通道中会以 "信息" 级别显示，并带有时间戳和图标。

  • outputChannel.appendWarn(value): 向输出通道追加警告消息 (VSCode 1.75+)。警告消息在输出通道中会以 "警告" 级别显示，并带有时间戳和图标。

  • outputChannel.appendError(value): 向输出通道追加错误消息 (VSCode 1.75+)。错误消息在输出通道中会以 "错误" 级别显示，并带有时间戳和图标。

  • outputChannel.appendObject(value): 向输出通道追加 JSON 对象，对象会被格式化为 JSON 字符串并输出。

  • outputChannel.clear(): 清空输出通道的内容。

  • outputChannel.dispose(): 销毁输出通道，释放资源。

示例:创建简单的输出通道

📝 按照上述步骤，我们创建了一个简单的输出通道示例，演示了如何创建、显示输出通道，以及如何输出不同类型的信息。

  1. 创建输出通道: 在 activate 函数中使用 vscode.window.createOutputChannel() 创建输出通道 (参考上面的代码示例)。

  2. 注册命令 extension.showOutputChannel: 在 package.json 中注册命令 extension.showOutputChannel，并在 extension.ts 中实现命令处理函数，显示输出通道 (参考上面的代码示例)。

  3. 输出信息到输出通道: 在 activate 函数中使用 outputChannel.appendLine(), outputChannel.appendLog(), outputChannel.appendInfo(), outputChannel.appendWarn(), outputChannel.appendError(), outputChannel.appendObject() 等方法，向输出通道输出不同类型的信息 (参考上面的代码示例)。

  4. 重新加载扩展: 重新加载 VSCode 窗口。

  5. 测试: 执行命令 extension.showOutputChannel，打开 "输出" 面板，并在下拉列表中选择 "My Output Channel"。你将在输出通道中看到我们输出的各种信息，包括不同级别的日志消息和 JSON 对象。

总结

🎉 恭喜你，又掌握了 VSCode 扩展开发的两个重要技能:创建 Webview 和 使用输出通道。Webview 让你能够创建高度自定义的交互界面，而输出通道则方便你展示扩展的日志和信息。合理运用这两种交互面板，你的 VSCode 扩展将会变得更加强大和易用。在接下来的文章中，我们将继续探索 VSCode 扩展的更多高级功能，敬请期待！