MediaSession:setPositionState() 方法

setPositionState() 方法是 MediaSession 接口的方法,用于更新当前文档的媒体播放位置和速度,以便用户设备在任何提供有关正在进行的媒体详细信息的界面中呈现。如果您的代码实现了不支持浏览器直接支持的媒体类型的播放器,这将非常有用。

navigator 对象的 mediaSession 对象上调用此方法。

语法

js
setPositionState()
setPositionState(stateDict)

参数

stateDict 可选

一个对象,提供有关文档正在进行的媒体的播放位置和速度的更新信息。如果对象为空,则会清除现有的播放状态信息。此对象可以包含以下参数

duration 可选

一个浮点值,以秒为单位表示当前媒体的总时长。这应该始终是一个正数,正无穷 (Infinity) 表示没有定义结束的媒体,例如直播流。

playbackRate 可选

一个浮点值,表示媒体播放速度相对于其正常播放速度的比率。因此,值为 1 表示以正常速度播放,2 表示以双倍速度播放,等等。负值表示媒体以反向播放;-1 表示以正常速度但反向播放,-2 表示以双倍速度反向播放,依此类推。

position 可选

一个浮点值,表示媒体最后报告的播放位置(以秒为单位)。这必须始终是一个正值。

返回值

无 (undefined).

异常

TypeError

此错误可能在一系列情况下发生

  • 指定对象的 duration 缺失、为负或为 null
  • 它的 position 为负或大于 duration
  • 它的 playbackRate 为零。

示例

以下是一个更新当前 MediaSession 轨道的位置状态的函数。

js
function updatePositionState() {
  navigator.mediaSession.setPositionState({
    duration: audioEl.duration,
    playbackRate: audioEl.playbackRate,
    position: audioEl.currentTime,
  });
}

当更新 MediaMetadata 以及在操作的回调中(如以下所示)时,我们可以使用此函数。

js
navigator.mediaSession.setActionHandler("seekbackward", (details) => {
  // our time to skip
  const skipTime = details.seekOffset || 10;

  // set our position
  audioEl.currentTime = Math.max(audioEl.currentTime - skipTime, 0);
  updatePositionState();
});

规范

规范
媒体会话
# dom-mediasession-setpositionstate

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。