# edge_side_panel 清单成员

> Edge 专有的 edge_side_panel 成员及其 preferred_width 属性把 PWA 固定到 Microsoft Edge 侧边栏；Microsoft 已于 2026 年 7 月将其标记为弃用。

`edge_side_panel` 是 Microsoft Edge 的清单成员，让已安装的 PWA 可以被固定到 Edge 侧边栏，也就是
浏览器窗口右侧那条竖向的应用栏。它唯一的属性 `preferred_width` 要求侧边栏以指定宽度而不是
376 像素的最小宽度打开应用。

该成员只有桌面端的 Microsoft Edge（Windows、macOS、Linux）实现。Chrome 155、Firefox 157 与
Safari 27 把它当作未知成员丢弃，不报错。Microsoft 自己的文档带有一条 2026 年 7 月的更新，说明
该特性正在被弃用、不再受支持；请把本条目当作一项正在退场的特性的记录，而不是新开发的目标。

## 成员

- **类型**：对象。空对象 `{}` 就是完整的选择加入；唯一被识别的属性是 `preferred_width`，
  单位为 CSS 像素的数字。
- **默认值**：缺省。没有该成员时 Edge 不提供把应用固定到侧边栏的入口；写 `{}` 时侧边栏以
  376 px 的默认最小宽度打开应用，用户可以拉宽。
- **示例值**：`{ "preferred_width": 480 }`。

Microsoft 的文档要求清单先具备 `name`、`short_name`、`description` 与 `icons`，该成员才会生效，
因为侧边栏商店的列表就是从这几项生成的。低于 376 px 的 `preferred_width` 会被钳制到该值；用户
仍可把面板拉大，或缩小到最小宽度为止。

固定在侧边栏里的应用默认收到桌面端的 User-Agent Client Hints，即使存在移动端变体也是如此。
侧边栏通过一个 UA-CH 品牌向页面表明身份，这是官方支持的检测途径；Microsoft 把匹配 User-Agent
字符串列为备选，并建议不要使用。

:::observed
Edge 154（Windows 11，英文界面）从侧边栏启动应用时，`navigator.userAgentData.brands` 中除
Chromium 与 Microsoft Edge 品牌外还有 `{ brand: "Edge Side Panel", version: "1" }`；同一应用在
普通窗口里打开时没有这一项。Chrome 155（macOS 26）的 DevTools > Application > Manifest 对
`edge_side_panel` 既不显示任何分节，也没有 **Errors and warnings** 条目：该成员被静默丢弃。
:::

## 示例

清单里的选择加入和运行时检查是两件事：前者只改一行，后者决定应用渲染哪种布局。

### 让音乐播放器以 480 px 进入侧边栏

一个双栏布局的播放器放不进 376 px，于是请求 480。用户固定该应用时，Edge 以这个宽度打开侧边栏；
清单的其余部分就是一份普通的可安装 PWA。

```json
{
  "name": "PWAmp music player",
  "short_name": "PWAmp",
  "description": "A skinnable music player app to play your favorite mp3 files",
  "start_url": "/",
  "display": "standalone",
  "icons": [{ "src": "/favicon-256.png", "sizes": "256x256", "type": "image/png" }],
  "edge_side_panel": { "preferred_width": 480 }
}
```

去掉 `preferred_width` 仍然保留固定入口，并把宽度交给用户决定；对于在 376 px 下已经能正常工作的
布局，这是更好的选择。

### 检测侧边栏环境并回退

Edge 通过 User-Agent Client Hints 品牌暴露侧边栏。没有 `navigator.userAgentData` 的浏览器
（Firefox 157、Safari 27）走回退分支，被当作普通窗口处理。

```js
function isInEdgeSidebar() {
  if (!('userAgentData' in navigator)) return false; // 没有 UA-CH：不是 Edge 侧边栏
  return navigator.userAgentData.brands.some((b) => b.brand === 'Edge Side Panel');
}

document.documentElement.dataset.layout = isInEdgeSidebar() ? 'sidebar' : 'window';
```

在 CSS 里按这个 data 属性切换，而不是分叉应用逻辑：侧边栏里的应用就是同一个应用在更窄、更高的
视口里运行，一条 `max-width` 媒体查询能覆盖该属性要做的大部分事情。

### 在移动优先的站点上给侧边栏提供桌面布局

因为侧边栏发送的是桌面端客户端提示，按 `Sec-CH-UA-Mobile` 请求头选择移动端包的站点会把桌面版
发给一个 376 px 的面板。在服务端先检查品牌再做选择。

```js
// Express 中间件：在 Edge 侧边栏内优先使用紧凑布局。
app.use((req, res, next) => {
  const brands = String(req.get('Sec-CH-UA') ?? '');
  res.locals.compact = brands.includes('"Edge Side Panel"') || req.get('Sec-CH-UA-Mobile') === '?1';
  next();
});
```

`Sec-CH-UA` 是每个请求都会发送的低熵提示，这项检查不需要 `Accept-CH` 选择加入。

## 另请参阅

- [Microsoft Edge 上的 PWA（侧边栏、商店）](/zh/reference/platforms/edge/)
- [icons 清单成员](/zh/reference/manifest/icons/)
- [description 清单成员](/zh/reference/manifest/description/)
- [Build PWAs for the sidebar in Microsoft Edge](https://learn.microsoft.com/en-us/microsoft-edge/progressive-web-apps/how-to/sidebar)（learn.microsoft.com）
- [Microsoft Edge Explainers: Side Panel](https://github.com/MicrosoftEdge/MSEdgeExplainers/blob/main/SidePanel/explainer.md)（github.com）