ThunderPhone 2.0 正式上線。全程自助，每分鐘 2 美分起。查看公告
立即開始

Widget

樣式設定

使用 CSS 自訂 ThunderPhone 語音小工具的外觀

小工具會以具玻璃擬態風格的橫條呈現，內建淺色與深色主題。你可以從三個層級進行自訂：常用選項的 props、用於主題設定的 CSS 自訂屬性，以及可完整掌控樣式的 CSS 類別覆寫。

主題

theme prop 可控制小工具的配色。它會將 tp--light 或 tp--dark 類別套用至小工具根元素：

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
/>
主題類別說明
'light'tp--light淺色背景搭配深色文字。預設值。
'dark'tp--dark深色背景搭配淺色文字。

兩種主題皆採用具背景模糊與細緻透明效果的玻璃擬態橫條設計。

CSS 自訂屬性

此小工具提供可覆寫的 CSS 自訂屬性（變數），讓你無須調整個別類別即可變更色彩。這些屬性由套用至 .tp-widget 根元素的佈景主題類別（.tp--light 或 .tp--dark）定義：

屬性預設值（淺色）預設值（深色）說明
--tp-accent#000#fff強調色：開始按鈕、波形長條、連線中圓點、已連線狀態文字。透過 primaryColor 屬性以內嵌方式設定。
--tp-bgrgba(255, 255, 255, 0.82)rgba(15, 15, 15, 0.85)控制列背景（半透明；由 --tp-glass 產生模糊效果）。
--tp-surfacergba(0, 0, 0, 0.04)rgba(255, 255, 255, 0.07)靜音按鈕背景。
--tp-surface-hoverrgba(0, 0, 0, 0.07)rgba(255, 255, 255, 0.12)靜音按鈕懸停背景。
--tp-borderrgba(0, 0, 0, 0.08)rgba(255, 255, 255, 0.1)控制列與按鈕邊框。
--tp-border-hoverrgba(0, 0, 0, 0.14)rgba(255, 255, 255, 0.18)懸停時的邊框顏色。
--tp-textrgba(0, 0, 0, 0.88)rgba(255, 255, 255, 0.95)主要文字（標題、智慧體名稱）。
--tp-text-2rgba(0, 0, 0, 0.5)rgba(255, 255, 255, 0.55)次要文字（副標題、狀態列、通話計時器）。
--tp-glassblur(32px) saturate(180%)blur(32px) saturate(180%)在控制列上建立玻璃效果的 backdrop-filter。
--tp-shadow三層陰影堆疊三層陰影堆疊控制列的 box-shadow（外框＋近距離＋遠距離圖層）。
--tp-shadow-hover三層陰影堆疊三層陰影堆疊為懸停時的抬升效果所宣告；目前未由任何規則套用。
--tp-glowinset 0 1px 0 0 rgba(255,255,255,0.5)inset 0 1px 0 0 rgba(255,255,255,0.06)疊加於控制列陰影上的內側頂部高光。
--tp-connected#059669#34d399已連線狀態指示器顏色（狀態圓點）。
--tp-error#dc2626#fb7185錯誤狀態文字顏色。
--tp-end-bgrgba(239, 68, 68, 0.08)rgba(251, 113, 133, 0.12)結束通話按鈕背景。
--tp-end-color#ef4444#fb7185結束通話按鈕圖示顏色。
--tp-end-borderrgba(239, 68, 68, 0.12)rgba(251, 113, 133, 0.15)結束通話按鈕邊框。
--tp-end-hoverrgba(239, 68, 68, 0.14)rgba(251, 113, 133, 0.2)結束通話按鈕懸停背景。
--tp-idle-opacity0.40.3為閒置狀態的淡化效果所宣告；目前未由任何規則套用。

覆寫自訂屬性

透過 primaryColor 屬性設定強調色：

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#e11d48"
/>

使用 CSS 覆寫其他自訂屬性。請使用雙類別選擇器（.tp-widget.tp--light / .tp-widget.tp--dark），確保無論樣式表順序為何，你的規則都會優先於定義預設值的佈景主題類別：

.tp-widget.tp--light {
  --tp-bg: rgba(0, 0, 0, 0.9);
  --tp-text: rgba(255, 255, 255, 0.95);
  --tp-text-2: rgba(255, 255, 255, 0.55);
  --tp-border: rgba(255, 255, 255, 0.15);
}

CSS 類別

所有小工具類別皆以 tp- 為前綴，以避免與你現有的樣式衝突。

