💡 前言

在前一天的文章中，我們學會了如何初始化專案、註冊指令，並在命令面板中彈出簡單的提示視窗 (showInformationMessage)。

然而，如果你的外掛需要呈現更複雜的互動介面——例如：專屬的圖表儀表板、Markdown 即時預覽、資料庫管理介面、甚至是內嵌的小遊戲或網頁工具，單靠 VS Code 原生的對話框就遠遠不夠了。

今天 Day 26 我們要來解鎖 VS Code 外掛開發的終極武器——Webview API，教你如何在 VS Code 內部嵌入完整的網頁，打造媲美獨立軟體的強大互動介面！

🎯 本篇重點

1. 什麼是 Webview API？（在編輯器裡開網頁）
2. 如何建立與註冊自訂 Webview Panel
3. 主行程 (Extension) 與 Webview 之間的雙向通訊 (Message Passing)
4. 實作範例：打造一個帶有互動按鈕的筆記儀表板

🌐 1. 什麼是 Webview API？

Webview 允許擴充套件在 VS Code 內部建立一個完全自訂的標籤頁分頁。
• 它的本質其實就是一個內嵌的 iframe (網頁容器)。
• 這意味著你可以完全使用熟悉的 HTML、CSS、JavaScript，甚至搭配 React、Vue 或 Tailwind CSS 來設計 UI，讓你的外掛介面變得極度精緻與現代化！

🛠️ 2. 建立你的第一個 Webview Panel

修改前一天建立的 src/extension.ts，加入建立 Webview 的程式碼：

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  let disposable = vscode.commands.registerCommand('my-first-extension.openDashboard', () => {
    // 1. 建立並開啟一個新的 Webview Panel
    const panel = vscode.window.createWebviewPanel(
      'dashboard',                    // 內部識別碼
      'My Custom Dashboard',          // 標籤頁顯示的標題
      vscode.ViewColumn.One,          // 顯示在哪一個編輯器分頁欄
      {
        enableScripts: true           // 允許在 Webview 中執行 JavaScript
      }
    );

    // 2. 設定 Webview 的 HTML 內容
    panel.webview.html = getWebviewContent();
  });

  context.subscriptions.push(disposable);
}

// 產生 HTML 內容的輔助函式
function getWebviewContent() {
  return `<!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Dashboard</title>
        <style>
            body { font-family: sans-serif; padding: 20px; background-color: #1e1e1e; color: #fff; }
            button { background: #007acc; color: white; border: none; padding: 10px 20px; cursor: pointer; border-radius: 4px; }
            button:hover { background: #005999; }
        </style>
    </head>
    <body>
        <h1>🚀 歡迎來到我的 VS Code 儀表板</h1>
        <p>這是一個透過 Webview API 嵌入在編輯器內的自訂網頁！</p>
        <button id="clickBtn">點我觸發通知</button>

        <script>
            // 取得前端 VS Code API
            const vscode = acquireVsCodeApi();

            document.getElementById('clickBtn').addEventListener('click', () => {
                // 向外掛主行程發送訊息
                vscode.postMessage({ command: 'showAlert', text: 'Hello from Webview HTML!' });
            });
        </script>
    </body>
    </html>`;
}

export function deactivate() {}

🔄 3. 雙向通訊：主行程與網頁的對話 (Message Passing)

Webview 雖然是一個網頁，但它運行在獨立的沙盒環境中。如果網頁上的按鈕被點擊了，要怎麼通知 VS Code 主行程呢？答案是透過 postMessage 雙向通訊機制：

在 src/extension.ts 中接收來自 Webview 的訊息：

// 在 panel 建立後加入監聽
panel.webview.onDidReceiveMessage(
  message => {
    switch (message.command) {
      case 'showAlert':
        vscode.window.showInformationMessage(message.text);
        return;
    }
  },
  undefined,
  context.subscriptions
);

通訊流程：

1. 網頁端 (HTML/JS) ➔ 透過 vscode.postMessage({ command: '...', ... }) 發送事件。
2. 擴充套件端 (TypeScript) ➔ 透過 panel.webview.onDidReceiveMessage 攔截並執行對應的 VS Code API（例如彈出通知、讀寫檔案、開啟終端機）。

⚠️ 4. 開發 Webview 的安全與注意事項

在實際開發專案時，使用 Webview 有幾個必須注意的鐵律：
• Content Security Policy (CSP)：為了防止資安漏洞，務必在 HTML 的 <head> 中設定嚴格的 CSP 標頭，限制網頁只能載入合法的腳本來源。
• 狀態保存：當 VS Code 關閉分頁或記憶體吃緊而銷毀 Webview 時，網頁上的狀態會被重置。如果需要保存使用者輸入的資料，記得透過 panel.webview.state 進行持久化。