更新记录

1.0（2026-01-27）

AudioWave 是一款基于 uni-app 框架开发的高性能音频波形可视化组件，专为语音录制、音频播放等场景设计，支持 H5、APP（Android/iOS）、小程序多端适配。组件通过解析 PCM 音频数据，实时渲染动态声波波形，具备阻尼过渡动画、渐变色彩、自适应尺寸等特性，可根据播放状态自动切换动态 / 静止效果，轻量化且性能优化到位，无需依赖第三方库，开箱即用。

多端兼容：完美适配 H5、APP、小程序，针对不同平台 Canvas 渲染机制做专属适配； 动态可视化：接收 16 位 PCM 音频数据，实时生成对应高度的波形，播放 / 暂停状态下动画自然过渡； 灵活配置：支持自定义波形最大高度、条数、阻尼系数、渐变色彩、背景透明度等； 性能优化：缓存变量减少属性访问、防抖处理窗口 resize、自动回收动画帧，降低性能消耗； 容错机制：Canvas 实例获取失败时自动重试，H5 端支持手动创建 Canvas 兜底。

playState false 播放状态：true（动态波形）、false（波形衰减至静止） pcmData 16 位 PCM 音频数据数组，组件据此生成波形高度 maxHeight 35 波形最大高度（px），防止超出画布 gradientColors Array ['rgba(79,195,247,0.8)','rgba(33,150,243,1)'] 波形渐变颜色（仅 H5 生效，APP / 小程序用第二个颜色作为纯色） dampingFactor 0.12 阻尼系数（0-1），值越大波形过渡动画越快 waveCount 60（需为偶数） 波形条数，条数越多波形越密集，建议 40-80 之间 bgTransparent true 是否启用透明背景

平台兼容性

uni-app(3.7.12)

其他

AudioWave 音频波形可视化插件使用说明

一、插件简介

AudioWave 是一款基于 uni-app 框架开发的高性能音频波形可视化组件，专为需要直观展示音频状态的场景设计。组件支持解析 16 位 PCM 音频数据，实时渲染动态声波效果，可根据播放/暂停状态自动切换动画模式，具备多端适配、灵活配置、性能优化等核心优势，无需依赖第三方库，开箱即用。

1.1 核心特性

• 多端兼容：完美适配 H5、APP（Android/iOS）、小程序（微信/支付宝等）；

• 动态渲染：实时解析 PCM 数据生成对应波形，播放/暂停状态动画自然过渡；

• 灵活配置：支持自定义波形高度、条数、颜色、阻尼速度、背景透明度等；

• 性能优化：缓存核心变量、防抖处理窗口 resize、自动回收动画帧，降低资源消耗；

• 容错机制：Canvas 实例获取失败时自动重试，H5 端支持手动创建 Canvas 兜底。

1.2 适用环境

二、快速上手

2.1 组件引入

1. 将插件文件（AudioWave.vue）放入 uni-app 项目的 components 目录下；

2. 在需要使用的页面/组件中直接引入并注册：

<template>
  <view class="container" style="width: 100%; height: 100px;">
    <!-- 音频波形组件 -->
    <AudioWave 
      ref="audioWaveRef"
      :play-state="isPlaying" 
      :pcm-data="audioPcmData"
    />
  </view>
</template>

<script>
// 引入组件
import AudioWave from '@/components/AudioWave/AudioWave.vue';

export default {
  components: {
    AudioWave // 注册组件
  },
  data() {
    return {
      isPlaying: false, // 播放状态（默认暂停）
      audioPcmData: new Int16Array(0) // PCM 音频数据（默认空）
    };
  }
};
</script>

2.2 基础使用示例

以下示例实现“模拟音频播放”功能，通过生成模拟 PCM 数据驱动波形渲染：

<template>
  <view class="demo-container">
    <AudioWave 
      :play-state="isPlaying" 
      :pcm-data="audioPcmData"
      :max-height="40"
      :damping-factor="0.15"
    />
    <button @click="togglePlay" class="play-btn">
      {{ isPlaying ? '暂停' : '播放' }}
    </button>
  </view>
</template>

<script>
import AudioWave from '@/components/AudioWave/AudioWave.vue';

export default {
  components: { AudioWave },
  data() {
    return {
      isPlaying: false,
      audioPcmData: new Int16Array(0),
      mockTimer: null // 模拟数据定时器
    };
  },
  methods: {
    // 播放/暂停切换
    togglePlay() {
      this.isPlaying = !this.isPlaying;
      if (this.isPlaying) {
        // 启动模拟 PCM 数据生成
        this.startMockPcmData();
      } else {
        // 停止模拟
        clearInterval(this.mockTimer);
      }
    },
    // 生成模拟 PCM 数据（模拟音频播放时的数据流）
    startMockPcmData() {
      this.mockTimer = setInterval(() => {
        const mockPcm = new Int16Array(1024);
        // 生成随机 PCM 数据（取值范围：-32768 ~ 32767）
        for (let i = 0; i < mockPcm.length; i++) {
          mockPcm[i] = Math.floor(Math.random() * 32767 - 16384);
        }
        this.audioPcmData = mockPcm;
      }, 50); // 每 50ms 更新一次数据
    }
  },
  beforeDestroy() {
    // 销毁时清理定时器
    clearInterval(this.mockTimer);
  }
};
</script>

<style scoped>
.demo-container {
  padding: 20rpx;
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 30rpx;
}
.play-btn {
  padding: 15rpx 40rpx;
  background: #2196F3;
  color: #fff;
  border-radius: 50rpx;
}
</style>

