1. Web
  2. Web API
  3. MediaSession
  4. setActionHandler()

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

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

togglescreenshare

开启或关闭用户的活动屏幕共享。

回调

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

action

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

fastSeek 可选

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

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

浏览器兼容性

帮助改进 MDN

了解如何贡献

此页面最后修改时间为 ，由 MDN 贡献者 修改。

在 GitHub 上查看此页面 • 报告此内容的问题
© . Content available under a Creative Commons license.