在上一篇中，我们已经基于基础的 html、css、js 完成了一个粗糙版的 to-do list demo。这一篇我们将从以下几个方面来介绍我在实战中的一些经验，并最终能重构出一个视觉效果良好的 demo。

webview 重构

在上一篇中，我们已经了解到，webview 的本质其实就是 HTML，我们只需要将包含了样式和脚本的完整 HTML 片段赋值给 WebviewView 实例的 webview.html 属性即可。基于此，那只要我们使用 webpack 或 vite 等构建工具将 react 或 vue 开发的组件构建出相应的脚本及样式文件，然后能挂载进完整的 HTML 片段中，这样我们便可以使用 react 或 vue 来开发 webview 了。理论上是可行的，下面我们就以 webpack、react 为例，来看几个关键步骤：

添加 webview.config.js

我们将多个 webview 视为多个页面，分别构建出各个 webview 的脚本及样式文件（注：这里之所以要将样式抽离出来作为独立的文件，是因为不想松懈上一篇中提到的安全策略，否则 css in js 的方式动态插入的样式将不会生效）。以下是我实践时用到的配置，大家可重点留意 entry、output、devServer 这三个属性的配置，仅供参考：

// @ts-check
"use strict";

const path = require("path");
const MiniCssExtractPlugin = require("mini-css-extract-plugin");
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin");

const resolveApp = (relativePath) => path.resolve(__dirname, relativePath);

const webviewConfig = [
  {
    name: "webview",
    target: "web",
    entry: {
      addTaskView: resolveApp("webview/views/AddTask"),
      toDoListView: resolveApp("webview/views/ToDoList"),
      doneView: resolveApp("webview/views/DoneList"),
    },
    output: {
      filename: "[name].js",
      path: resolveApp("dist"),
    },
    devtool: "source-map",
    resolve: {
      extensions: [".ts", ".js", ".tsx", ".jsx"],
      alias: {
        webview: resolveApp("webview"),
      },
    },
    module: {
      rules: [
        {
          test: /\.(ts|tsx)$/,
          exclude: /node_modules/,
          use: [
            {
              loader: "ts-loader",
            },
          ],
        },
        {
          test: /\.css$/,
          use: [
            "@ecomfe/class-names-loader",
            MiniCssExtractPlugin.loader,
            "css-loader",
            "postcss-loader",
          ],
        },
        {
          test: /\.less$/,
          exclude: /\.module\.less$/,
          use: [
            {
              loader: MiniCssExtractPlugin.loader,
              options: {
                defaultExport: true,
              },
            },
            "css-loader",
            "postcss-loader",
            {
              loader: "less-loader",
              options: {
                sourceMap: true,
                lessOptions: {
                  javascriptEnabled: true,
                },
              },
            },
          ],
        },
        {
          test: /\.module\.less$/,
          use: [
            "@ecomfe/class-names-loader",
            {
              loader: MiniCssExtractPlugin.loader,
              options: {
                defaultExport: true,
              },
            },
            {
              loader: "css-loader",
              options: {
                modules: {
                  localIdentName: "[local]_[hash:base64:5]", // 定义类名生成规则
                },
              },
            },
            "postcss-loader",
            {
              loader: "less-loader",
              options: {
                sourceMap: true,
                lessOptions: {
                  javascriptEnabled: true,
                },
              },
            },
          ],
        },
      ],
    },
    performance: {
      hints: false,
    },
    optimization: {
      minimizer: [
        // 在 webpack@5 中，你可以使用 `...` 语法来扩展现有的 minimizer（即 `terser-webpack-plugin`）
        `...`,
        new CssMinimizerPlugin(),
      ],
    },
    plugins: [new MiniCssExtractPlugin()],
    devServer: {
      compress: true,
      hot: true,
      allowedHosts: "all",
      port: 8192,
      headers: {
        "Access-Control-Allow-Origin": "*",
      },
    },
  },
];

module.exports = [webviewConfig];

优化构建脚本命令

有了构建 webview 的 webpack 配置后，再加上初始化项目后就已经存在的构建插件本身的配置，此时项目中便有了两份 webpack 配置。这里我们将并行构建插件代码和 webview 代码，以下是优化后的部分脚本命令：