類別元素說明
.tp-widget根包裝器固定定位容器（position: fixed、角落位置由 position prop 設定、z-index: 9999）。承載主題類別與基礎字型設定；本身沒有視覺外框。
.tp--light / .tp--dark主題修飾類別與主題一同套用至 .tp-widget；定義所有 --tp-* 自訂屬性。
.tp-bar橫條玻璃擬態膠囊橫條本體：背景、背景模糊、邊框、99px 圓角半徑與陰影。寬度為 300px。
.tp-meta文字區塊所有文字的容器——閒置時的標題與副標題，以及通話期間的智慧體名稱與狀態。
.tp-name主要標籤閒置時顯示 title prop，通話期間顯示已連線智慧體的名稱（若無則使用 title）。
.tp-sub副標題閒置時顯示的「現正可用」文字。
.tp-start閒置通話按鈕圓形強調色開始按鈕（42px）。以 --tp-accent 作為背景。
.tp-dot連線圓點連線時顯示於橫條左側、會脈動的強調色圓點。
.tp-wave / .tp-wave--idle波形圖五條柱狀波形。--idle 會加入緩慢的呼吸動畫；通話期間，長條會依音訊產生反應。
.tp-button通話中按鈕通話中控制項的基礎樣式（42px、12px 圓角）。
.tp-button-group按鈕列通話期間包裝靜音與結束按鈕。
.tp-button--start連線按鈕變體通話開始時顯示的強調色變體。
.tp-button--mute靜音切換在通話期間將麥克風靜音／取消靜音。使用 --tp-surface。
.tp-button--end結束通話按鈕掛斷通話。使用 --tp-end-* 色彩組。
.tp-button--loading載入修飾類別連線時降低按鈕亮度。
.tp-icon / .tp-spin圖示按鈕圖示尺寸；tp-spin 會為連線中的旋轉圖示加入動畫。
.tp-status通話中狀態區塊在連線中／已連線／錯誤狀態時包裝狀態列。
.tp-status__text狀態列連線狀態文字（例如「連線中……」）或通話計時器。依狀態套用 .tp-status--connected（強調色）或 .tp-status--error（錯誤色）。
.tp-status__name智慧體名稱欄位狀態區塊的一部分，但目前的橫條版面配置不會顯示——智慧體名稱改為顯示在 .tp-name 中。
.tp-status__dot狀態圓點脈動的已連線狀態圓點樣式（使用 --tp-connected）。

範例

透過 Props 自訂強調色

為小工具建立品牌風格最簡單的方式：

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="light"
  primaryColor="#059669"
  title="Talk to support"
/>

透過 CSS 自訂顏色

覆寫自訂屬性以完整控制顏色。請記得，強調色來自 primaryColor prop，而不是 CSS：

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#059669"
/>
/* Emerald theme for everything else */
.tp-widget.tp--light {
  --tp-bg: rgba(236, 253, 245, 0.85);
  --tp-text: rgba(6, 78, 59, 0.95);
  --tp-text-2: rgba(4, 120, 87, 0.8);
  --tp-border: rgba(5, 150, 105, 0.2);
}

自訂尺寸

調整列、按鈕與文字尺寸，讓小工具變大或變小：

/* Wider bar */
.tp-bar {
  width: 340px;
}
 
/* Larger buttons (42px by default) */
.tp-start,
.tp-button {
  width: 56px;
  height: 56px;
}
 
/* Larger text */
.tp-name {
  font-size: 16px;
}
 
.tp-sub,
.tp-status__text {
  font-size: 14px;
}

隱藏文字標籤

小工具的所有文字都位於 .tp-meta。完全隱藏它，只保留波形與按鈕：

.tp-meta {
  display: none;
}

或者隱藏個別部分：

/* Hide only the idle "Available now" subtitle */
.tp-sub {
  display: none;
}
 
/* Hide only the in-call status line (connection state / timer) */
.tp-status {
  display: none;
}

特定主題覆寫

使用主題 class 鎖定特定主題：

/* Only affect dark theme */
.tp--dark .tp-start {
  box-shadow: 0 0 20px rgba(255, 255, 255, 0.25);
}
 
/* Only affect light theme */
.tp-widget.tp--light {
  --tp-bg: rgba(255, 255, 255, 0.95);
}

使用 className 設定範圍

使用 React 元件時，傳入 className prop，將覆寫設定限定在特定小工具執行個體：

<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  className="support-widget"
/>

接著在 CSS 中鎖定該 class：

.support-widget.tp--dark {
  --tp-bg: rgba(30, 30, 46, 0.9);
}
 
.support-widget .tp-name {
  font-weight: 700;
}

這樣你就能在同一頁面放置多個不同樣式的小工具執行個體。透過各自的 primaryColor prop 為每個執行個體設定專屬強調色（CSS 無法覆寫 --tp-accent——它會以 inline 方式設定）。

完全自訂 UI

如果 CSS 覆寫不足，無介面 hook 可讓你完全掌控。你提供所有 HTML 與樣式，而 useThunderPhone 負責處理語音工作階段。此 hook 也提供 audioLevelRef，可用於建立波形等會隨音訊反應的視覺效果。

import { useThunderPhone } from '@thunderphone/widget'
 
function MyWidget() {
  const phone = useThunderPhone({
    publishableKey: 'pk_live_your_publishable_key',
  })
 
  return (
    <div className="my-totally-custom-widget">
      {/* Your own buttons, animations, layouts -- anything */}
      <button onClick={phone.state === 'connected' ? phone.disconnect : phone.connect}>
        {phone.state === 'connected' ? 'Hang up' : 'Call us'}
      </button>
      {phone.audio}
    </div>
  )
}