音乐播放器代码怎么写：从播放、暂停到进度控制

网页音乐播放器看起来只是几个按钮和一条进度条，真正需要处理的却不只是“点按钮后播放”。浏览器可能拒绝自动播放，音频元数据可能尚未加载，网络中断会让播放失败，直播流也未必有固定时长。要写出可靠的播放器，先要理解浏览器提供的音频接口，再围绕播放状态和媒体事件组织界面。

本文使用原生 HTML 音频元素 <audio> 和 JavaScript 实现一个简单播放器，包含播放、暂停、进度显示与拖动、音量控制、静音和倍速。示例面向普通网页音频，不依赖框架，也不负责音频上传、解码、剪辑或版权保护。

一、适用场景与实现选择

如果需求是播放一首或多首常规音频，例如播客、课程、音乐试听或站内音效，优先考虑 <audio>。浏览器负责媒体解码、缓冲和输出，JavaScript 通过 HTMLAudioElement 控制播放状态与播放位置。和自行解码相比，这种方式实现成本低，也能使用浏览器的媒体兼容机制。

原生播放器自带控制栏，最小实现只需要：

<audio controls src="audio/example.mp3">
  您的浏览器不支持音频播放。
</audio>

设置 controls 后，播放、进度和音量等控件由浏览器提供。不同浏览器和操作系统的外观可能不同。如果需要统一布局、增加章节列表或展示业务状态，可以隐藏原生控制栏，使用 JavaScript 构建自定义界面；但这也意味着键盘操作、焦点、状态提示等细节需要由开发者负责。

以下情况可能需要其他方案：需要对音频做实时分析、混音或效果处理时，可结合 Web Audio API；需要直播、低延迟分片或自适应码率时，通常还要引入相应的流媒体方案。它们不是普通音乐播放控件的必要组成部分。

二、先理解音频元素的状态

JavaScript 中的 audio 对象既是媒体元素，也是播放状态的来源。常用属性和方法包括：

• play()：请求开始或继续播放。它返回 Promise；浏览器拒绝播放时，Promise 可能以异常拒绝，不能假设调用后一定已经播放。
• pause()：暂停播放。重复调用通常没有问题。
• paused：表示当前是否暂停，但它不能单独解释所有加载、缓冲和错误状态。
• currentTime：当前播放位置，单位为秒。读取时可能是零；设置时会发起跳转，但具体行为受媒体资源和可跳转范围影响。
• duration：媒体时长，单位为秒。元数据尚未加载或时长未知时可能是 NaN；部分实时媒体可能没有有限的结束时间。
• volume：音量，取值范围为 0 到 1。浏览器和设备仍可能对实际输出音量施加限制。
• playbackRate：播放速率。具体支持范围及音高处理效果会因浏览器和媒体而异，不应把任意数值都视作跨浏览器保证。

播放器界面应响应媒体事件，而不是只在按钮点击时改文字。例如，loadedmetadata 表示元数据已可用；timeupdate 在播放位置变化时触发；play、pause 和 ended 分别反映播放开始、暂停和播放结束。网络加载状态还可通过 waiting、canplay、error 等事件观察。

三、可运行的基础播放器

将下面代码保存为 HTML 文件，并把 audio/example.mp3 替换为实际可访问的音频地址。测试时，音频文件需要由本地开发服务器或网站服务器提供；直接打开 HTML 文件时，相对路径未必指向正确位置。示例隐藏了原生控制栏，因此保留了自定义控件和状态提示。

<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>简易音乐播放器</title>
  <style>
    body {
      max-width: 620px;
      margin: 40px auto;
      padding: 0 16px;
      font: 16px/1.6 system-ui, sans-serif;
    }
    .row {
      display: flex;
      align-items: center;
      gap: 10px;
      margin: 12px 0;
    }
    input[type="range"] {
      flex: 1;
      min-width: 80px;
    }
    button, select {
      font: inherit;
    }
    #status {
      min-height: 1.6em;
    }
  </style>
