Progressive Web App Manifest: 配置档属性深入介绍 (5)

Web App 的 manifest 是一个 JSON 形式的配置档，浏览器透过配置档就会知道 Progressive Web App 该怎麽去安装在用户的电脑或手机装置上，所以最基本的 manifest 会包含 App 的名称、Icon、App 开启时要显示的 URL。

建立 manifest file

命名上其实没有特别规定，但通常会是 manifest.json 并且放置在专案的根目录，规格上的副档名是有特别建议 .webmanifest 所以其实也可以，但 JSON 格式较容易广泛的辨识和理解。

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "540x720"
    }
  ]
}

manifest 属性 (Key manifest properties)

• name/short_name: 安装後的 App 名称 short_name 会用在显示上有限制的地方
• icons: 主画面或是任务切换时显示
• start_url: App 开启预设页，须注意为相对路径跟 manifest 位置相关，有填 Chrome 才会跳提示
• background_color: 在加入主画面後，启动时 splash screen 的背景主视觉，在还没安装前的网址列也会改变颜色
• display: 定义 App 开启後的显示方式目前有三种，各有细微差异 fullscreen、standalone、minimal-ui

short_name、name

两个必须择一填，若两者都填

• short_name: 用在主画面、启动画面或是其他显示受限的地方
• name: 安装时使用

background_color

启动画面的 splash screen 背景色

theme_color

网址列的颜色，注意要和 meta 中的颜色相同。

<meta name="theme-color" content="#3c553c" />

icons

当用户安装 PWA 的时候，我们可以预先提供一套不同解析度的 icon 给浏览器用在不同的位置，icons 是包含图片物件的阵列，对 Chrome 来说, PWA 至少要提供 192x192 和 512x512 两种解析度的 icon，剩下的情境 Chrome 会自动针对装置做优化。

每一个图片物件须包含以下属性:

• src
• sizes
• type
• purpose: 选填，可填入 "any maskable"，在 Android 手机中可以发现 icon 会依照手机主题样式变成圆形或其他形状，所以 icon 在设计上可以特别注意。
  • https://web.dev/maskable-icon/

Photo Credit: https://web.dev/
透过开发者工具勾选 Show only the minimum safe area for maskable icons 来看现在的 Icon 是否 maskable

description

说明这个 App 的一些介绍。

screenshots

screenshots 是包含图片物件的阵列, 就是 App 的使用说明截图，description 和 screenshots 主要都是安装相关讯息，所以目前只会用在 Android 上的 Chrome。

要满足以下条件:

• 长宽介於 320px - 3840px
• 最大解析度不能超过最小的 2.3 倍
• 截图要同样的长宽比
• 仅支援 JPEG、PNG

display

透过这个属性我们可以选择 App 开启後的介面，举例来说我们可隐藏网址列使用全萤幕去操作，但并非所有的浏览器都完整支援，支援度会以下面的顺序向下支援:

"fullscreen" → "standalone" → "minimal-ui" → "browser"

若想要跳过上面顺序的某个阶段，就需要透过 display_override 来盖掉:

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone"
}

1. "window-control-overlay" (盖掉)
2. "minimal-ui"
3. "standalone" (回到原来 display 设定的 standalone)
4. "minimal-ui"
5. "browser"

start_url

start_url 算是最重要的一个必填属性，要告诉浏览器当 App 启动时要显示什麽画面，避免 App 因为用户是从其他页面加入至主画面导致启动页面是从其他页面开始。start_url 就是用户打开的第一个页面，可以看成产品专用的到达页面。所以也值得从用户想要开启 App 的原因去规划 start_url 位置。

shortcuts

shortcuts 相对於 start_url 则可以看成其他常用的子功能，以订票系统来说就可以分为余票查询、时刻查询等子功能，透过捷径的配置就能够让用户透过子选单直接开启 App 并且使用功能，目前的支援度如下

• Android (Chrome 84)
• Windows (Chrome 85 and Edge 85)
• Chrome OS (Chrome 92)

1. 长按 App 开启选单

Photo Credit: https://web.dev/

2. 桌面版 App 按右键开启选单

Photo Credit: https://web.dev/

如果对捷径功能有兴趣，可以试玩看看底下这个 App:

https://app-shortcuts.glitch.me/

验证 manifest

透过开发者工具中的 Application Tab 可以轻松的察看是否我们的 manifest 有被正确的使用。

Photo Credit: https://web.dev/