企业官网建设流程全解析

wavesurfer.js核心选项全解析：12个常用配置项帮你调出专业级波形效果

【免费下载链接】wavesurfer.jsAudio waveform player项目地址: https://gitcode.com/gh_mirrors/wa/wavesurfer.js

wavesurfer.js 是一款轻量级音频波形播放器（Audio waveform player），只需几行代码就能在网页上渲染出可交互的音频波形。但很多新手只知道最基础的用法，却调不出理想的视觉效果。本文将带你逐一拆解wavesurfer.js 核心选项，精选 12 个最常用的配置项，帮你快速调出专业级波形效果。

快速上手：3行代码创建波形

全部选项都通过WaveSurfer.create()传入，完整类型定义见 src/wavesurfer.ts。

import WaveSurfer from 'wavesurfer.js' const wavesurfer = WaveSurfer.create({ container: document.body, // 渲染容器（必填） url: '/audio/demo.wav', // 音频地址 })

更多可动手调节的演示，可直接查看 examples/all-options.js 和 examples/basic.js。

一、基础配置：容器与音频源

1. container —— 波形渲染容器（必填）

唯一必填项。传一个 DOM 元素或 CSS 选择器字符串，波形就会画在里面。

2. url —— 音频文件地址

支持 mp3、wav、ogg 等浏览器可解码的格式。加载完成后会触发ready事件。

3. height 与 width —— 波形尺寸

• height：像素数值，或'auto'填满容器高度（默认 auto）
• width：像素或任意 CSS 值（如'300px'），默认100%

💡 小建议：让height跟随容器自适应，配合 CSS 布局更省事。

二、视觉风格：配色与波形形态

4. waveColor 与 progressColor —— 未播放/已播放颜色

两个颜色可以随意搭配，也支持数组（多通道渐变）和CanvasGradient 渐变对象。参考 examples/gradient.js 可做出渐变色波形。

waveColor: '#999', // 默认灰色 progressColor: '#555', // 默认深灰

5. cursorColor 与 cursorWidth —— 播放光标

光标是播放头的那条竖线。默认宽 1px（见 默认值配置），调大cursorWidth到 2~3 会更醒目。

6. barWidth、barGap、barRadius —— 柱状波形三件套

只要给barWidth设置大于 0 的值，波形立刻从实心变为 SoundCloud 风格的柱状条 ▁▂▇▃，再搭配间隙与圆角：

barWidth: 2, // 柱子宽度 barGap: 1, // 柱子间隙 barRadius: 2, // 圆角

完整示例见 examples/bars.js。

7. normalize —— 拉伸到满高

设为true后，波形会被拉伸占满整个高度，小音量音频也能看得清清楚楚，做演示页面很实用。

三、交互与播放：点击、缩放、自动滚动

8. interact 与 dragToSeek —— 点击跳转与拖拽定位

• interact：设为false可禁用点击（默认允许点击波形跳转进度）
• dragToSeek：允许按住光标拖动跳转，体验更顺滑

9. minPxPerSec —— 缩放级别（像素/秒）

这是实现"波形缩放"的关键选项：值越大，波形拉得越长。配合滚动条还能实现音频剪辑器式体验，完整演示在 examples/zoom.js。

10. autoScroll 与 autoCenter —— 自动跟随播放头

• autoScroll（默认 true）：自动滚动容器，让播放位置始终可见
• autoCenter（默认 true）：播放时保持光标居中

关闭autoScroll或配合hideScrollbar: true，可获得更"静态展示"的风格。

四、进阶玩法：多通道与插件

11. splitChannels —— 多通道分开显示

立体声音频可以拆成左右两条波形，各自独立配色：

splitChannels: [ { waveColor: 'rgb(200, 0, 200)', progressColor: 'rgb(100, 0, 100)' }, { waveColor: 'rgb(0, 200, 200)', progressColor: 'rgb(0, 100, 100)' }, ]

效果演示见 examples/split-channels.js。

12. plugins —— 加载官方插件

通过plugins数组可在创建时直接挂载官方插件，全部插件源码位于 src/plugins/，包括：

• Regions：在波形上标记区间、剪切片段
• Timeline：底部时间刻度
• Spectrogram：声谱图叠加，无标签版本见下图
• Minimap、Hover、Zoom、Record、Envelope

12个选项速查表

写在最后

掌握以上 12 个核心选项，基本能覆盖 90% 的波形定制场景：先定容器和音频源，再用颜色与柱状选项调风格，最后用缩放、拖拽和插件补齐交互。更多细节欢迎翻阅项目 README.md 与 examples/ 目录下的 30 余个示例，每个选项都配有可直接运行的演示页面。

【免费下载链接】wavesurfer.jsAudio waveform player项目地址: https://gitcode.com/gh_mirrors/wa/wavesurfer.js