</head>
<body>
  <h1>简易音乐播放器</h1>

  <audio id="audio" preload="metadata">
    <source src="audio/example.mp3" type="audio/mpeg">
    您的浏览器不支持音频播放。
  </audio>

  <div class="row">
    <button id="playButton" type="button">播放</button>
    <span id="status" role="status" aria-live="polite">等待加载</span>
  </div>

  <div class="row">
    <label for="seek">进度</label>
    <input id="seek" type="range" min="0" max="1000" value="0"
           step="1" aria-label="播放进度" disabled>
    <span id="time">00:00 / --:--</span>
  </div>

  <div class="row">
    <button id="muteButton" type="button" aria-pressed="false">静音</button>
    <label for="volume">音量</label>
    <input id="volume" type="range" min="0" max="1" step="0.01"
           value="1" aria-label="音量">
    <label for="rate">速度</label>
    <select id="rate" aria-label="播放速度">
      <option value="0.75">0.75 倍</option>
      <option value="1" selected>1 倍</option>
      <option value="1.25">1.25 倍</option>
      <option value="1.5">1.5 倍</option>
      <option value="2">2 倍</option>
    </select>
  </div>

  <script>
    const audio = document.querySelector("#audio");
    const playButton = document.querySelector("#playButton");
    const seek = document.querySelector("#seek");
    const timeLabel = document.querySelector("#time");
    const status = document.querySelector("#status");
    const volume = document.querySelector("#volume");
    const muteButton = document.querySelector("#muteButton");
    const rate = document.querySelector("#rate");

    function formatTime(seconds) {
      if (!Number.isFinite(seconds) || seconds < 0) return "--:--";
      const total = Math.floor(seconds);
      const minutes = Math.floor(total / 60);
      const remainingSeconds = total % 60;
      return String(minutes).padStart(2, "0") + ":" +
        String(remainingSeconds).padStart(2, "0");
    }

    function hasFiniteDuration() {
      return Number.isFinite(audio.duration) && audio.duration > 0;
    }

    function updateProgress() {
      const finiteDuration = hasFiniteDuration();
      seek.disabled = !finiteDuration;

      if (finiteDuration) {
        const ratio = Math.min(1, Math.max(0, audio.currentTime / audio.duration));
        seek.value = String(Math.round(ratio * Number(seek.max)));
      } else {
        seek.value = "0";
      }

      timeLabel.textContent =
        formatTime(audio.currentTime) + " / " +
        (finiteDuration ? formatTime(audio.duration) : "--:--");
    }

    playButton.addEventListener("click", async () => {
      if (audio.paused) {
        status.textContent = "正在启动播放…";
        try {
          await audio.play();
        } catch (error) {
          status.textContent = "无法播放，请检查音频地址或浏览器权限。";
          console.error("音频播放失败：", error);
        }
      } else {
        audio.pause();
      }
    });

    audio.addEventListener("play", () => {
      playButton.textContent = "暂停";
      status.textContent = "正在播放";
    });

    audio.addEventListener("pause", () => {
      playButton.textContent = "播放";
      if (!audio.ended) status.textContent = "已暂停";
    });

    audio.addEventListener("ended", () => {
      playButton.textContent = "播放";
      status.textContent = "播放结束";
      updateProgress();
    });

    audio.addEventListener("loadedmetadata", updateProgress);
    audio.addEventListener("durationchange", updateProgress);
    audio.addEventListener("timeupdate", updateProgress);

    audio.addEventListener("waiting", () => {
      status.textContent = "缓冲中…";
    });

    audio.addEventListener("canplay", () => {
      if (!audio.paused) status.textContent = "正在播放";
    });

    audio.addEventListener("error", () => {
      status.textContent = "音频加载失败，请检查文件和网络。";
      console.error("音频元素错误：", audio.error);
    });

    seek.addEventListener("input", () => {
      if (!hasFiniteDuration()) return;
      const fraction = Number(seek.value) / Number(seek.max);
      audio.currentTime = fraction * audio.duration;
      updateProgress();
    });

    volume.addEventListener("input", () => {
      audio.volume = Number(volume.value);
      audio.muted = false;
      muteButton.setAttribute("aria-pressed", "false");
      muteButton.textContent = "静音";
    });

    muteButton.addEventListener("click", () => {
      audio.muted = !audio.muted;
      muteButton.setAttribute("aria-pressed", String(audio.muted));
      muteButton.textContent = audio.muted ? "取消静音" : "静音";
    });

    rate.addEventListener("change", () => {
      audio.playbackRate = Number(rate.value);
    });

    updateProgress();
  </script>
