> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 弹出窗口尺寸

> 浏览器如何决定 action 弹出窗口的尺寸、真实的最小与最大尺寸，以及让弹出窗口在 Chrome、Firefox 与 Safari 上都保持稳定的 CSS 写法。

action 弹出窗口并没有一个可以用 JavaScript 调整尺寸的窗口。浏览器会测量你渲染出来的 HTML，然后在硬性上限之内围绕它绘制弹出窗口。所以给弹出窗口定尺寸，本质上就是用 CSS 给它的内容定尺寸。

## 浏览器实际应用的规则

* 弹出窗口会撑大到刚好容纳你文档渲染后的尺寸。
* Chromium 系浏览器把弹出窗口限制在最大 **800 x 600 px**、最小 **25 x 25 px**。
* Firefox 采用同样的 **800 x 600 px** 上限。
* 超出最大值的内容会出现滚动条，弹出窗口本身绝不会超过这个上限继续变大。
* 没有任何 API 可以直接设置弹出窗口的尺寸。`chrome.windows` 这组 API 调整的是浏览器窗口，而不是 action 弹出窗口。

## 基准写法

给文档一个明确的宽度，让高度跟随内容：

```css theme={null}
/* popup.css */
html,
body {
  margin: 0;
}

body {
  width: 360px;
  min-height: 120px;
  max-height: 600px;
  overflow-x: hidden;
  box-sizing: border-box;
}
```

在 320 到 400 px 之间取一个固定宽度，在所有桌面浏览器上观感都不错。高度才是你想保持弹性的那一维：让它跟着内容走，把 600 px 的上限当作天花板。

## 会导致弹出窗口错位或跳动的坑

### 视口单位

不要在弹出窗口里用 `vh` 和 `vw`。视口就是弹出窗口本身，而弹出窗口的尺寸又来自你的内容，于是视口单位造成了循环测量。实际表现是 `100vh` 会塌缩成意料之外的数值，在 Firefox 上尤其明显。请改用固定的 `px` 值，或者由内容驱动的尺寸。

### 百分比高度

在 `body` 上写 `height: 100%` 有同样的循环问题：在你的内容给出高度之前，父元素根本没有固定高度。更好的做法是用带像素值的 `min-height`。

### 迟到加载的内容会改变弹出窗口尺寸

弹出窗口按首次绘制时的尺寸打开，随后在字体、图片或异步数据到达时肉眼可见地跳一下。要让它保持稳定：

* 给图片设置明确的 `width` 和 `height` 属性。
* 用 `min-height` 骨架为异步区块预留空间。
* 尽可能让首次渲染保持同步，把数据填充进已经定好尺寸的容器里。

### 滚动条闪烁

如果内容在加载过程中短暂溢出，滚动条会闪现并让布局发生位移。在 `body` 上写 `overflow-x: hidden` 可以消除水平方向的闪烁，而 `scrollbar-gutter: stable` 能在真正出现纵向滚动条时不让内容被挤动。

### 缩放会改变实际生效的上限

浏览器缩放会缩放弹出窗口的 CSS 像素，因此一个 360 px 的弹出窗口在 150% 缩放下会占据更多屏幕空间，也会更早撞上 800 x 600 的上限。如果用户反馈弹出窗口被裁切，缩放是常见原因，把布局控制在大约 750 x 550 CSS px 以内可以留出余量。

## Firefox 注意事项

* Firefox 需要在 `body`（或者一个固定宽度的根元素）上给出宽度，否则不受约束的弹出窗口可能渲染成塌缩状态或者一个意料之外的宽度。
* 由于 Manifest V3 移除了 `browser_style`，弹出窗口的全部样式都由你自己负责。请自带一套基础样式。

## Safari 注意事项

Safari 把弹出窗口渲染成一个 popover，采用同样的内容驱动模型。请继续使用明确宽度的写法，并用 `extension dev --browser=safari` 测试。该命令仅在 macOS 上运行，需要完整的 Xcode app，而且目前还没有实时重载，所以每改一次尺寸都意味着要重新构建一次（参见 [构建 Safari 扩展](/docs/browsers/safari)）。Safari 对布局尚未稳定时就绘制这件事更严格，所以在它上面预先定好尺寸的容器更加重要。

## 调试弹出窗口尺寸

运行你的扩展，然后像检查任何页面一样检查弹出窗口：

```bash theme={null}
npx extension@latest dev
```

打开弹出窗口，在里面点右键并选择“检查”。DevTools 连着的时候弹出窗口会保持打开，你可以一边切换 CSS 一边实时看它改变尺寸。Extension.js 会在保存时重新加载弹出窗口，让调尺寸这件事迭代得很快。

## 快速检查清单

* 在 `body` 上设置固定的 `width`，取值在 320 到 400 px 之间。
* `min-height` 用像素值，不要用 `vh`，也不要用百分比高度。
* 给图片和异步区块预先定好尺寸。
* 保持在 800 x 600 的上限之内，并为缩放留出余量。
* 测试 Chrome、Firefox 和 Safari 的构建，上限虽然一致，渲染却各有差异。