全栈攻城狮

Appearance

Webview 基础 ​

Webview 是 VS Code 插件打造复杂界面的核心手段：在编辑器内嵌一个完整的 HTML 页面，用 Web 技术栈自由构建 UI。聊天面板、数据可视化、自定义设置页，都是 Webview 的经典应用。

Webview 是什么 ​

Webview 本质是嵌入在 VS Code 窗口中的 iframe：

特性说明
渲染引擎Chromium（与编辑器同源）
技术栈HTML/CSS/JS，可用任何前端框架
隔离性独立上下文，不能直接访问插件代码
通信通过 postMessage 与插件主进程通信

Webview 适合构建复杂交互 UI，而普通命令、状态栏、QuickPick 只适合轻量交互。

创建 Webview 面板 ​

window.createWebviewPanel 创建面板：

typescript
import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand('myExt.openPanel', () => {
      // 创建面板
      const panel = vscode.window.createWebviewPanel(
        'myExt.panel',   // viewType：面板类型标识
        '我的面板',       // title：标题
        vscode.ViewColumn.One,  // revealCol：显示位置
        {
          enableScripts: true,          // 允许 JS
          retainContextWhenHidden: true // 隐藏时保留状态
        }
      );

      // 设置 HTML
      panel.webview.html = getHtml();

      // 面板关闭事件
      panel.onDidDispose(() => {
        console.log('面板已关闭');
      });

      context.subscriptions.push(panel);
    })
  );
}

参数详解 ​

viewType ​

面板类型标识，必须全局唯一：

约束说明
只能包含小写字母、数字、连字符myExt.panel
建议前缀扩展名避免与其他扩展冲突
不能与扩展名相同会与主视图冲突

title ​

面板标签页显示的标题，可动态更新：

typescript
panel.title = '加载中...';
// 数据加载完成后更新
panel.title = '数据面板 (3)';

revealCol ​

面板打开的编辑器列位置：

值位置
ViewColumn.One第一列
ViewColumn.Two第二列
ViewColumn.Beside当前列旁边

设置 HTML 内容 ​

panel.webview.html 是核心属性，直接赋 HTML 字符串：

typescript
function getHtml(): string {
  return `
    <!DOCTYPE html>
    <html lang="zh-CN">
      <head>
        <meta charset="UTF-8">
        <style>
          body { font-family: sans-serif; padding: 16px; }
          button { padding: 8px 16px; }
        </style>
      </head>
      <body>
        <h1>Hello Webview</h1>
        <button id="btn">点击我</button>
        <script>
          const btn = document.getElementById('btn');
          btn.addEventListener('click', () => {
            document.body.innerText = '已点击';
          });
        </script>
      </body>
    </html>
  `;
}

内容安全策略 CSP ​

Webview 默认禁用脚本与外部资源加载，必须显式声明 CSP：

typescript
panel.webview.html = `
  <!DOCTYPE html>
  <html>
    <head>
      <meta
        http-equiv="Content-Security-Policy"
        content="default-src 'none';
                 style-src ${panel.webview.cspSource};
                 script-src ${panel.webview.cspSource};"
      >
    </head>
    <body>安全内容</body>
  </html>
`;

CSP 指令说明 ​

指令作用
default-src 'none'默认禁止所有资源（最安全）
style-src允许的样式来源
script-src允许的脚本来源
img-src允许的图片来源
font-src允许的字体来源

本地资源安全引用 ​

typescript
// 将扩展目录的 URI 转换为 webview 可访问的 URI
const scriptUri = panel.webview.asWebviewUri(
  vscode.Uri.joinPath(context.extensionUri, 'media', 'main.js')
);

panel.webview.html = `
  <script src="${scriptUri}"></script>
`;

生命周期 onDidDispose ​

面板关闭时触发 onDidDispose，用于清理资源：

typescript
const panel = vscode.window.createWebviewPanel(...);

panel.onDidDispose(() => {
  // 清理定时器、断开连接、释放资源
  if (timer) {
    clearInterval(timer);
  }
  console.log('Webview 面板已销毁');
});

状态保持 ​

选项效果
retainContextWhenHidden: true面板隐藏时保留 JS 状态，但消耗内存
默认（false）隐藏时销毁上下文，显示时重建

大数据场景谨慎使用 retainContextWhenHidden，推荐用 getState/setState 持久化关键状态。

完整示例 ​

typescript
import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand('myExt.openDashboard', () => {
      // 创建面板
      const panel = vscode.window.createWebviewPanel(
        'myExt.dashboard',
        '数据面板',
        vscode.ViewColumn.One,
        { enableScripts: true }
      );

      // 更新 HTML
      panel.webview.html = `<!DOCTYPE html>
        <html>
          <head>
            <meta charset="UTF-8">
            <meta http-equiv="Content-Security-Policy"
                  content="default-src 'none'; style-src ${panel.webview.cspSource};">
            <style>
              body { font-family: sans-serif; padding: 20px; }
              .card { border: 1px solid #ccc; padding: 12px; border-radius: 4px; }
            </style>
          </head>
          <body>
            <div class="card">
              <h2>数据面板</h2>
              <p>CPU: 45%</p>
              <p>内存: 2.1GB / 8GB</p>
            </div>
          </body>
        </html>`;

      // 生命周期
      panel.onDidDispose(() => console.log('面板已关闭'));
      context.subscriptions.push(panel);
    })
  );
}

常见问题 ​

问题处理
页面空白无样式检查 CSP 是否放行 style-src
脚本不执行确认 enableScripts: true 与 script-src
无法加载本地图片用 asWebviewUri 转换 URI
面板关闭后报错监听 onDidDispose 停止异步操作

Webview 是插件 UI 的无限可能，掌握基础创建与安全配置后，下一步学习它与插件主进程的消息通信。