Webview 中可用的 VS Code 方法

在 VS Code Webview 的 HTML 中，不能直接调用 VS Code 的 API （如 vscode.window.showInformationMessage），但可以通过 acquireVsCodeApi() 获取一个受限的 vscode 对象，用于与插件主程序通信。以下是详细说明和示例：

一、Webview 中可用的 VS Code 方法

通过 const vscode = acquireVsCodeApi(); 获取的 vscode 对象支持以下操作：

1. 消息传递

vscode.postMessage(message)

向插件主程序发送消息，触发主程序执行操作（如显示弹窗、修改文件等）。
javascript 复制代码
```
vscode.postMessage({ command: "showMessage", text: "Hello from Webview" });
```

window.addEventListener('message', callback)

接收主程序返回的消息（如操作结果、数据更新等）。

javascript 复制代码

window.addEventListener('message', (event) => {
  if (event.data.command === "operationResult") {
    console.log("收到主程序响应:", event.data.data);
  }
});

2. 状态管理

vscode.getState()

获取 Webview 上一次保存的状态（如表单数据、滚动位置等）。
javascript 复制代码
```
const savedState = vscode.getState() || { formData: {} };
```
vscode.setState(newState)

保存 Webview 的状态，刷新或重新打开时恢复。
javascript 复制代码
```
vscode.setState({ formData: currentFormValues });
```

3. 环境信息

vscode.environment （只读）
包含 VS Code 的环境信息，如版本号、是否为调试模式等。
javascript 复制代码
```
console.log("VS Code 版本:", vscode.environment.appVersion);
```

二、完整交互流程示例

1. Webview HTML（发送消息）

html 复制代码

<!DOCTYPE html>
<html>
<body>
  <button id="showMessageBtn">显示消息</button>
  <script>
    const vscode = acquireVsCodeApi();

    // 发送消息到主程序
    document.getElementById("showMessageBtn").addEventListener("click", () => {
      vscode.postMessage({ command: "showMessage", text: "点击了按钮！" });
    });

    // 接收主程序响应
    window.addEventListener("message", (event) => {
      if (event.data.command === "messageShown") {
        alert("主程序已显示消息！");
      }
    });
  </script>
</body>
</html>

2. 插件主程序（处理消息）

typescript 复制代码

import * as vscode from "vscode";

export function activate(context: vscode.ExtensionContext) {
  // 创建 Webview 面板
  const panel = vscode.window.createWebviewPanel(
    "myWebview",
    "Webview 示例",
    vscode.ViewColumn.One
  );

  // 加载 HTML 内容
  panel.webview.html = getWebviewContent();

  // 监听 Webview 消息
  panel.webview.onDidReceiveMessage(
    (message: { command: string; text?: string }) => {
      switch (message.command) {
        case "showMessage":
          // 显示 VS Code 消息
          vscode.window.showInformationMessage(message.text || "默认消息");
          // 发送确认消息回 Webview
          panel.webview.postMessage({ command: "messageShown" });
          break;
      }
    },
    undefined,
    context.subscriptions
  );
}

function getWebviewContent() {
  return `<!DOCTYPE html>
  <html>
  <body>
    <button id="showMessageBtn">显示消息</button>
    <script>
      const vscode = acquireVsCodeApi();
      document.getElementById("showMessageBtn").addEventListener("click", () => {
        vscode.postMessage({ command: "showMessage", text: "点击了按钮！" });
      });
      window.addEventListener("message", (event) => {
        if (event.data.command === "messageShown") {
          alert("主程序已显示消息！");
        }
      });
    </script>
  </body>
  </html>`;
}

三、关键限制

安全隔离

Webview 的 JavaScript 环境与插件主程序隔离，不能直接调用 VS Code API，必须通过消息传递。
可用 API 受限

仅能通过 acquireVsCodeApi() 获取的 vscode 对象进行通信，无法直接使用 vscode.window、vscode.workspace 等模块。
性能优化

频繁的消息传递可能影响性能，建议批量处理或使用状态管理。

四、常见用例

场景	实现方式
显示 VS Code 消息	Webview 发送 `postMessage`，主程序调用 `vscode.window.showInformationMessage`
获取当前文件路径	主程序通过 `vscode.window.activeTextEditor?.document.uri` 获取，再发送回 Webview
执行 VS Code 命令	主程序调用 `vscode.commands.executeCommand("命令ID")`
修改用户配置	主程序调用 `vscode.workspace.getConfiguration().update()`

通过消息传递机制，Webview 可以安全地与 VS Code 主程序交互，实现丰富的自定义功能。