样式 - ThunderPhone

该小组件呈现为带有内置浅色和深色主题的毛玻璃风格栏。可通过三个层级进行自定义：用于常见选项的属性、用于主题设置的 CSS 自定义属性，以及用于完全控制的 CSS 类覆盖。

这些样式选项适用于由 ThunderPhoneWidget React 组件和 ThunderPhone.mount() CDN 方法渲染的预构建小组件。如果您需要完全自定义的 UI，请改用无头 Hook。

主题

theme 属性控制小组件的配色方案。它会将 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-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 属性设置强调色：

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

--tp-accent 会通过 primaryColor 属性设置为内联样式，因此在样式表中覆盖 --tp-accent 不会生效。请通过该属性更改强调色。其他所有自定义属性均可在 CSS 中覆盖。

使用 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` 属性设置，`z-index: 9999`）。承载主题类和基础字体设置；自身不含视觉外观。
`.tp--light` / `.tp--dark`	主题修饰符	与主题一起应用于 `.tp-widget`；定义所有 `--tp-*` 自定义属性。
`.tp-bar`	栏	玻璃拟态胶囊主体：背景、背景模糊、边框、`99px` 圆角半径和阴影。宽度为 `300px`。
`.tp-meta`	文本块	所有文本的容器——空闲时为标题和副标题，通话期间为智能体名称和状态。
`.tp-name`	主标签	空闲时显示 `title` 属性；通话期间显示已连接智能体的名称（若无则回退使用 `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;
}

空闲标签位于 .tp-name/.tp-sub 中，而非 .tp-status——仅隐藏 .tp-status 时，小组件空闲时仍会显示标题。

特定主题覆盖

使用主题类定位特定主题：

/* 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 中定位该类：

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

.support-widget .tp-name {
  font-weight: 700;
}

这样您可以在同一页面上使用多个具有不同样式的小组件实例。通过各自的 primaryColor prop 为每个实例设置独立的强调色（CSS 无法覆盖 --tp-accent——它以内联方式设置）。

完全自定义 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>
  )
}

当您需要音频响应式动画、自定义布局，或与现有组件库集成时，无头 Hook 是合适的选择。CSS 覆盖和自定义属性更适合快速调整主题。

​主题

​CSS 自定义属性

​覆盖自定义属性

​CSS 类

​示例

​通过 Props 自定义强调色

​通过 CSS 自定义颜色

​自定义尺寸

​隐藏文本标签

​特定主题覆盖

​使用 className 设定作用域

​完全自定义 UI

主题

CSS 自定义属性

覆盖自定义属性

CSS 类

示例

通过 Props 自定义强调色

通过 CSS 自定义颜色

自定义尺寸

隐藏文本标签

特定主题覆盖

使用 className 设定作用域

完全自定义 UI