异常教程

HTML 音频/视频 DOM played 属性（长文讲解）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

前言

随着 HTML5 的普及，网页中嵌入音频和视频变得越来越简单。然而，要实现更复杂的交互功能，开发者需要深入理解媒体元素的 DOM 属性。其中，“HTML 音频/视频 DOM played 属性”是一个关键工具，它能帮助开发者精准获取媒体文件的已播放时间范围，从而实现进度条、播放统计等功能。本文将从基础概念出发，通过案例和代码示例，逐步解析这一属性的用法和应用场景，帮助读者掌握其核心原理。

什么是 HTML 音频/视频 DOM played 属性？

HTML 音频/视频 DOM played 属性是 HTML5 提供的一个接口，用于返回一个 TimeRanges 对象，该对象记录了媒体文件中用户已播放的时间范围。简单来说，它告诉开发者用户在播放过程中，哪些时间段的媒体内容已经被加载并播放过。

核心概念解析

  • TimeRanges 对象：这是一个类似数组的结构，包含多个时间段（start 到 end）。
  • 播放片段的不连续性：由于网络延迟、用户拖动进度条或视频分段加载等原因，已播放的时间可能呈现多个不连续的区间。

比喻说明：
可以将播放过程想象为驾驶一辆汽车。played 属性记录的是你已经行驶过的路段，而这些路段可能因红绿灯、绕路或中途下车而形成多个不连续的区间。

如何获取和使用 played 属性？

基础语法

通过 JavaScript 可以直接访问媒体元素的 played 属性：

const videoElement = document.getElementById("myVideo");
const playedRanges = videoElement.played;

解析 TimeRanges 对象

TimeRanges 对象包含以下两个关键方法：

  • start(index)：返回指定索引的播放区间的起始时间（秒）。
  • end(index)：返回指定索引的播放区间的结束时间（秒）。

示例代码：

// 假设用户播放了 0-10 秒和 20-30 秒的内容
console.log(playedRanges.length); // 输出：2
console.log(playedRanges.start(0)); // 输出：0
console.log(playedRanges.end(1)); // 输出：30

实际案例：计算已播放的总时长

通过遍历 TimeRanges 对象，可以计算用户实际播放的总时长：

function getPlayedDuration(timeRanges) {
  let total = 0;
  for (let i = 0; i < timeRanges.length; i++) {
    total += timeRanges.end(i) - timeRanges.start(i);
  }
  return total;
}

const totalPlayed = getPlayedDuration(videoElement.played);
console.log(`用户已播放总时长：${totalPlayed} 秒`);

场景应用

  • 统计用户行为：分析用户对视频内容的兴趣区间。
  • 进度条实现：动态更新进度条的已播放部分。

进阶技巧：结合其他属性实现交互功能

1. 计算剩余未播放时间

结合 duration 属性（总时长）和 played 属性，可以计算剩余未播放的时间：

const remainingTime = videoElement.duration - getPlayedDuration(videoElement.played);
console.log(`剩余未播放时间：${remainingTime} 秒`);

2. 实现动态进度条

通过监听 timeupdate 事件，实时更新进度条的样式：

<div id="progressBar" style="width: 300px; background: #eee;">
  <div id="playedBar" style="width: 0%; background: #4CAF50;"></div>
</div>

<script>
const progressBar = document.getElementById("progressBar");
const playedBar = document.getElementById("playedBar");

videoElement.addEventListener("timeupdate", () => {
  const played = videoElement.played.end(0) || 0;
  const percentage = (played / videoElement.duration) * 100;
  playedBar.style.width = `${percentage}%`;
});
</script>

3. 检测用户是否完整观看视频

通过比较 played 的总时长与 duration，可以判断用户是否完整播放了视频：

function isVideoCompleted() {
  const playedTotal = getPlayedDuration(videoElement.played);
  return playedTotal >= videoElement.duration;
}

常见问题与解决方案

问题 1：TimeRanges 对象为何包含多个区间？

原因：用户可能中途暂停、拖动进度条或视频因网络问题分段加载。
解决方案：遍历所有区间，避免仅依赖第一个区间（end(0)）。

问题 2：如何处理未播放的片段？

方法：通过对比 TimeRanges 与总时长，找出未播放的区域：

function getUnplayedRanges(timeRanges, duration) {
  let unplayed = [];
  let current = 0;
  for (let i = 0; i < timeRanges.length; i++) {
    if (timeRanges.start(i) > current) {
      unplayed.push({ start: current, end: timeRanges.start(i) });
    }
    current = timeRanges.end(i);
  }
  if (current < duration) {
    unplayed.push({ start: current, end: duration });
  }
  return unplayed;
}

关键点总结：与相关属性的对比

属性名描述示例用法
currentTime当前播放位置（秒）video.currentTime = 10;
duration媒体总时长（秒）console.log(video.duration);
played已播放时间范围（TimeRanges 对象）video.played.end(0)

结论

通过掌握 HTML 音频/视频 DOM played 属性，开发者能够实现更精细的媒体控制功能，例如动态进度条、播放统计和用户行为分析。本文通过基础概念、代码示例和实际案例，逐步展示了该属性的使用方法和潜在应用场景。建议读者通过实践项目（如自定义播放器）巩固知识，同时注意结合 currentTime 和 duration 等属性，以实现更复杂的交互逻辑。

未来，随着 Web 技术的发展，媒体元素的 API 将持续扩展，开发者需保持对新特性的关注，以提升用户体验和功能深度。

最新发布

查看更多文章