{
  "scripts": {
    "watch": "run-p watch:*",
    "watch:wv": "webpack serve --mode development --config ./webview.config.js",
    "watch:ext": "webpack --mode development --watch --config ./extension.config.js",
    "package": "pnpm run clean && run-p package:*",
    "package:wv": "webpack --mode production --config ./webview.config.js --devtool hidden-source-map",
    "package:ext": "webpack --mode production --config ./extension.config.js --devtool hidden-source-map",
    "clean": "rimraf dist"
  }
}

相信大家看后便一目了然了，本地开发时我们执行 watch 脚本，会为 webview 起一个本地 server。而生产构建执行的 package 脚本，会指定环境变量为 production。

有了构建配置和命令，我们便可以从每个 webview 的入口文件开始，分别构建出各自的脚本和样式了，接下来我们就来看看这些入口文件的实现。

添加 webview 入口文件

在上面的 webview.config.js 文件的 entry 中，我们添加了三个入口文件，下面就以 addTaskView 为例，来看看它的实现：

import * as React from "react";

import { ViewType } from "webview/constants";
import { getClientRoot } from "webview/utils";

import { AddTask } from "./AddTask";

const root = getClientRoot(ViewType.addTaskView);
root.render(<AddTask />);

// Webpack HMR
if (import.meta.webpackHot) {
  import.meta.webpackHot.accept();
}

其中 getClientRoot 的实现是：

import { createRoot } from "react-dom/client";
import type { Root } from "react-dom/client";

let root: Root | null = null;

export function getClientRoot(rootId: string) {
  if (!root) {
    const container = document.querySelector(`#${rootId}`)!;
    root = createRoot(container);
  }
  return root;
}

这样我们便可以在 HTML 片段的“根节点”中渲染 AddTask 组件了。另外，为了提升开发体验，这里我们也支持了代码热更。

改造 webview html

有了前面三步，便有了各个 webview 的脚本及样式，那在 webview html 中如何加载它们呢？请看代码：

import * as vscode from "vscode";

import { ViewType, NODE_ENV_PROD } from "src/constants";
import { getUri, getNonce } from "src/utils";

const webviewInfoMap: Record<
  ViewType,
  { id: string; title: string; noStyle?: boolean; noScript?: boolean }
> = {
  [ViewType.addTaskView]: {
    id: ViewType.addTaskView,
    title: "添加待办项",
  },
  [ViewType.toDoListView]: {
    id: ViewType.toDoListView,
    title: "待办项",
  },
  [ViewType.doneView]: {
    id: ViewType.doneView,
    title: "已完成",
  },
};
const localServer = "http://localhost:8192";

export function getHtmlForWebview(
  webview: vscode.Webview,
  extensionUri: vscode.Uri,
  viewType: ViewType
) {
  let styleUri = null;
  let scriptUri = null;
  const isProduction = process.env.NODE_ENV === NODE_ENV_PROD;
  const { id, title, noStyle, noScript } = webviewInfoMap[viewType];

  if (isProduction) {
    styleUri = getUri(webview, extensionUri, ["dist", `${viewType}.css`]);
    scriptUri = getUri(webview, extensionUri, ["dist", `${viewType}.js`]);
  } else {
    styleUri = `${localServer}/${viewType}.css`;
    scriptUri = `${localServer}/${viewType}.js`;
  }

  // Use a nonce to only allow a specific script to be run.
  const nonce = getNonce();

  return `
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8">

        <!-- Use a content security policy to only allow loading styles from our extension directory, and only allow scripts that have a specific nonce. (See the 'webview-sample' extension sample for img-src content security policy  examples) -->
        <meta
          http-equiv="Content-Security-Policy"
          content=" 
            default-src 'none';
            style-src ${webview.cspSource} ${localServer};
            script-src 'nonce-${nonce}' ${localServer};
            connect-src ws://0.0.0.0:8192/ws ${localServer};
          "
        >
        <meta name="viewport" content="width=device-width, initial-scale=1.0">

        ${noStyle ? "" : `<link href="${styleUri}" rel="stylesheet">`}

        <title>To Do List Demo: ${title}</title>
      </head>
      <body>
        <div id=${id}></div>

        ${noScript ? "" : `<script nonce="${nonce}" src="${scriptUri}"></script>`}
      </body>
    </html>
  `;
}

在代码中我们首先根据环境变量判断了下是本地开发还是生产构建，本地开发的话，就从本地 server 中加载对应资源，生产构建的话，那就从构建的输出目录 dist 中加载资源。其次为了能正常加载这些资源，我们对内容安全策略也进行了按需扩展，比如对 style-src、script-src 支持了从 http://localhost:8192 加载本地 server 资源，新增了 connect-src 用以支持代码热更（更多扩展可参考 内容安全策略）。

