大网数据广告活动
Web 标准与前端开发

Launch Handler API

· 52CE 我爱测

The **Launch Handler API** allows developers to control how a progressive web app (PWA) is launched — for example if it uses an existing window or creates a new one, and how the app's target launch URL is handled.

Launch Handler API

The Launch Handler API allows developers to control how a progressive web app (PWA) is launched — for example if it uses an existing window or creates a new one, and how the app's target launch URL is handled.

Concepts and usage

You can specify launch behavior for your app by adding the launch_handler field to your web app manifest file. This has one sub-field, client_mode, which contains a string value specifying how the app should be launched and navigated to. For example:

{
  "launch_handler": {
    "client_mode": "focus-existing"
  }
}

If not specified, the default client_mode value is auto. Available values are:

  • focus-existing
    • : The most recently interacted with browsing context in a web app window is chosen to handle the launch. This will populate the target launch URL in the LaunchParams.targetURL property of the LaunchParams object passed into the LaunchQueue.setConsumer's callback function. As you'll see below, this allows you to set custom launch handing functionality for your app.
  • navigate-existing
    • : The most recently interacted with browsing context in a web app window is navigated to the target launch URL. The target URL is still made available via LaunchQueue.setConsumer to allow additional custom launch navigation handling to be implemented.
  • navigate-new
    • : A new browsing context is created in a web app window to load the target launch URL. The target URL is still made available via LaunchQueue.setConsumer to allow additional custom launch navigation handling to be implemented.
  • auto
    • : The user agent decides what works best for the platform. For example, <code>navigate-existing</code> might make more sense on mobile, where single app instances are commonplace, whereas <code>navigate-new</code> might make more sense in a desktop context. This is the default value used if provided values are invalid.

When focus-existing is used, you can include code inside the LaunchQueue.setConsumer's callback function to provide custom handling of the LaunchParams.targetURL

window.launchQueue.setConsumer((launchParams) => {
  // Do something with launchParams.targetURL
});

[!NOTE] LaunchParams also has a LaunchParams.files property, which returns a read-only array of FileSystemHandle objects representing any files passed along with the launch navigation via the POST method. This allows custom file handling to be implemented.

Interfaces

  • LaunchParams
    • : Used when implementing custom launch navigation handling in a PWA. When LaunchQueue.setConsumer is invoked to set up the launch navigation handling functionality, the callback function inside setConsumer() is passed a LaunchParams object instance.
  • LaunchQueue
    • : When a progressive web app (PWA) is launched with a launch_handler client_mode value of focus-existing, navigate-new, or navigate-existing, LaunchQueue provides access to functionality that allows custom launch navigation handling to be implemented in the PWA. This functionality is controlled by the properties of the LaunchParams object passed into the LaunchQueue.setConsumer callback function.

Extensions to other interfaces

  • window.launchQueue
    • : Provides access to the LaunchQueue class, which allows custom launch navigation handling to be implemented in a progressive web app (PWA), with the handling context signified by the launch_handler manifest field client_mode value.

Examples

if ("launchQueue" in window) {
  window.launchQueue.setConsumer((launchParams) => {
    if (launchParams.targetURL) {
      const params = new URL(launchParams.targetURL).searchParams;

      // Assuming a music player app that gets a track passed to it to be played
      const track = params.get("track");
      if (track) {
        audio.src = track;
        title.textContent = new URL(track).pathname.slice(1);
        audio.play();
      }
    }
  });
}

This code is included in the PWA, and executed when the app loads, upon launch. The LaunchQueue.setConsumer's callback function extracts the search param out of the LaunchParams.targetURL and, if it finds a track param, uses it to populate an audio element's src and play the audio track that this points to.

See the Musicr 2.0 demo app for full working code.

Specifications

Browser compatibility

See also

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。