使用 Web 应用清单将渐进式 Web 应用集成到操作系统中

项目
03/15/2023

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

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 应用中的文件。