到这里，基于 react 重构 webview 的关键步骤就介绍完了。当然如果你想使用 vue 开发 webview 或使用 vite、esbuild 等构建工具构建资源，思路都是一样的，放心尝试即可。

使用组件库

有了 webpack 来构建 webview 代码，开发这些 webview 也终于可以像我们开发普通的 web 项目一样了，各种组件库、工具库都可以拿来用了。但为了和 vscode 整体风格匹配，这一节我们会以 vscode-webview-ui-toolkit 为例，看看它的接入使用流程。（注：因为一些 客观因素 该组件库即将废弃，正式项目使用需慎重）

安装

pnpm install @vscode/webview-ui-toolkit -D

使用

由于该组件库支持了 react 版本，因此可以直接从 @vscode/webview-ui-toolkit/react 引用相关组件并使用：

import React, { useState } from "react";
import { VSCodeTextField } from "@vscode/webview-ui-toolkit/react";

import { getVsCodeApi } from "webview/utils";

import style from "./AddTask.module.less";

const vscode = getVsCodeApi();

export const AddTask = () => {
  const [taskContent, setTaskContent] = useState("");

  function onTaskContentChange(e: any) {
    setTaskContent(e.target.value);
  }

  const toAddTask: React.KeyboardEventHandler<HTMLInputElement> = (e) => {
    if (e.key === "Enter") {
      vscode.postMessage({ type: "addTask", content: taskContent });
      setTaskContent("");
    }
  };

  return (
    <div className={style("add-task")}>
      <VSCodeTextField
        className={style("add-task-input")}
        placeholder="请输入待办项"
        value={taskContent}
        onKeyUp={toAddTask}
        onChange={onTaskContentChange}
      />
    </div>
  );
};

好吧，有了 webpack 等构建工具的加成，这些感觉真没啥好说的了。但无论你最终使用的是 vscode-webview-ui-toolkit 还是 ant design 亦或是其它组件库，开发完成后都别忘了在 vscode 的三类颜色主题下看看 webview 的实际视觉效果，下一节我们就来介绍颜色主题相关的一些内容。现在，可以看一下优化后的 demo 效果了：

颜色主题

vscode 有三大类颜色主题，分别是：浅色主题、深色主题以及高对比度主题。这三类主题在 body 元素上分别有着各自的类名：vscode-light、vscode-dark 以及 vscode-high-contrast。你可以基于这几个类名定制相应主题下的部分样式，例如：

body.vscode-light {
  color: black;
}

body.vscode-dark {
  color: white;
}

body.vscode-high-contrast {
  color: red;
}

在开发 webview 的样式时，我们更推荐大家尽可能地去使用 vscode 提供好的 颜色变量，这样可以最大程度地兼容到三类主题。以 textLink.foreground 为例，我们可以这样去用：

span {
  color: var(--vscode-textLink-foreground)
}

但难免可能存在个别主题下部分样式的效果还是不够好，拿我们的 demo 来讲，在高对比度主题下，鼠标悬浮任务行时，任务名直接看不清了，如图示：

这时我们就可以找到 body 元素上的 data-vscode-theme-id 的属性值，来定制相应主题下的样式，类似这样：

body[data-vscode-theme-id="Default High Contrast"] {
  .task-item-high-contrast {
    &:hover {
      background-color: rgba(255, 255, 255, 0.1);
    }
  }
}

body[data-vscode-theme-id="Default High Contrast Light"] {
  .task-item-high-contrast {
    &:hover {
      background-color: rgba(0, 0, 0, 0.1);
    }
  }
}

到这里，颜色主题相关的内容基本也就介绍完了。但有必要再提醒一下，那就是开发完插件后一定要在这三类主题下做一次视觉走查，很重要但也很容易被遗漏。接下来，我们就来看看开发的过程中可能会遇到的一些常见问题吧。

常见问题

在 webview 内能否做异步请求？

能，但是不推荐。

要在 webview 内发起异步请求，首先内容安全策略中，你得先这样 connect-src https://xxx; 配置下 connect-src，地址即是你要请求的服务端地址。其次就是你调用的接口也得支持跨域。

更推荐您在插件侧处理异步请求，再通过与 webview 通信以同步数据。

如何获取插件所在的工作区文件夹路径？

