# name 与 short_name 清单成员

> name 是已安装 Web 应用的完整标签，short_name 是主屏幕等狭窄位置使用的标签；Chromium 要求至少具备其中之一才会提供安装。

`name` 是 Web 应用完整的、面向人的标签；`short_name` 用在放不下完整标签的地方：主屏幕网格、
启动器、任务栏、应用切换器。规范把两者都定为可选；Chromium 的可安装性检查则不然，它要求至少
具备其中之一才会提供安装。

Chrome 39、Edge 79、Samsung Internet 4.0、Android 上的 Firefox 79、iOS 上的 Safari 11.3 与
macOS 上的 Safari 17 读取这两个成员（BCD `html.manifest.name`、`html.manifest.short_name`）。
桌面端 Firefox 157 不从清单安装 Web 应用，所以两者都不读。各语言版本放在 `name_localized`
与 `short_name_localized` 中，Chrome 与 Edge 148 会应用它们。

## 成员

- **类型**：两者都是字符串。纯文本；HTML、emoji 与控制字符会被操作系统原样渲染或丢弃，不会被
  解释。
- **默认值**：`name` 没有默认值。`short_name` 缺省时，浏览器在原本使用 `short_name` 的地方
  使用 `name`，并按界面需要截断。
- **示例值**：`"name": "Acme Invoice Tracker"`、`"short_name": "Invoices"`。

在 Chromium 中各标签出现的位置：`name` 出现在安装对话框、启动画面、Windows 开始菜单与 macOS
的"应用程序"文件夹，以及窗口标题；`short_name` 出现在 Android 主屏幕图标下方、ChromeOS 的
任务栏，以及固定到 Windows 任务栏时。Lighthouse 的 `manifest-short-name-length` 审计会判定
超过 12 个字符的 `short_name` 不合格，因为 Android 启动器会把它截断，这就是实际的长度上限。

Chromium 还把标签用作安全手段：对处于 `standalone` 或 `fullscreen` 模式的应用，它在窗口切换
界面中把 `short_name`（缺省时为 `name`）加到文档 `<title>` 之前，使页面无法把自己伪装成操作
系统或另一个应用（web.dev）。在 iOS 上，存在 `<meta name="apple-mobile-web-app-title">` 时，
它优先于 `short_name` 成为主屏幕标签。

非字符串的值会以 `property 'name' ignored, type string expected.` 被丢弃（`short_name` 同理），
这可能悄悄抹掉可安装性所依赖的那一个字段。

:::observed
Chrome 155（macOS 26，英文界面）的 DevTools > Application > Manifest：清单同时删去 `name`
与 `short_name` 时，**Installability** 一节显示
`Manifest does not contain a 'name' or 'short_name' field`，地址栏安装图标消失。只加回
`"short_name": "Invoices"` 就能清除该提示；此时 **Identity** 一节的 **Name** 为空，
**Short name** 显示 `Invoices`。
:::

## 示例

三个示例分别覆盖最小组合、为 12 字符启动器预算挑选的标签，以及页面能做的唯一一项运行时检查。

### 完整名称与放得进启动器的短标签

品牌名放在 `name`；`short_name` 是用户在 48 px 图标下方能认出的那个词。两者都别写"App"或
"PWA"，操作系统已经知道它是应用。

```json
{
  "name": "Acme Invoice Tracker",
  "short_name": "Invoices",
  "start_url": "/",
  "display": "standalone",
  "icons": [{ "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }]
}
```

`Invoices` 有 8 个字符，在 Android 启动器预算之内；`Acme Invoice Tracker` 则显示在安装对话框、
Windows 开始菜单与窗口标题中。

### 在 standalone 模式下保持窗口标题可读

由于 Chromium 会在 standalone 模式下把 `short_name` 加到窗口标题前面，重复应用名的页面标题会
显示成 `Invoices - Invoices - March`。把文档标题只设为内容本身，让浏览器自己加应用标签。

```js
function setWindowTitle(section) {
  const standalone = matchMedia('(display-mode: standalone)').matches;
  // 在 standalone 窗口里，Chromium 会自行加上清单的 short_name。
  document.title = standalone ? section : `${section} · Acme Invoice Tracker`;
}

setWindowTitle('March');
```

在浏览器标签页里，该分支把品牌加回来，书签与标签栏仍然能识别站点。

### 在部署测试里检查上线的标签

运行时没有任何东西能报告操作系统画出的标签，但测试可以断言已部署的清单带有 `name`、
`short_name` 在启动器预算之内、两者都不含标记。回退分支返回问题而不是抛出，这样测试输出会
点名具体字段。

```js
export async function checkLabels(manifestUrl = '/manifest.webmanifest') {
  const m = await fetch(manifestUrl).then((r) => r.json());
  const problems = [];
  if (typeof m.name !== 'string' || !m.name.trim()) problems.push('name missing');
  if (typeof m.short_name === 'string' && m.short_name.length > 12) problems.push('short_name over 12 chars');
  for (const key of ['name', 'short_name']) {
    if (typeof m[key] === 'string' && /<[a-z]/i.test(m[key])) problems.push(`${key} contains markup`);
  }
  return problems;
}
```

每次部署后对生产源跑一遍，与可安装性标准条目里描述的图标和启动 URL 检查放在一起。

## 另请参阅

- [lang、dir 与 *_localized 清单成员](/zh/reference/manifest/localization/)
- [icons 清单成员](/zh/reference/manifest/icons/)
- [可安装性标准：什么让 PWA 可安装](/zh/reference/installation/installability-criteria/)
- [iOS 添加到主屏幕：iOS 上的 PWA 安装](/zh/reference/installation/ios-add-to-home-screen/)
- [Web Application Manifest: name member](https://www.w3.org/TR/appmanifest/#name-member)（w3.org）
- [Add a web app manifest](https://web.dev/articles/add-manifest)（web.dev）