MediaSessionActionDetails - 触发媒体会话操作时参数

MediaSessionActionDetails 是 Media Session API 的字典，是触发媒体会话操作时参数。它指定需要执行的操作类型以及执行该操作所需的数据。

属性

action

一个媒体会话操作类型字符串，来自 MediaSessionAction 枚举类型，指示需要执行哪种类型的操作。有关可能的值，请参见下面的媒体操作类型。

fastSeek 可选

一个布尔值，指示是否执行 “快速” 搜索，当操作为 seekto 时，可以设置该属性。“快速” 搜索是按快速顺序执行的搜索，例如在媒体中快进或快退时，会快速跳过它。此属性可用于指示您应使用最短的方法查找媒体。在这种情况下，fastSeek 不包括在搜寻序列的最终操作中。

seekOffset 可选

如果 action 是 seekforward 或 seekbackward 且存在此属性，则它是一个浮点值，指示秒数向前或向后移动播放位置。如果不存在此属性，则这些操作应选择一个合理的默认距离以向前或向后跳过（例如 7 或 10 秒）。

seekTime 可选

如果 action 为 seekto，则此属性必须存在，并且必须是浮点值，指示媒体在其中将播放位置移至的绝对时间，其中 0 表示媒体的开始。其他操作类型不存在此属性。

媒体操作类型

使用 MediaSessionAction 枚举类型中的字符串指定媒体会话操作的类型。

值

每个操作都是一个公共媒体会话控制请求。为每个操作提供支持，以允许执行该类型的操作。以下字符串标识了媒体会话操作的当前可用类型：

nexttrack

将播放前进到下一首曲目。

pause

暂停播放媒体。

play

开始（或恢复）媒体播放。

previoustrack

移回上一轨道。

seekbackward

从当前位置向后搜索媒体。 MediaSessionActionDetails 的 seekOffset 属性指定向后搜索的时间。

seekforward

从当前位置向前搜索媒体。MediaSessionActionDetails 的 seekOffset 属性指定向前搜索的时间。

seekto

将播放位置移动到媒体中的指定时间。 MediaSessionActionDetails 的 seekTime 中指定要寻找的时间。如果您打算快速连续执行多个 seekto 操作，则还可以指定 MediaSessionActionDetails 的 fastSeek 属性值为 true。这使浏览器知道它可以采取步骤来优化重复的操作，并有可能提高性能。

skipad

跳过当前播放的广告或广告。根据平台和用户代理，此操作可能有效或无效，或者可能由于订阅级别或其他情况而被禁用。

stop

完全停止播放。

实例

添加操作处理程序

此实例通过设置 seekforward 和 seekforward 操作处理程序来实现音频播放器的向前和向后操作。

let skipTime = 10; // 跳过时间（秒）

navigator.mediaSession.setActionHandler('seekforward', details => {
 // 用户单击 “前进” 的媒体图标。
 audio.currentTime = Math.min(audio.currentTime + skipTime,  
               audio.duration);
});

navigator.mediaSession.setActionHandler('seekbackward', details => {
 // 用户单击 “后退” 的媒体图标。
 audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
});

在这种情况下，seekforward 和 seekbackward 处理程序都使用固定距离，而忽略了传递到处理程序中的 MediaSessionActionDetails 指定的时间。

在一个处理程序功能中支持多种操作

如果需要，您还可以通过检查 MediaSessionActionDetails 对象的 action 属性的值来使用单个函数来处理多种操作类型：

let skipTime = 7;

navigator.mediaSession.setActionHandler("seekforward", handleSeek);
navigator.mediaSession.setActionHandler("seekbackward", handleSeek);

function handleSeek(details) {
  switch(details.action) {
    case "seekforward":
      audio.currentTime = Math.min(audio.currentTime + skipTime,
              audio.duration);
      break;
    case "seekbackward":
      audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
      break;
  }
}

在这里，handleSeek() 函数既可以处理 seekbackward，也可以处理 seekforward。

使用 MediaSessionActionDetails 提供的数据

在此实例中，seekforward 和 seekbackward 处理程序不使用指定的距离，而是使用在 MediaSessionActionDetails 对象的 seekOffset 属性中指定的时间。

navigator.mediaSession.setActionHandler("seekforward", handleSeek);
navigator.mediaSession.setActionHandler("seekbackward", handleSeek);

function handleSeek(details) {
  switch(details.action) {
    case "seekforward":
      audio.currentTime = Math.min(audio.currentTime + details.seekOffset,
                                   audio.duration);
      break;
    case "seekbackward":
      audio.currentTime = Math.max(audio.currentTime - details.seekOffset, 0);
      break;
  }
});

规范

规范 状态 备注
Media Session Standard
MediaSessionActionDetails 的定义		 草稿 初始定义。

桌面浏览器兼容性

暂无兼容数据