--- title: "CDN／Script Tag" description: "無需打包工具，即可將 ThunderPhone 語音小工具加入任何網站" --- CDN 版本會在內部打包 React，因此你可以在靜態網站、WordPress、Webflow，或任何可加入 HTML 的頁面上使用小工具。不需要 npm、打包工具或框架。 ## CDN 網址 ```html Latest (recommended) ``` ```html Pinned version ``` `latest` 網址是控制台嵌入程式碼產生器所產生的網址。這些網址會快取 5 分鐘，並自動取得新的穩定版本。固定的 `/widget/vX.Y.Z/` 路徑不可變更，且會長期快取——若使用固定版本，請將版本與你開發時使用的 `@thunderphone/widget` npm 發行版本保持一致。 --- ## 基本用法 ```html

``` 小工具會掛載至目標元素，並顯示為**視窗角落的固定定位列**（預設為 `bottom-right`，由 `position` 選項控制）。掛載元素僅是 React 根節點——它在頁面中的位置不會影響小工具顯示的位置。 --- ## 掛載選項 `ThunderPhone.mount()` 接受與 React 元件相同的選項，另加上 `element` 屬性： | 選項 | 類型 | 必填 | 預設值 | 說明 | |--------|------|----------|---------|-------------| | `element` | `string \| HTMLElement` | 是 | -- | CSS 選擇器（例如 `'#thunderphone'`）或 DOM 元素參照。 | | `publishableKey` | `string` | 是 | -- | 可發布的 API 金鑰（`pk_live_...`）。系統會根據金鑰的小工具設定自動解析智慧體。 | | `theme` | `'light' \| 'dark'` | 否 | `'light'` | 色彩配置。 | | `primaryColor` | `string` | 否 | `'#000000'`（淺色）/ `'#ffffff'`（深色） | 作為強調色使用的 CSS 色彩字串。 | | `title` | `string` | 否 | `'Voice assistant'` | 顯示於小工具列中的文字。 | | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | 否 | `'bottom-right'` | 固定於檢視區的位置。 | | `apiBase` | `string` | 否 | `'https://api.thunderphone.com/v1'` | 覆寫 API 基礎 URL。 | | `language` | `string` | 否 | -- | 每個工作階段的語言覆寫設定——可使用語言代碼或地區設定，例如 `en`、`es` 或 `fr-FR`。未設定時，會套用智慧體設定的語言。需要在金鑰的[瀏覽器覆寫設定](/zh-Hant/guides/embed-web-widget)下啟用 `language`。 | | `voice` | `string` | 否 | -- | 每個工作階段的語音覆寫設定——可使用語音名稱，例如 `maria`。未設定時，會套用智慧體設定的語音。需要在金鑰的[瀏覽器覆寫設定](/zh-Hant/guides/embed-web-widget)下啟用 `voice`。 | | `context` | `string` | 否 | -- | 傳遞給智慧體的每個工作階段頁面或網站事實背景資訊。伺服器端會截斷為 12,000 個字元。需要在金鑰的[瀏覽器覆寫設定](/zh-Hant/guides/embed-web-widget)下啟用 `context`。 | | `onConnect` | `() => void` | 否 | -- | 語音工作階段連線時呼叫。 | | `onDisconnect` | `() => void` | 否 | -- | 工作階段結束時呼叫。 | | `onError` | `(error) => void` | 否 | -- | 發生錯誤時呼叫。錯誤物件包含 `error`（代碼）和 `message` 欄位。 | | `ringtone` | `boolean \| string` | 否 | `false` | 連線期間播放鈴聲。`true` 使用預設鈴聲，或使用 URL 字串指定自訂音訊。 | --- ## 清理 `ThunderPhone.mount()` 會傳回具有清理方法的小工具執行個體： ```html ``` `unmount()` 和 `destroy()` 的作用相同——兩者都會中斷任何進行中的語音工作階段，並從 DOM 中移除小工具。請依照最適合你程式碼可讀性的方式使用。在單頁式應用程式中離開頁面，或移除包含元素時，請務必清理小工具。這可確保進行中的語音工作階段會正確中斷。 --- ## 範例 ### 深色主題搭配自訂顏色 ```html

``` ### 自訂位置 ```html

``` ### 搭配事件回呼 ```html

``` ### 搭配鈴聲 ```html

``` ### 使用 DOM 元素參照 ```html

``` ### WordPress／CMS 整合將以下內容加入自訂 HTML 區塊或佈景主題的頁尾： ```html ``` `

` 可放在任何位置——它僅作為掛載點。小工具本身會以固定覆蓋層的形式顯示在檢視區角落（由 `position` 選項設定），不會隨周圍內容排列。 --- ## 疑難排解確認 CSS 和 JS 檔案都已載入。檢查瀏覽器主控台是否有網路錯誤。確認在呼叫 `ThunderPhone.mount()` 前，目標元素已存在於 DOM 中。指令碼尚未載入。確認 `widget.js` 的 `