全栈攻城狮

Appearance

Webview 消息通信 ​

Webview 与插件运行在两个隔离的上下文，无法直接调用对方函数。消息通信是连接二者的桥梁：插件发送指令给页面，页面汇报数据给插件，一问一答完成交互。

通信架构 ​

插件主进程（Extension Host）          Webview（浏览器）
┌─────────────────────┐    postMessage   ┌─────────────────┐
│ panel.webview.postMessage ◄────────────┤ vscode.postMessage
│ panel.webview.onDidReceiveMessage ────► │ window.addEventListener('message')
└─────────────────────┘                  └─────────────────┘
  • 插件 → 页面：panel.webview.postMessage()
  • 页面 → 插件：vscode.postMessage()（经 acquireVsCodeApi 获取）
  • 插件接收：panel.webview.onDidReceiveMessage()
  • 页面接收：window.addEventListener('message')

页面获取 API：acquireVsCodeApi ​

Webview 页面 JS 通过 acquireVsCodeApi() 获取 VS Code API 对象：

javascript
// Webview 内的 JavaScript
const vscode = acquireVsCodeApi();

// 向插件发送消息
vscode.postMessage({ type: 'hello', data: 'from webview' });

API 对象能力 ​

方法作用
postMessage(message)向插件发送消息
getState()读取持久化状态
setState(state)保存持久化状态

获取限制 ​

  • 每个 Webview 只能调用一次 acquireVsCodeApi()
  • 重复调用会报错（保存引用复用）
  • 仅在 Webview 上下文中可用

插件接收消息 onDidReceiveMessage ​

插件侧监听页面发来的消息：

typescript
panel.webview.onDidReceiveMessage(
  (message) => {
    switch (message.type) {
      case 'hello':
        vscode.window.showInformationMessage(`收到: ${message.data}`);
        break;
      case 'save':
        handleSave(message.content);
        break;
      default:
        console.warn('未知消息类型', message);
    }
  },
  undefined,
  context.subscriptions
);

消息协议设计 ​

用 type 字段区分消息类型，是标准做法：

json
{ "type": "save", "content": "..." }
{ "type": "requestData", "id": 1 }
{ "type": "done", "result": true }

插件发送消息 postMessage ​

插件主动向页面推送数据：

typescript
// 推送更新
panel.webview.postMessage({
  type: 'update',
  data: { cpu: 45, memory: 2.1 }
});

// 推送命令指令
panel.webview.postMessage({
  type: 'refresh',
  force: true
});

发送时机 ​

  • 用户点击页面按钮时（页面主动请求）
  • 数据变化时（插件主动推送）
  • 文件保存/编辑器变更时

页面接收消息 ​

Webview 页面监听 message 事件：

javascript
window.addEventListener('message', (event) => {
  const message = event.data;
  switch (message.type) {
    case 'update':
      renderData(message.data);
      break;
    case 'refresh':
      loadData();
      break;
  }
});

注意：event.data 就是插件发送的消息对象，event.source 是消息来源。

getState / setState 状态持久化 ​

Webview 关闭再打开时，JS 状态会丢失。用 getState/setState 持久化：

javascript
// 保存状态
const vscode = acquireVsCodeApi();

function saveState(data) {
  vscode.setState({ savedData: data, savedAt: Date.now() });
}

// 恢复状态
function loadState() {
  const state = vscode.getState();
  if (state) {
    return state.savedData;
  }
  return null;
}

// 初始化时恢复
const previous = loadState();
if (previous) {
  renderData(previous);
} else {
  loadData();
}

状态持久化原理 ​

机制说明
setState保存到内存，面板销毁后保留
面板重新打开自动恢复（即使 retainContextWhenHidden=false）
存储限制每个 Webview 独立存储空间

状态在整个会话中有效，VS Code 重启后丢失（如需跨重启用 workspaceState）。

完整示例：计数器应用 ​

typescript
// extension.ts
import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand('myExt.openCounter', () => {
      const panel = vscode.window.createWebviewPanel(
        'myExt.counter',
        '计数器',
        vscode.ViewColumn.One,
        { enableScripts: true }
      );

      let count = 0;

      // 页面请求数据
      panel.webview.onDidReceiveMessage(
        (message) => {
          switch (message.type) {
            case 'increment':
              count++;
              break;
            case 'decrement':
              count--;
              break;
            case 'reset':
              count = 0;
              break;
          }
          // 推送新值给页面
          panel.webview.postMessage({ type: 'count', value: count });
        },
        undefined,
        context.subscriptions
      );

      panel.webview.html = getHtml();
      context.subscriptions.push(panel);
    })
  );
}

function getHtml(): string {
  return `<!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8">
        <style>
          body { font-family: sans-serif; text-align: center; padding-top: 40px; }
          .count { font-size: 48px; margin: 20px; }
          button { font-size: 20px; margin: 0 8px; padding: 8px 20px; }
        </style>
      </head>
      <body>
        <div class="count" id="count">0</div>
        <button onclick="send('increment')">+</button>
        <button onclick="send('decrement')">-</button>
        <button onclick="send('reset')">重置</button>
        <script>
          const vscode = acquireVsCodeApi();
          function send(type) { vscode.postMessage({ type }); }
          window.addEventListener('message', (event) => {
            if (event.data.type === 'count') {
              document.getElementById('count').textContent = event.data.value;
            }
          });
        </script>
      </body>
    </html>`;
}

消息调试 ​

技巧操作
打开开发者工具菜单 Help → Toggle Developer Tools
查看消息Console 面板观察 postMessage 流量
插件侧日志console.log 输出到 Extension Host
消息格式错误确认 type 字段拼写一致

常见问题 ​

问题处理
postMessage 无效确认 enableScripts: true
acquireVsCodeApi 报错只能调用一次，保存引用
页面收不到消息检查 message 事件监听已注册
状态丢失用 setState 持久化，getState 恢复

消息通信让 Webview 从「静态页面」升级为「双向交互应用」，是构建复杂插件的关键能力。