三、核心配置（Props）

组件支持通过 Props 灵活配置波形样式和行为，所有参数均有默认值，可根据需求选择性配置：

四、核心方法（Methods）

组件提供手动控制波形的方法，需通过 ref 引用组件后调用：

4.1 方法调用示例

<template>
  <view>
    <AudioWave ref="audioWaveRef" :play-state="isPlaying" />
    <button @click="manualUpdate">手动更新波形</button>
  </view>
</template>

<script>
import AudioWave from '@/components/AudioWave/AudioWave.vue';

export default {
  components: { AudioWave },
  data() {
    return {
      isPlaying: true
    };
  },
  methods: {
    manualUpdate() {
      // 生成模拟 PCM 数据
      const mockPcm = new Int16Array(512);
      for (let i = 0; i < mockPcm.length; i++) {
        mockPcm[i] = Math.floor(Math.random() * 32767);
      }
      // 调用组件方法手动更新波形
      this.$refs.audioWaveRef.manualUpdateWave(mockPcm);
    }
  }
};
</script>

五、典型应用场景

5.1 语音录制实时可视化

结合 uni-app 录音 API，实时采集麦克风 PCM 数据并传递给组件，展示录音过程中的动态波形：

<template>
  <view class="recorder-container">
    <AudioWave 
      :play-state="isRecording" 
      :pcm-data="recordPcmData"
      :wave-count="80"
      gradient-colors="['rgba(255, 87, 34, 0.8)', 'rgba(255, 193, 7, 1)']"
    />
    <view class="btn-group">
      <button @click="startRecord" v-if="!isRecording">开始录制</button>
      <button @click="stopRecord" v-else>停止录制</button>
    </view>
  </view>
</template>

<script>
import AudioWave from '@/components/AudioWave/AudioWave.vue';

export default {
  components: { AudioWave },
  data() {
    return {
      isRecording: false,
      recordPcmData: new Int16Array(0),
      recorderManager: null // 录音管理器
    };
  },
  onLoad() {
    // 初始化录音管理器
    this.recorderManager = uni.getRecorderManager();
    // 监听录音数据（实时获取 PCM 数据）
    this.recorderManager.onFrameRecorded((res) => {
      if (this.isRecording) {
        // res.data 为 ArrayBuffer 格式，转换为 Int16Array
        this.recordPcmData = new Int16Array(res.data);
      }
    });
  },
  methods: {
    startRecord() {
      this.isRecording = true;
      // 启动录音（配置为 PCM 格式）
      this.recorderManager.start({
        format: 'pcm',
        sampleRate: 16000,
        numberOfChannels: 1
      });
    },
    stopRecord() {
      this.isRecording = false;
      this.recorderManager.stop();
      // 重置波形数据
      this.recordPcmData = new Int16Array(0);
    }
  }
};
</script>

5.2 音频播放可视化

解析本地/网络音频文件为 PCM 数据，播放时同步传递给组件，实现音频播放与波形可视化同步：

核心思路：通过 AudioContext 解析音频文件，获取 PCM 数据后传递给组件，结合音频播放进度实时更新波形。

六、注意事项

1. PCM 数据格式要求：必须为 Int16Array（16 位整型），取值范围为 -32768 ~ 32767，若传递其他格式会导致波形渲染异常；

2. 性能优化建议：

   • waveCount 建议控制在 40 ~ 80 之间，过多会增加 Canvas 渲染压力，尤其在低端设备上可能出现卡顿；

   • PCM 数据无需全量传递，可按固定步长采样后传递（如每 10 个数据取 1 个），减少数据处理压力；

   • 窗口 resize 时组件会自动适配，无需手动处理，内部已做防抖优化。

3. 多端适配差异：

   • H5 端支持渐变色彩，APP/小程序端暂仅支持纯色渲染；

   • APP/小程序端 Canvas 初始化依赖 uni 原生接口，组件内部已做重试逻辑，若仍失败需检查组件挂载时机（避免页面未渲染完成时使用）。

4. 组件销毁清理：组件在 beforeDestroy 生命周期中已自动清理动画帧和窗口 resize 监听事件，无需手动处理，但需避免重复创建组件实例；

5. Canvas 兜底机制：H5 端若获取 Canvas 实例失败，会自动尝试手动创建 Canvas，若仍失败会打印错误日志，需检查页面 DOM 结构是否正常。

七、常见问题排查

Q1：波形不显示？

• 检查组件容器是否设置了宽高（组件宽高默认继承容器宽高，若容器宽高为 0 则无法显示）；

• 检查 playState 是否设为 true（默认 false 时波形为静止的基础高度，可能视觉不明显）；

• 检查 pcmData 是否为有效的 Int16Array 格式，且数据长度 > 0。

Q2：波形动画卡顿？

• 减少 waveCount 数量（如从 100 调整为 60）；

• 优化 PCM 数据传递频率（如从 30ms/次调整为 50ms/次）；

• 检查是否有其他占用性能的逻辑（如频繁的 DOM 操作）与波形渲染冲突。

Q3：多端显示效果不一致？

• 渐变颜色仅 H5 端生效，APP/小程序端需通过 gradientColors 第二个参数控制纯色；

• 不同平台 Canvas 渲染精度有差异，可通过调整 maxHeight、waveCount 适配不同平台。

  （注：文档部分内容可能由 AI 生成）