</body>
</html>

四、播放与暂停：以媒体事件同步界面

点击播放按钮时，代码先检查 audio.paused，再调用 audio.play()。等待它返回的 Promise，可以捕获浏览器拒绝播放、资源不可用等情况。拒绝原因可能包括自动播放策略、用户设置或媒体错误；异常类型和具体提示文字不应被当作固定协议，实际产品可以根据需要记录错误并展示通用说明。

即使播放请求成功，也建议由 play 和 pause 事件更新按钮。这样，界面状态来自音频元素本身，而不是仅根据某次点击推断。实际项目还可能通过耳机按键、系统媒体控件或其他脚本改变播放状态；只在点击处理器里切换按钮文字，容易出现控件显示“暂停”，音频却已经暂停的情况。

页面加载后自动调用 play() 并不可靠。浏览器通常会限制没有用户交互触发的有声自动播放，具体行为取决于浏览器、用户设置和上下文。不要把自动播放当作首屏必然行为；如果产品确有需求，应在播放请求被拒绝时提供清楚的手动播放入口。静音媒体在部分环境下有不同策略，但也不宜据此假设所有浏览器都允许自动播放。

五、进度显示与拖动跳转

示例将进度条范围设为 0 到 1000，再换算成时长比例。这只是界面刻度，并不是音频位置的精度限制。用户拖动到某个刻度后，代码把比例乘以 duration，再赋给 currentTime。如果产品需要显示时间刻度，也可以把范围直接设置为时长；但元数据未加载时，时长不可用，不能提前把它当作有效数值。

代码监听进度条的 input 事件，因此拖动时会不断请求跳转。长音频或网络资源上，这可能导致频繁 seek 请求。若希望用户松开滑块后才跳转，可以在 input 中只更新预览位置，在 change 事件中设置 currentTime；也可以在拖动过程中暂停界面上的进度刷新，避免播放事件不断覆盖用户正在拖动的值。

对普通、可跳转的文件，按总时长换算通常够用。但并非所有媒体都能从零开始跳到总时长中的任意位置。流媒体可能只保留一段可访问窗口，媒体也可能暂时尚未缓冲目标位置。更严格的播放器应结合 audio.seekable 检查可跳转时间范围，并在设置 currentTime 时处理失败情况；不要仅凭进度条显示了一个位置，就认为资源一定能立即跳过去。

六、时长、缓冲与结束状态的边界

duration 在元数据未加载时可能是 NaN，而不是零。把它直接写进进度计算，容易得到 NaN，再导致滑块或显示文本异常。示例使用 Number.isFinite() 判断时长是否为有限数值，并在未知时显示 --:--、禁用进度条。

有些实时媒体没有固定结束时间，时长可能是正无穷；有些直播场景的可跳转范围也会随时间变化。此时“当前时间除以总时长”的进度条没有合适的含义，应根据产品需求展示直播状态或可回看的时间窗口，而不是硬造一个百分比。

还要区分“已经开始播放”和“数据足够连续播放”。play 事件表示播放状态变化，不能保证之后永不缓冲。waiting 可用来提示等待数据，canplay 可用于更新状态，但媒体网络状态仍可能继续变化。不要因为收到一次 canplay 就移除所有错误处理。

七、音量、静音与倍速

HTML 媒体元素的 volume 取值按接口约定处于 0 到 1 之间，因此音量滑块可将此范围映射到实际属性。示例在音量变化时取消静音；这是一种界面选择，并非接口强制要求。也可以保留静音状态，让用户调节音量后再手动取消静音，但要让按钮状态与实际属性一致。

静音通常通过布尔属性 muted 控制。音量设为零和设置静音听起来相近，但语义不同：用户可能希望先记住原音量，再临时静音。切换静音时不需要把音量值改成零。

playbackRate 可以用于倍速播放，但设备、媒体和浏览器对速率及音高处理的支持并不完全一致。示例只提供几个常用选项，没有假设任意速率都有效。面向跨浏览器产品时，应在目标设备上实测；如果某个速率未按预期生效，要避免让界面显示一个与实际播放不同的数值。