获取工作区文件夹路径可使用 vscode.workspace.workspaceFolders，具体可参考：

import * as vscode from "vscode";

export function getWorkspacePath() {
  const workspaceFolders = vscode.workspace.workspaceFolders;
  return workspaceFolders ? workspaceFolders[0].uri.fsPath : undefined;
}

这里需注意，一定要使用 uri 的 fsPath 属性，而不能使用其 path 属性，否则会有系统兼容性问题。

一个会话中 acquireVsCodeApi 能否调用多次？

不能，一个会话仅能调用一次 acquireVsCodeApi。而且处于安全原因，不建议你在调用后，将调用结果挂载在全局对象下以共享使用。你可以参考这样对调用结果缓存，并通过方法将调用结果暴露出去：

/**
 * 由于一个 session 仅能调用一次 acquireVsCodeApi，故在此缓存处理。
 * 出于安全考虑，这里并没有将获取到的 vscode api 对象挂载在 window 下，以防止被其它第三方脚本获取使用。
 */

let vsCodeApi: any = null;

export function getVsCodeApi() {
  if (!vsCodeApi) {
    vsCodeApi = window.acquireVsCodeApi();
  }
  return vsCodeApi;
}

为什么接入 webpack 等构建工具后，我使用的第三方 UI 组件库的样式没生效？

这大概率是因为你的 css 代码是以 css in js 的方式存在于构建产物中，而你在 webview 的 html 的内容安全策略中又限制了 style 只能通过外联的方式去加载，因此这种运行时动态插入的 css 代码将不会生效。此时你可以将这些 css 从 js 中抽离出去作为独立的 css 文件引入，你也可以选择像这样支持内联样式的加载：style-src: 'unsafe-inline'。如果你使用的是 antd，你还可以选择通过配置 csp 属性来支持动态样式。

如何获取输出面板中当前选中的输出通道名（OutputChannel Name）？

如果你的插件存在多种类型的日志输出，并且你可能需要知道当前选中的输出通道名，可以尝试下这种方式：

import * as vscode from "vscode";

import { PUBLISHER, EXTENSION_NAME, OUTPUT_CHANNEL_NAME } from "src/constants";

export function getVisibleOutputChannel() {
  const visibleTextEditors = vscode.window.visibleTextEditors;

  const visibleOutputChannel = visibleTextEditors.find(({ document }) => {
    return (
      document.uri.scheme === "output" &&
      document.uri.path.startsWith(
        `${PUBLISHER}.${EXTENSION_NAME}.${OUTPUT_CHANNEL_NAME}`
      )
    );
  });

  return visibleOutputChannel?.document.uri.path;
}

其中，PUBLISHER 和 EXTENSION_NAME 分别对应的是 package.json 中的 publisher 和 name 属性的值，OUTPUT_CHANNEL_NAME 对应的是你使用 vscode.window.createOutputChannel 方法创建输出通道时指定的输出通道名。

不仅如此，如果你还想监听输出面板日志的切换，但同样由于 vscode 本身并没有提供直接的 api，我也没找到更好的实现方式，有需要的话可以暂时参考这样实现：

context.subscriptions.push(
  vscode.window.onDidChangeVisibleTextEditors(() => {
    // 当存在多个 visibleTextEditor 时，该回调会被执行多次，每次获取到的 visibleTextEditors 会按顺序递增
  })
);

这里要注意，TextEditors 不仅仅包含所有的输出通道，你打开的每个文件编辑区域也都属于 TextEditor，它们的打开、关闭、切换都会触发该回调。另外，当存在多个可见的 TextEditor 时，该回调会被执行多次，且每次获取到的 visibleTextEditors 会按顺序递增。因此，你可能还需要结合上面示例中的 getVisibleOutputChannel 方法一起去做相关业务逻辑的处理。

小结

本文的篇幅不长，所有内容基本也都围绕着更好更快地开发 webview 插件展开，权当抛砖引玉，不足之处，还望指正。

到这里，webview 插件开发的主要内容基本也就介绍完了。下一篇我们就来看看如何“交付”已经开发好的 vscode 插件！

Demo 源码

to-do-list-demo-v0.2.0

相关阅读

vscode webview 插件开发（毛坯篇）

vscode webview 插件开发（交付篇）

参考资料

vscode-webview-ui-toolkit--getting-started

theming-webview-content

vscode-theme-color

vscode-output-channel

内容安全策略