---
title: SoundWave 声波
group:
  title: 其他
  path: /SoundWave
  order: 3
---

# SoundWave 音频可视化

音频可视化组件，支持实时音频流和音频文件，音波条和光圈可视化展示

## 示例

<code src="../../examples/SoundWave"></code>


## Props

| 属性      | 类型                                   | 是否必传 | 默认值 | 说明                                                         |
| --------- | -------------------------------------- | -------- | ------ | ------------------------------------------------------------ |
| source    | `MediaStream` &#124; `Blob` &#124; `File` &#124; `null` | 否       | -      | 音频源：MediaStream（用于实时录音可视化）或 Blob/File（用于已录制或上传的音频可视化） |
| mode      | `'wave'` &#124; `'halo'` &#124; `'wave-halo'` | 否       | wave   | 可视化模式：wave-音波条，halo-光圈，wave-halo-同时显示            |
| wave      | `WaveProps`                            | 否       | -      | 音波条配置                                                   |
| halo      | `HaloProps`                            | 否       | -      | 光圈配置                                                     |
| className | `string`                               | 否       | -      | 自定义类名                                                   |

### WaveProps（音波条配置）

| 属性          | 类型                                   | 是否必传 | 默认值     | 说明                                                         |
| ------------- | -------------------------------------- | -------- | ---------- | ------------------------------------------------------------ |
| color         | `string`                               | 否       | #606e85    | 音波颜色                                                     |
| count         | `number`                               | 否       | 52         | 音波数量                                                     |
| waveMode      | `'volume'` &#124; `'random'` &#124; `'wave'` | 否       | volume     | 音波生成模式：volume-按音量大小控制，random-随机生成，wave-波浪形状 |
| minHeight     | `number`                               | 否       | 6          | 音波最小高度（px）                                           |
| maxHeight     | `number`                               | 否       | 30         | 音波最大高度（px）                                           |
| updateInterval | `number`                              | 否       | 110        | 音波更新间隔（毫秒）                                         |
| willCancel    | `boolean`                              | 否       | false      | 是否处于待取消状态（显示红色渐变）                           |

### HaloProps（光圈配置）

| 属性    | 类型                                   | 是否必传 | 默认值 | 说明                                                         |
| ------- | -------------------------------------- | -------- | ------ | ------------------------------------------------------------ |
| color   | `'blue'` &#124; `'pink'`                | 否       | blue   | 光圈颜色：blue-蓝色，pink-粉色                                |
| radius  | `number`                               | 否       | -      | 光圈半径（px），所有光圈使用相同的半径，默认使用内置配置     |
| gradient | `Array<{ stop: number; color: string }>` | 否       | -      | 光圈渐变配置，所有光圈使用相同的渐变，默认使用内置配置       |

### 音频可视化属性定义

```ts
type WaveMode = 'volume' | 'random' | 'wave';
type HaloColor = 'blue' | 'pink';
type SoundWaveMode = 'wave' | 'halo' | 'wave-halo';

interface WaveProps {
  /** 音波颜色，默认为 #606e85 */
  color?: string;
  /** 音波数量，默认52个 */
  count?: number;
  /** 音波生成模式：volume-按音量大小控制，random-随机生成，wave-波浪形状，默认volume */
  waveMode?: WaveMode;
  /** 音波最小高度（px），默认6px */
  minHeight?: number;
  /** 音波最大高度（px），默认30px */
  maxHeight?: number;
  /** 音波更新间隔（毫秒），默认110ms */
  updateInterval?: number;
  /** 是否处于待取消状态（显示红色渐变），默认false */
  willCancel?: boolean;
}

interface HaloProps {
  /** 光圈颜色：blue-蓝色，pink-粉色，默认blue */
  color?: HaloColor;
  /** 光圈半径（px），所有光圈使用相同的半径，默认使用内置配置 */
  radius?: number;
  /** 光圈渐变配置，所有光圈使用相同的渐变，默认使用内置配置 */
  gradient?: Array<{ stop: number; color: string }>;
}

interface SoundWaveProps {
  /** 音频源：MediaStream（用于实时录音可视化）或 Blob/File（用于已录制或上传的音频可视化） */
  source?: MediaStream | Blob | File | null;
  /** 可视化模式：wave-音波条，halo-光圈，wave-halo-同时显示，默认wave */
  mode?: SoundWaveMode;
  /** 音波条配置 */
  wave?: WaveProps;
  /** 光圈配置 */
  halo?: HaloProps;
  /** 自定义类名 */
  className?: string;
}
```