# 三星 Internet 浏览器上的 PWA

> 三星 Internet 如何安装 PWA——手动"添加到主屏幕"菜单，以及由 standalone 或 fullscreen 清单触发的 ambient badging 加号图标。

**一句话：** 根据三星 Internet 官方开发者文档，该浏览器支持通过手动菜单项"Add
shortcut on Home screen"（添加快捷方式到主屏幕）安装 PWA，同时在检测到清单
`display` 为 `standalone` 或 `fullscreen` 的可安装 PWA 时，会在地址栏单独显示一个
"+"（ambient badging）图标。

## 支持情况

三星 Internet 的开发者文档描述了两种相关但彼此独立的安装信号，而非一种：

- **手动添加。** 用户可以打开菜单选择"Add shortcut on Home screen"；如果清单声明
  了图标，"所选图标会连同所选简称一起出现在主屏幕上"。
- **Ambient badging。** 三星的文档指出，三星 Internet"会在地址栏动态显示一个加号
  图标"来提示检测到 PWA，且这个"+"图标"要求 Web 应用以无地址栏的独立应用形式展
  示"——也就是清单的 `display` 字段被设为 `standalone` 或 `fullscreen`。Web App
  Manifest 支持本身"从三星 Internet v4 开始加入"，而 ambient badging"是在三星
  Internet 5.2 中引入的"。
- **Samsung DeX。** 文档还指出，"在运行于 Samsung DeX 的三星 Internet 中，Web 应
  用同样可以被添加到桌面"。

## 如何使用

```json
{
  "name": "My App",
  "short_name": "App",
  "display": "standalone",
  "icons": [{ "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }]
}
```

## 如何在运行时检测

三星的文档并未描述任何用于查询 ambient badging 图标当前是否显示、或以编程方式触
发手动"Add shortcut"菜单项的 JavaScript API、事件或属性。另外，根据 MDN，CSS
`display-mode` 媒体特性"可用于测试一个 Web 应用是在普通浏览器标签页中显示，还是
以独立应用或全屏模式等其他方式显示"。MDN 同时指出，`fullscreen` 这个值在页面"通
过 Fullscreen API，或使用 Web App Manifest 的 `display` 字段的 `fullscreen` 值
被切换到全屏模式"时都会匹配——也就是说，一个普通网页仅靠自己调用 Fullscreen API
也能匹配 `(display-mode: fullscreen)`，因此单凭这个值并不能可靠地作为安装信号。
出于这个原因，下面的检测只把 `standalone` 当作安装指示：

```js
function isRunningInstalled() {
  if (!('matchMedia' in window)) {
    // 回退：此处无法查询 display-mode，视为未安装。
    return false;
  }
  // 这里只使用 `standalone`：`fullscreen` 同样会匹配一个仅通过 Fullscreen API
  // 进入全屏的普通网页，如果也检测它，会把未安装的页面误判为已安装。
  return window.matchMedia('(display-mode: standalone)').matches;
}

if (!isRunningInstalled()) {
  // 展示指向浏览器自身菜单的页内文案——因为并没有文档记载的方式可以直接检测或
  // 触发三星 Internet 的安装界面。
  document.getElementById('install-hint').hidden = false;
}
```

## 实用清单

- 将清单 `display` 设为 `standalone` 或 `fullscreen`——根据三星的文档，ambient
  badging 的加号图标依赖于这个值。
- 为手动"Add shortcut on Home screen"路径提供清单 `icons`——根据文档，出现在主屏
  幕上的正是这个图标（连同所选简称）。
- 已注册的 Service Worker 本身并不意味着页面已被缓存以供离线使用。三星的文档把
  Service Worker 描述为"运行在浏览器中、类似网络代理"的东西，"可以从缓存中返回响
  应"——离线缓存只有在你的 fetch 处理逻辑真正实现了它时才会发生。
- 使用 HTTPS 提供服务——根据三星的文档，"Service Worker 仅限于安全上下文"。
- 不要把 ambient badging 图标和手动的主屏幕菜单项当作同一个信号——三星的文档将
  它们描述为两条彼此独立的安装路径。

## 相关参考

- [Chrome 与 Android 上的 PWA（WebAPK、TWA）](/zh/reference/platforms/chrome-android/) ——
  另一个基于 Chromium、拥有自身清单驱动界面的安装流程。
- [Service Worker 缓存策略](/zh/reference/service-worker/caching-strategies/) ——
  Service Worker 只有在你于 fetch 处理逻辑中实现之后，才会提供的缓存行为。