MediaSession：setActionHandler() 方法

可用性有限

此功能不是基线功能，因为它在一些最常用的浏览器中无法正常工作。

setActionHandler() 方法是 MediaSession 接口的方法，用于设置媒体会话操作的处理程序。这些操作允许 Web 应用程序在用户使用设备内置的物理或屏幕媒体控件（例如播放、停止或搜索按钮）时接收通知。

语法

js
setActionHandler(type, callback)

参数

type

表示要监听的操作类型的字符串。它将是以下之一

hangup

结束通话。

nextslide

在演示幻灯片时，切换到下一张幻灯片。

nexttrack

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

pause

暂停媒体播放。

play

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

previousslide

在演示幻灯片时，切换到上一张幻灯片。

previoustrack

返回上一首曲目。

seekbackward

从当前位置向后搜索媒体。传递给回调的 seekOffset 属性指定向后搜索的时间量。

seekforward

从当前位置向前搜索媒体。传递给回调的 seekOffset 属性指定向前搜索的时间量。

seekto

将播放位置移动到媒体中指定的时间。要搜索到的时间在传递给回调的 seekTime 属性中指定。如果您打算连续快速执行多个 seekto 操作，您还可以将传递给回调的 fastSeek 属性设置为 true。这使浏览器知道它可以采取措施优化重复操作，并且可能会提高性能。

skipad

跳过当前正在播放的广告或商业广告。此操作可能可用也可能不可用，具体取决于平台和 用户代理，或者可能由于订阅级别或其他情况而被禁用。

stop

完全停止播放。

togglecamera

打开或关闭用户的活动摄像头。

togglemicrophone

静音或取消静音用户的麦克风。

callback

调用指定操作类型时要调用的函数。回调不应返回值。回调接收一个包含以下属性的字典

action

表示操作类型的字符串。此属性允许单个回调处理多个操作类型。

fastSeek 可选

seekto 操作可以选择包含此属性，该属性是一个布尔值，指示是否执行“快速”搜索。“快速”搜索是在快速序列中执行的搜索，例如在媒体中快进或倒退，快速跳过它。此属性可用于指示您应使用最短的方法来搜索媒体。在这种情况下，此属性不会包含在搜索序列中的最终操作中。

seekOffset 可选

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

seekTime 可选

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

返回值

无 (undefined）。

描述

要移除之前已建立的操作处理程序，请再次调用 setActionHandler()，并将 null 指定为 callback。

操作处理程序接收一个参数作为输入：一个对象，它同时提供操作类型（因此同一个函数可以处理多个操作类型），以及执行操作所需的数据。

示例

为音乐播放器设置操作处理程序

此示例创建一个新的媒体会话，并为其分配操作处理程序（这些处理程序不执行任何操作）。

js
if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: "Unforgettable",
    artist: "Nat King Cole",
    album: "The Ultimate Collection (Remastered)",
    artwork: [
      {
        src: "https://dummyimage.com/96x96",
        sizes: "96x96",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/128x128",
        sizes: "128x128",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/192x192",
        sizes: "192x192",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/256x256",
        sizes: "256x256",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/384x384",
        sizes: "384x384",
        type: "image/png",
      },
      {
        src: "https://dummyimage.com/512x512",
        sizes: "512x512",
        type: "image/png",
      },
    ],
  });

  navigator.mediaSession.setActionHandler("play", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("pause", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("stop", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekbackward", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekforward", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("seekto", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("previoustrack", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("nexttrack", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("skipad", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("togglecamera", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("togglemicrophone", () => {
    /* Code excerpted. */
  });
  navigator.mediaSession.setActionHandler("hangup", () => {
    /* Code excerpted. */
  });
}

以下示例为播放和暂停设置了两个函数，然后将它们用作回调，并使用相关的操作处理程序。

js
const actionHandlers = [
  // play
  [
    "play",
    async () => {
      // play our audio
      await audioEl.play();
      // set playback state
      navigator.mediaSession.playbackState = "playing";
      // update our status element
      updateStatus(allMeta[index], "Action: play  |  Track is playing…");
    },
  ],
  [
    "pause",
    () => {
      // pause out audio
      audioEl.pause();
      // set playback state
      navigator.mediaSession.playbackState = "paused";
      // update our status element
      updateStatus(allMeta[index], "Action: pause  |  Track has been paused…");
    },
  ],
];

for (const [action, handler] of actionHandlers) {
  try {
    navigator.mediaSession.setActionHandler(action, handler);
  } catch (error) {
    console.log(`The media session action "${action}" is not supported yet.`);
  }
}

此示例使用适当的操作处理程序来允许通过正在播放的媒体向前或向后搜索。

js
navigator.mediaSession.setActionHandler("seekbackward", (evt) => {
  // User clicked "Seek Backward" media notification icon.
  let skipTime = evt.seekOffset || 10; // Time to skip in seconds
  audio.currentTime = Math.max(audio.currentTime - skipTime, 0);
});

navigator.mediaSession.setActionHandler("seekforward", (evt) => {
  // User clicked "Seek Forward" media notification icon.
  let skipTime = evt.seekOffset || 10; // Time to skip in seconds
  audio.currentTime = Math.min(audio.currentTime + skipTime, audio.duration);
});

要移除媒体操作处理程序，请将其分配为 null。

js
navigator.mediaSession.setActionHandler("nexttrack", null);

在一个处理程序函数中支持多个操作

如果您愿意，还可以使用单个函数来处理多个操作类型，方法是检查 action 属性的值

js
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 操作。

使用操作处理程序控制幻灯片演示

"previousslide" 和 "nextslide" 操作处理程序可用于处理在幻灯片演示中向前和向后移动，例如，当用户将其演示放入 画中画 窗口并按下浏览器提供的用于导航幻灯片的控件时。

js
try {
  navigator.mediaSession.setActionHandler("previousslide", () => {
    log('> User clicked "Previous Slide" icon.');
    if (slideNumber > 1) slideNumber--;
    updateSlide();
  });
} catch (error) {
  log('Warning! The "previousslide" media session action is not supported.');
}

try {
  navigator.mediaSession.setActionHandler("nextslide", () => {
    log('> User clicked "Next Slide" icon.');
    slideNumber++;
    updateSlide();
  });
} catch (error) {
  log('Warning! The "nextslide" media session action is not supported.');
}

有关工作示例，请参阅 演示幻灯片 / 媒体会话示例。

规范

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

浏览器兼容性

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