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.