115/18 - generative_ui - 生成 HTML 互動檔案 - iT 邦幫忙::一起幫忙解決難題，拯救 IT 人的一天

2026 iThome 鐵人賽

DAY 18

Build on Google AI

第一次用 Antigravity CLI 做出 Plugin 就上手系列第 18 篇

115/18 - generative_ui - 生成 HTML 互動檔案

18th鐵人賽 agy antigravity antigravity_cli agy_cli

AndyAWD

團隊第二屆技術創作市集

2026-09-06 20:55:59

72 瀏覽

分享至

今天介紹什麼工具

generative_ui（生成 HTML 互動檔案）：Antigravity CLI（agy）內建的視覺化擴充技能，能突破終端機純文字與 Markdown 的框架，讓 AI 代理直接產出自包含（Self-contained）、具備互動性與精美質感的 HTML 頁面或行內微型卡片（Inline Widget）。

為什麼要用這個工具

在過去，當我們請 AI 代理分析一份系統架構資料、測試覆蓋率或雲端成本預估時，AI 通常會吐出一張密密麻麻、動輒 50 行數據的 Markdown 表格。雖然資訊完整，但有幾個明顯缺點：

閱讀疲勞：在終端機狹小的視窗內捲動純文字表格，閱讀體驗較差且缺乏層次感。
缺乏互動：數據是靜態死板的，無法即時篩選、動態折疊、切換檢視維度或調整滑桿參數。
前端掌握度提升：隨著模型（如 Gemini 2.5 或 3.7 系列）對 HTML、Tailwind CSS 與現代 JavaScript 的控制力大幅躍進，AI 已具備隨插即用的前端排版能力。目前 Gemini 網頁版已全面導入 Generative UI 技術，而 Antigravity CLI 則進一步將這項能力無縫整合進終端機與桌面生態系。

透過 generative_ui，AI 代理不再只是回覆文字，而是能依照你的對話上下文，即時生成可操作、可互動的專屬微型應用程式。

核心運作機制與主題渲染架構

在深入實作前，我們先了解 Antigravity CLI 底層如何安全、優雅地渲染這些動態 HTML：

呈現模式（雙軌渲染）

獨立工件模式（Standalone Artifact，預設推薦）：AI 會在工作區的工件目錄（Artifact Directory）下產生一個獨立的 .html 檔案，使用者可直接點擊在側邊輔助面板（Side Pane）或外部瀏覽器中開啟，適合複雜儀表板、多分頁報告與深度圖表。
行內微型嵌入（Inline Embed）：若內容輕量且作為對話的輔助補充，AI 可在回覆中加入 agent-embed 標籤（如 <agent-embed src="file:///<artifact_path>/widget.html"></agent-embed>），CLI 與桌面畫布會以卡片形式直接在對話流中嵌入顯示。

CSP 安全邊界與 Tailwind CSS 支援

為了防止惡意代碼注入與 XSS 攻擊，Antigravity 對所有 UI 容器施加了嚴格的內容安全策略（CSP），完全封鎖外部第三方 CDN（如 unpkg、cdnjs 等）。
唯一開放的官方白名單為 Google 專屬的 Tailwind CSS 資源庫：<script src="https://www.gstatic.com/antigravity/web/dev/tailwindcss.min.js"></script>。這代表無須手動配置打包工具，直接在 HTML <head> 引入該腳本，即可使用完整的 Tailwind 工具類別進行排版。

主題變數感知（Semantic Design Tokens）

Antigravity 會自動將主程式的主題變數注入至 iframe 之中，元件無須寫死顏色，即可完美切換深色（Dark Mode）與淺色（Light Mode）模式：

背景與表面：var(--background)、var(--card)、var(--content)、var(--sidebar)
線條與框線：var(--border)
文字階層：var(--foreground)、var(--muted-foreground)、var(--placeholder)
主題強調色：var(--primary)、var(--secondary)、var(--accent)

終端機實作

基礎模板（Boilerplate Template）

Antigravity CLI 官方推薦的標準 Generative UI 自包含模板如下：

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script src="https://www.gstatic.com/antigravity/web/dev/tailwindcss.min.js"></script>
</head>
<body class="bg-transparent text-[var(--foreground)] antialiased p-5">
  <div class="bg-[var(--card)] text-[var(--foreground)] border border-[var(--border)] rounded-xl p-5 shadow-sm">
    <h2 class="text-[var(--foreground)] font-semibold text-lg">雲端資源成本預估儀表板</h2>
    <p class="text-[var(--muted-foreground)] text-sm mb-4">即時調整伺服器規模與儲存量，動態試算每月支出</p>
    
    <!-- 互動內容區塊（輸入框、滑桿、圖表或自訂 JavaScript） -->
  </div>
</body>
</html>

實戰示範：用自然語言觸發生成互動試算卡片

在 Antigravity CLI 的終端會話中，你可以直接輸入提示詞：

> 請幫我分析專案改採 Serverless 架構後的成本變化，並使用 generative_ui 做一個可以拉動請求量（Requests）滑桿的互動式 HTML 成本試算卡片。

AI 代理接收到指令後，會依序執行以下步驟：

自動調用檔案生成工具，在工件目錄下建立 cost_calculator.html。
引入官方 Tailwind CSS，並利用原生 JavaScript 實作滑桿連動計算公式。
輸出卡片式 HTML，並自動套用宿主的主題變數。
在終端中以 agent-embed 行內渲染出這張卡片，或提供點擊即可預覽的工件路徑。

踩坑與最佳實踐（陷阱避坑指南）

在使用 generative_ui 時，有幾個容易踩雷的限制與關鍵細節：

行內嵌入高度限制（500px 上限）

行內嵌入（Inline Embed）的視窗高度上限固定為 500px，一旦超出高度，元件內部會出現捲動軸。
行內卡片務必追求輕量、緊湊（Compact）。如果內容龐大（例如整套監控儀表板），應作為獨立工件（Standalone Artifact）開啟，避免硬塞在行內。
嚴禁設定相對視窗高度：在行內嵌入中，絕對不能在最外層容器使用 h-screen、min-h-screen、100vh 或 height: 100%。因為 iframe 的高度是由內容反向推導，相對高度會導致元件高度塌陷成一條細線，請一律使用 padding 或內部固定尺寸撐開。
不要在此標籤上手動加上 height 屬性，因為所有高度屬性都會被系統忽略。

嚴格遵守 CSP，禁止引用第三方 CDN

許多開發者習慣在 HTML 中順手引用 cdnjs 上的 FontAwesome 或 Chart.js，結果渲染出來全部被安全機制阻擋而破圖。
圖示請直接使用純 SVG 代碼內嵌，圖表可使用原生 HTML5 canvas、SVG 或純 CSS 長條圖呈現。

深淺色模式相容性（杜絕寫死顏色）

若習慣寫死 bg-white text-gray-900，切換到 Dark Mode 時會瞬間變成刺眼的強光區塊，甚至文字與背景同色看不清。
全面使用 Tailwind 任意值類別配合語意化 CSS 變數：背景使用 bg-[var(--card)]、主文字使用 text-[var(--foreground)]、次要文字使用 text-[var(--muted-foreground)]、框線使用 border-[var(--border)]。
請勿在 style 標籤中的 :root 覆寫顏色 fallback，因為宿主環境會在執行時動態管理並覆蓋變數。