Webview API 是 VSCode 扩展中嵌入可控 HTML/CSS/JS 界面的核心机制，需依次创建面板、加载本地资源、实现双向通信、管理动态内容与状态、并妥善处理生命周期释放。
如果您正在开发 VSCode 扩展并希望在编辑器内嵌入完全可控的 HTML/CSS/JS 界面，则 Webview API 是实现该目标的核心机制。以下是构建具备自定义 UI 的扩展所必需的关键步骤与实践方式：
本文运行环境：MacBook Pro，macOS Sequoia。
一、创建 Webview 视图面板
Webview 通过 vscode.window.createWebviewPanel 创建，它在侧边栏或新标签页中呈现独立的沙盒化网页环境，与主扩展进程隔离但可双向通信。
1、在 extension.ts 中调用 vscode.window.createWebviewPanel 方法，指定视图类型、标题、显示位置（vscode.ViewColumn.One）及初始选项。
2、设置 webview.options 属性，启用 scripts、localResourceRoots，并配置 cspSource 以允许内联脚本执行。
3、使用 webview.html 属性注入完整 HTML 字符串，其中包含 base href="${webview.cspSource}/" 以确保资源路径解析正确。
二、加载本地静态资源
Webview 默认禁止加载 file:// 协议资源，必须通过 vscode.Uri.file 转换为 webview.asWebviewUri 格式，才能在 HTML 中安全引用 CSS、JS 或图片文件。
1、在扩展目录下创建 resources 子文件夹，存放 style.css 和 script.js。
2、使用 vscode.Uri.file 获取资源绝对路径，再传入 webview.asWebviewUri 得到可被 webview 加载的 URI。
3、在注入的 HTML 中，将 link 和 script 标签的 src/href 属性设为转换后的 URI，例如：。
三、实现扩展与 Webview 的消息通信
Webview 与扩展主进程之间无法直接访问对方作用域，需通过 postMessage 和 onDidReceiveMessage 实现异步事件驱动通信，确保数据边界清晰且安全。
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
1、在 Webview 的 HTML 内部脚本中调用 acquireVsCodeApi() 获取 vscode 对象，然后使用 vscode.postMessage({ command: 'init', data: {} }) 向扩展发送初始化请求。
2、在 extension.ts 中对 panel.webview.onDidReceiveMessage 注册监听器，用 switch 匹配 command 字段处理不同消息类型。
3、扩展向 Webview 发送消息时调用 panel.webview.postMessage({ type: 'update', payload: result })，Webview 端监听 window.addEventListener('message', event => { ... }) 接收并响应。
四、注入动态内容与状态管理
Webview 的 HTML 是静态字符串，但可通过模板插值或 DOM 操作在加载后注入动态内容；状态应由扩展端统一维护，Webview 仅作为纯展示层与交互入口。
1、在 webview.html 字符串中预留占位符如 ${initialData}，并在拼接时用 JSON.stringify 替换为序列化对象。
2、Webview 加载完成后，触发 window.addEventListener('DOMContentLoaded', () => { ... })，读取初始数据并渲染 UI 元素。
3、所有用户操作（如按钮点击）均封装为 postMessage 消息，由扩展端执行实际逻辑（如调用 vscode.workspace.findFiles），再将结果回传更新视图。
五、处理 Webview 生命周期与资源释放
Webview 实例未被显式销毁时将持续占用内存，且可能引发重复事件监听或资源泄漏；必须在适当时机清理监听器、取消定时任务并释放引用。
1、监听 panel.onDidDispose 事件，在其回调中移除所有已注册的 onDidReceiveMessage 监听器。
2、若 Webview 内部启动了 setInterval 或 WebSocket 连接，须在 window.addEventListener('beforeunload', ...) 中主动关闭。
3、当用户关闭面板后，将 panel 变量置为 undefined，并确保无外部闭包持续持有对该 panel 的引用，防止 V8 垃圾回收器无法释放内存。
