> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 樣式設定

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

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

<Note>
  這些樣式選項適用於由 `ThunderPhoneWidget` React 元件和 `ThunderPhone.mount()` CDN 方法呈現的預建小工具。如果你需要完全自訂的 UI，請改用[無介面 hook](/zh-Hant/widget/headless-hook)。
</Note>

***

## 主題

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

```tsx theme={null}
<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-bg`            | `rgba(255, 255, 255, 0.82)`             | `rgba(15, 15, 15, 0.85)`                 | 控制列背景（半透明；由 `--tp-glass` 產生模糊效果）。                            |
| `--tp-surface`       | `rgba(0, 0, 0, 0.04)`                   | `rgba(255, 255, 255, 0.07)`              | 靜音按鈕背景。                                                      |
| `--tp-surface-hover` | `rgba(0, 0, 0, 0.07)`                   | `rgba(255, 255, 255, 0.12)`              | 靜音按鈕懸停背景。                                                    |
| `--tp-border`        | `rgba(0, 0, 0, 0.08)`                   | `rgba(255, 255, 255, 0.1)`               | 控制列與按鈕邊框。                                                    |
| `--tp-border-hover`  | `rgba(0, 0, 0, 0.14)`                   | `rgba(255, 255, 255, 0.18)`              | 懸停時的邊框顏色。                                                    |
| `--tp-text`          | `rgba(0, 0, 0, 0.88)`                   | `rgba(255, 255, 255, 0.95)`              | 主要文字（標題、智慧體名稱）。                                              |
| `--tp-text-2`        | `rgba(0, 0, 0, 0.5)`                    | `rgba(255, 255, 255, 0.55)`              | 次要文字（副標題、狀態列、通話計時器）。                                         |
| `--tp-glass`         | `blur(32px) saturate(180%)`             | `blur(32px) saturate(180%)`              | 在控制列上建立玻璃效果的 `backdrop-filter`。                              |
| `--tp-shadow`        | 三層陰影堆疊                                  | 三層陰影堆疊                                   | 控制列的 `box-shadow`（外框＋近距離＋遠距離圖層）。                             |
| `--tp-shadow-hover`  | 三層陰影堆疊                                  | 三層陰影堆疊                                   | 為懸停時的抬升效果所宣告；目前未由任何規則套用。                                     |
| `--tp-glow`          | `inset 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-bg`        | `rgba(239, 68, 68, 0.08)`               | `rgba(251, 113, 133, 0.12)`              | 結束通話按鈕背景。                                                    |
| `--tp-end-color`     | `#ef4444`                               | `#fb7185`                                | 結束通話按鈕圖示顏色。                                                  |
| `--tp-end-border`    | `rgba(239, 68, 68, 0.12)`               | `rgba(251, 113, 133, 0.15)`              | 結束通話按鈕邊框。                                                    |
| `--tp-end-hover`     | `rgba(239, 68, 68, 0.14)`               | `rgba(251, 113, 133, 0.2)`               | 結束通話按鈕懸停背景。                                                  |
| `--tp-idle-opacity`  | `0.4`                                   | `0.3`                                    | 為閒置狀態的淡化效果所宣告；目前未由任何規則套用。                                    |

### 覆寫自訂屬性

透過 `primaryColor` 屬性設定強調色：

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#e11d48"
/>
```

<Warning>
  `--tp-accent` 會透過 `primaryColor` 屬性設為**內嵌樣式**，因此在樣式表中覆寫 `--tp-accent` 不會生效。請使用此屬性變更強調色。其他所有自訂屬性皆可在 CSS 中覆寫。
</Warning>

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

```css theme={null}
.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 自訂強調色

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

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="light"
  primaryColor="#059669"
  title="Talk to support"
/>
```

### 透過 CSS 自訂顏色

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

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  primaryColor="#059669"
/>
```

```css theme={null}
/* 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);
}
```

### 自訂尺寸

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

```css theme={null}
/* 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`。完全隱藏它，只保留波形與按鈕：

```css theme={null}
.tp-meta {
  display: none;
}
```

或者隱藏個別部分：

```css theme={null}
/* 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;
}
```

<Note>
  閒置標籤位於 `.tp-name`/`.tp-sub`，而不是 `.tp-status`——僅隱藏 `.tp-status` 時，小工具閒置期間仍會顯示標題。
</Note>

### 特定主題覆寫

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

```css theme={null}
/* 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，將覆寫設定限定在特定小工具執行個體：

```tsx theme={null}
<ThunderPhoneWidget
  publishableKey="pk_live_your_publishable_key"
  theme="dark"
  className="support-widget"
/>
```

接著在 CSS 中鎖定該 class：

```css theme={null}
.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](/zh-Hant/widget/headless-hook) 可讓你完全掌控。你提供所有 HTML 與樣式，而 `useThunderPhone` 負責處理語音工作階段。此 hook 也提供 `audioLevelRef`，可用於建立波形等會隨音訊反應的視覺效果。

```tsx theme={null}
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>
  )
}
```

<Tip>
  當你需要隨音訊反應的動畫、自訂版面配置，或整合至既有元件庫時，無介面 hook 是合適的選擇。若要快速調整主題，則更適合使用 CSS 覆寫與自訂屬性。
</Tip>