通过

使用 Web 应用清单将 PWA 集成到 OS

  • 项目

渐进式 Web 应用 (PWA) 必须具有 Web 应用清单，以定义 PWA 如何与操作系统 (OS) 集成。 本文介绍什么是 Web 应用清单，以及 Web 应用清单包含哪些必需和可选数据。

Web 应用清单文件控制 PWA 在设备上安装时的外观和行为。 Web 应用清单提供信息，例如应用的名称、在系统菜单中代表应用的图标的文件位置，以及操作系统在标题栏中使用的主题颜色。

Web 应用清单是必须使用清单链接从网站的 HTML 页面引用的 JSON 文件。 在网站的 HTML 页面的 和 </head> 标记之间<head>插入以下代码，以链接到清单文件：

<link rel="manifest" href="/manifest.json">

Web 应用清单文件类型

Web 应用清单的内容必须是有效的 JSON，但文件扩展名可以是 .json 或 .webmanifest。

如果选择使用该 .webmanifest 扩展，请验证 HTTP 服务器是否为它提供 application/manifest+json MIME 类型。

清单成员

清单文件至少应包含以下清单成员：

{
    "name": "My Sample PWA",
    "lang": "en-US",
    "start_url": "/"
}

下面是包含更多成员的清单文件示例：

{
    "name": "My Sample PWA",
    "lang": "en-us",
    "short_name": "SamplePWA",
    "description": "A sample PWA for testing purposes",
    "start_url": "/",
    "scope": "/",
    "display": "standalone",
    "theme_color": "#2f3d58",
    "background_color": "#2f3d58",
    "orientation": "any",
    "icons": [
        {
            "src": "/icon512.png",
            "sizes": "512x512"
        }
    ]
}

可以使用其他清单成员进一步自定义 PWA，如下所示：

成员 说明
name 操作系统用来显示在应用图标旁边的应用名称。
short_name 当空间不足 name时，这可用于显示应用的名称。
description 应用的说明。
categories 应用所属的类别列表。
icons 操作系统在不同上下文中使用的图标图像对象的数组。
screenshots 屏幕截图图像对象的数组，也由操作系统在不同的上下文中使用。
start_url 操作系统启动应用时应导航到的首选 URL。
scope 定义应用的导航范围。 在此范围之外，访问的页面将还原为普通网页，而不是 PWA。 这默认为 start_url。
display 应用的外观。 这会更改向用户显示的浏览器 UI 量。
display_override 用于确定应用的首选显示，具体取决于设备支持的内容。
theme_color 应用的默认主题颜色。 这会影响 OS 显示站点的方式。
background_color 应用样式表之前启动应用的窗口的背景色。
orientation 在支持设备上，这将定义应用 (的默认方向，例如横向或纵向) 。
protocol_handlers 与应用关联的预定义或自定义 URI 协议方案的列表。
shortcuts 用户可以通过右键单击或长按应用图标来执行的常见任务列表。
share_target 通过 OS 共享对话框共享内容时应用接受的数据类型。
file_handlers 可启动应用的文件的类型。

若要详细了解清单成员，请参阅 MDN 中的 Web 应用清单 。

处理特定协议方案

可以将 PWA 注册为协议处理程序。 当用户单击使用应用注册到的协议方案的链接时，将自动启动你的应用。 这使用户能够轻松地相互共享指向应用的特定部分或功能的链接。

若要注册为协议处理程序，请使用 protocol_handlers 清单成员：

{
    "protocol_handlers": [
        {
            "protocol": "mailto",
            "url": "/newEmail?to=%s"
        }
    ]
}

若要了解详细信息，请参阅 在渐进式 Web 应用中处理协议。

使用快捷方式提供对功能的快速访问

大多数操作系统通过使用连接到应用图标的右键单击菜单上的快捷方式来快速访问关键应用功能。 若要在 PWA 中使用快捷方式，请在 Web 应用清单中包含 shortcuts 成员。

以下代码演示如何在 Web 应用清单中定义快捷方式。

"shortcuts": [
    {
        "name": "Play Later",
        "description": "View the list of podcasts you saved for later",
        "url": "/play-later",
        "icons": [
            {
                "src": "/icons/play-later.svg",
                "type": "image/svg+xml",
                "purpose": "any"
            }
        ]
    },
    {
        "name": "Subscriptions",
        "description": "View the list of podcasts available in your subscription",
        "url": "/subscriptions?sort=desc"
    }
]

若要了解详细信息，请参阅 定义应用快捷方式。

将应用标识为共享目标

若要使用户能够快速与本机应用程序共享链接和文件，请使用 share_target Web 应用清单中的 对象。 页面 action 类似于窗体。 在 对象中share_targetaction，定义希望传递到action页面的页面和参数。

"share_target": {
    "action": "/share.html",
    "params": {
        "title": "name",
        "text": "description",
        "url": "link"
    }
}

上述 share_target 对象建立 /share.html 为 action 共享的页面。 此示例还定义了将传递给该 action 页的三个参数： title、 text和 url。

若要详细了解如何使用共享目标功能，请参阅 与其他应用共享内容。

将应用与文件关联

将 PWA 注册为某些文件类型的文件处理程序时，操作系统可以在用户打开这些文件时自动启动应用，类似于 Microsoft Word 处理 .docx 文件的方式。 处理文件的 PWA 对用户感觉更原生，并且更好地集成到操作系统中。

若要处理文件，请列出要与应用关联的文件 mime 类型和扩展，并定义应用应用于启动的 URL：

{
    "file_handlers": [
        {
            "action": "/openFile",
            "accept": {
                "text/*": [
                    ".txt"
                ]
            }
        }
    ]
}

然后使用 方法处理文件 window.launchQueue() ：

if ('launchQueue' in window) {
    launchQueue.setConsumer(launchParams => {
        // Do something with launchParams.files ...
    });
}

若要了解详细信息，请参阅 在渐进式 Web 应用中处理文件。