八、音频地址与安全注意事项

示例中的音频地址是固定字符串。生产环境应确保地址指向可信的音频资源，并由服务器正确返回媒体内容。用户上传的文件不能仅靠扩展名判断内容是否安全；服务端还需要按业务要求验证文件类型、大小和处理方式，并避免把不可信文件直接作为可执行页面提供。

如果播放地址来自用户输入，不要把未经检查的内容拼进 innerHTML。设置文本信息应使用 textContent，媒体地址则应按应用允许的来源和协议进行校验。浏览器的媒体元素不会因为接收了一个 URL 就自动替你完成业务授权，也不会替代服务端的访问控制。

跨域音频有一个容易混淆的边界：仅通过媒体元素播放另一个来源的资源，与把音频样本交给 Web Audio API 做分析或处理，不是同一件事。普通播放在一些场景下可以加载跨域资源；若要通过 Web Audio API 读取音频数据，通常需要设置合适的跨域模式，并由资源服务器返回允许该来源的 CORS 响应头。是否能访问数据不能仅凭“听得到声音”来判断。

原生音频播放也不等于数字版权管理。隐藏下载入口、限制进度条或把地址放在 JavaScript 中，都不能可靠地保护可被用户播放的媒体。若业务涉及授权、付费访问或 DRM，应在服务端和相应媒体技术层面设计权限与保护机制。

九、可访问性与产品细节

原生按钮、范围输入和下拉框通常具有较好的键盘基础。自定义控件应保留合适的表单语义和可读标签，避免只用图标表达操作而没有可访问名称。示例通过 label、aria-label 和状态区域补充说明；实际页面还应检查焦点样式、键盘操作和屏幕阅读器播报，避免状态频繁变化造成干扰。

进度条同时显示已播放时间和总时长，能帮助用户理解当前位置。时间格式示例按分钟显示，超过一小时后分钟数会继续增长，例如 01:05:00 会显示为 65:00。如果产品需要小时格式，应修改时间格式化函数，而不是假设所有音频都短于一小时。

如果一个页面包含多首音频，建议为每个播放器建立独立实例和事件绑定，避免所有控件误操作同一个全局变量。切换曲目时要明确是否重置播放位置、音量和倍速，并处理上一首尚未完成的异步播放请求。页面卸载或组件销毁时，应移除自行注册的事件监听器，尤其是在单页应用反复挂载播放器的场景中。

十、常见错误检查清单

• 把 play() 当作同步操作：它可能失败。使用 Promise 处理结果，并保留播放失败提示。
• 假定元数据一开始就存在：在读取时长和允许拖动前，检查数值是否有限，必要时监听 loadedmetadata 和 durationchange。
• 只在按钮点击时改界面：播放状态应通过媒体事件同步，避免界面与实际状态不一致。
• 认为所有音频都可以任意 seek：实时流、尚未加载的资源和受限时间窗口都可能改变跳转行为。更复杂的场景应检查 seekable。
• 把缓冲当作播放结束：waiting 表示等待数据，不等于 ended。两种状态要分别处理。
• 依赖自动播放：用户没有交互时，浏览器可能拒绝有声播放。提供可操作的播放按钮，并处理拒绝结果。
• 只凭后缀判断媒体可用：地址、服务器响应、编码格式和浏览器支持都可能影响播放。必要时使用多个 source，并在目标浏览器测试。
• 把隐藏控件当成安全措施：自定义播放器只是界面，不是媒体访问控制或版权保护方案。

总结

普通网页音乐播放器可以从 <audio> 开始：播放请求用 play() 并处理其 Promise，播放位置通过 currentTime 控制，时长和状态由属性及媒体事件获得。进度条应考虑元数据未加载、时长未知和资源不可跳转等情况；自动播放、跨域读取和媒体授权也各有边界。

先用原生媒体元素做出行为正确的最小版本，再根据需求增加播放列表、加载提示、章节跳转或 Web Audio 处理，通常比一开始就自行实现复杂播放内核更稳妥。开发时重点测试实际音频文件、目标浏览器、移动设备和网络异常，而不只是确认按钮能响应点击。