> ## 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 應用程式，而且目前還沒有即時重新載入，所以每調整一次尺寸就得重新建置一次（請參見 [建置 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 的建置，上限雖然共通，算繪結果卻各有差異。