Chrome 現在支援標準化的 browser.* 命名空間 (適用於 Chrome 148 以上版本)。我們會逐步更新說明文件。詳情請參閱轉換指南。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

browser.windows

說明

使用 chrome.windows API 與瀏覽器視窗互動。您可以使用這個 API 在瀏覽器中建立、修改及重新排列視窗。

權限

收到要求時，windows.Window 會包含 tabs.Tab 物件陣列。如需存取 tabs.Tab 的 url、pendingUrl、title 或 favIconUrl 屬性，您必須在資訊清單中宣告 "tabs" 權限。例如：

{
  "name": "My extension",
  ...
  "permissions": ["tabs"],
  ...
}

概念和用途

目前的視窗

擴充功能系統中的許多函式都接受選用的 windowId 引數，預設為目前視窗。

「目前視窗」是指包含目前執行程式碼的視窗。請注意，這可能與最上層或焦點視窗不同。

舉例來說，假設某個擴充功能從單一 HTML 檔案建立多個分頁或視窗，且該 HTML 檔案包含對 tabs.query() 的呼叫。目前視窗是指包含發出呼叫的網頁的視窗，無論最上層視窗為何。

如果是 Service Worker，目前視窗的值會改用最後一個活動視窗。在某些情況下，背景網頁可能沒有目前的視窗。

範例

如要試用這個 API，請從 chrome-extension-samples 存放區安裝 windows API 範例。

類型

CreateType

Chrome 44 以上版本瀏覽器。*自 Chrome 148 起

指定要建立的瀏覽器視窗類型。「panel」已淘汰，目前僅適用於 ChromeOS 上已加入許可清單的擴充功能。

列舉

"normal"
將視窗指定為標準視窗。

"popup"
將視窗指定為彈出式視窗。

"panel"
將視窗指定為面板。

QueryOptions

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

屬性

填入

布林值選填

如果為 true，windows.Window 物件會包含 tabs 屬性，其中包含 tabs.Tab 物件清單。只有在擴充功能的資訊清單檔案包含 "tabs" 權限時，Tab 物件才會包含 url、pendingUrl、title 和 favIconUrl 屬性。
windowTypes

WindowType[] 選填

如果設定，系統會根據類型篩選傳回的 windows.Window。如未設定，預設篩選器會設為 ['normal', 'popup']。

Window

屬性

alwaysOnTop

布林值

視窗是否設為一律置頂。
全神貫注

布林值

視窗目前是否為焦點視窗。
高度

數字選填

視窗高度 (含框架)，以像素為單位。在某些情況下，視窗可能不會獲派 height 屬性，例如透過 sessions API 查詢已關閉的視窗時。
id

數字選填

視窗的 ID。視窗 ID 在瀏覽器工作階段中不得重複。在某些情況下，視窗可能不會指派 ID 屬性，例如使用 sessions API 查詢視窗時，此時可能會出現工作階段 ID。
incognito

布林值

視窗是否為無痕模式。
左

數字選填

視窗與螢幕左側邊緣的偏移量 (以像素為單位)。在某些情況下，視窗可能不會獲派 left 屬性，例如透過 sessions API 查詢已關閉的視窗時。
sessionId

字串選填

工作階段 ID，用於識別視窗，可透過 sessions API 取得。
state

WindowState 選填

這個瀏覽器視窗的狀態。
分頁

Tab[] 選填

tabs.Tab 物件陣列，代表視窗中的目前分頁。
頂端

數字選填

視窗與螢幕頂端的偏移量 (以像素為單位)。在某些情況下，視窗可能不會獲派 top 屬性，例如透過 sessions API 查詢已關閉的視窗時。
類型

WindowType 選填

瀏覽器視窗類型。
寬度

數字選填

視窗寬度 (含邊框)，以像素為單位。在某些情況下，視窗可能不會獲派 width 屬性，例如透過 sessions API 查詢已關閉的視窗時。

WindowState

Chrome 44 以上版本瀏覽器。*自 Chrome 148 起

這個瀏覽器視窗的狀態。在某些情況下，視窗可能不會獲派 state 屬性，例如透過 sessions API 查詢已關閉的視窗時。

列舉

"normal"
一般視窗狀態 (非最小化、最大化或全螢幕)。

"minimized"
最小化視窗狀態。

"maximized"
視窗最大化狀態。

"fullscreen"
全螢幕視窗狀態。

WindowType

Chrome 44 以上版本瀏覽器。*自 Chrome 148 起

瀏覽器視窗的類型。在某些情況下，視窗可能不會指派 type 屬性，例如透過 sessions API 查詢已關閉的視窗時。

列舉

"normal"
一般瀏覽器視窗。

「popup」
瀏覽器彈出式視窗。

"panel"
在這個 API 中已淘汰。Chrome 應用程式面板樣式的視窗。擴充功能只能查看自己的面板視窗。

"app"
在這個 API 中已淘汰。Chrome 應用程式視窗。擴充功能只能查看自己的應用程式視窗。

"devtools"
開發人員工具視窗。

屬性

WINDOW_ID_CURRENT

代表目前視窗的 windowId 值。

值

-2

WINDOW_ID_NONE

代表沒有 Chrome 瀏覽器視窗的 windowId 值。

值

-1

方法

create()

browser.windows.create(
  createData?: object,
): Promise<Window | undefined>

建立 (開啟) 新的瀏覽器視窗，並套用您提供的選用大小、位置或預設網址。

參數

createData

物件選填
- 全神貫注
  
  布林值選填
  
  如果為 true，則會開啟使用中的視窗。如果 false，則開啟閒置視窗。
- 高度
  
  數字選填
  
  新視窗的高度 (以像素為單位)，包括框架。如未指定，則預設為自然高度。
- incognito
  
  布林值選填
  
  新視窗是否應為無痕視窗。
- 左
  
  數字選填
  
  新視窗與螢幕左側邊緣的距離 (以像素為單位)。如未指定，新視窗會自然地從最後一個聚焦視窗偏移。面板會忽略這個值。
- setSelfAsOpener
  
  布林值選填
  
  Chrome 64+ 瀏覽器 (自 Chrome 148 起)
  
  如果為 true，新建立視窗的「window.opener」會設為呼叫端，且與呼叫端位於相同的相關瀏覽情境單元。
- state
  
  WindowState 選填
  
  Chrome 44 以上版本瀏覽器。*自 Chrome 148 起
  
  視窗的初始狀態。minimized、maximized 和 fullscreen 狀態無法與 left、top、width 或 height 結合。
- tabId
  
  數字選填
  
  要新增至新視窗的分頁 ID。
- 頂端
  
  數字選填
  
  新視窗與螢幕頂端邊緣的距離 (以像素為單位)。如未指定，新視窗會自然地從最後一個聚焦視窗偏移。面板會忽略這個值。
- 類型
  
  CreateType 選用
  
  指定要建立的瀏覽器視窗類型。
- 網址
  
  字串 | 字串 [] 選填
  
  要在視窗中開啟為分頁的網址或網址陣列。完整網址必須包含配置，例如「http://www.google.com」，而非「www.google.com」。非完整網址會視為擴充功能內的相對網址。預設為新分頁。
- 寬度
  
  數字選填
  
  新視窗的寬度 (以像素為單位)，包括框架。如未指定，則預設為自然寬度。

傳回

Promise<Window | undefined>

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

get()

browser.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
): Promise<Window>

取得視窗詳細資料。

參數

windowId

數字
queryOptions

QueryOptions 選用

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

傳回

Promise<Window>

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

getAll()

browser.windows.getAll(
  queryOptions?: QueryOptions,
): Promise<Window[]>

取得所有視窗。

參數

queryOptions

QueryOptions 選用

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

傳回

Promise<Window[]>

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

getCurrent()

browser.windows.getCurrent(
  queryOptions?: QueryOptions,
): Promise<Window>

取得目前視窗。

參數

queryOptions

QueryOptions 選用

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

傳回

Promise<Window>

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

getLastFocused()

browser.windows.getLastFocused(
  queryOptions?: QueryOptions,
): Promise<Window>

取得最近聚焦的視窗，通常是「最上層」的視窗。

參數

queryOptions

QueryOptions 選用

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

傳回

Promise<Window>

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

remove()

browser.windows.remove(
  windowId: number,
): Promise<void>

移除 (關閉) 視窗和其中的所有分頁。

參數

windowId

數字

傳回

承諾<void>

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

update()

browser.windows.update(
  windowId: number,
  updateInfo: object,
): Promise<Window>

更新視窗屬性。請只指定要變更的屬性，未指定的屬性不會變更。

參數

windowId

數字
updateInfo

物件
- drawAttention
  
  布林值選填
  
  如果為 true，則會以吸引使用者注意的方式顯示視窗，但不會變更焦點視窗。直到使用者將焦點切換至該視窗為止。如果視窗已取得焦點，這個選項就不會生效。設為 false 即可取消先前的 drawAttention 要求。
- 全神貫注
  
  布林值選填
  
  如果為 true，則會將視窗移至最前方；無法與「minimized」狀態合併使用。如果為 false，則會將 Z 軸順序中的下一個視窗移至最前方；無法與「fullscreen」或「maximized」狀態合併使用。
- 高度
  
  數字選填
  
  視窗調整後的高度 (以像素為單位)。面板會忽略這個值。
- 左
  
  數字選填
  
  視窗要移至的位置與螢幕左側邊緣的距離 (以像素為單位)。面板會忽略這個值。
- state
  
  WindowState 選填
  
  視窗的新狀態。「minimized」、「maximized」和「fullscreen」狀態無法與「left」、「top」、「width」或「height」合併。
- 頂端
  
  數字選填
  
  視窗與螢幕頂端的距離 (以像素為單位)。面板會忽略這個值。
- 寬度
  
  數字選填
  
  視窗調整後的寬度 (以像素為單位)。面板會忽略這個值。

傳回

Promise<Window>

Chrome 88 以上版本 Chrome 148 起為瀏覽器。*

事件

onBoundsChanged

Chrome 86 以上版本 Chrome 148 以上版本支援 browser.*

browser.windows.onBoundsChanged.addListener(
  callback: function,
)

在視窗大小調整時觸發；只有在提交新邊界時，才會調度這個事件，不會在變更進行中時調度。

參數

callback

函式

callback 參數如下：
```
(window: Window) => void
```
- 窗戶
  
  視窗

onCreated

browser.windows.onCreated.addListener(
  callback: function,
  filters?: object,
)

建立視窗時觸發。

參數

callback

函式

Chrome 46 以上版本 Chrome 148 以上版本為 browser.*

callback 參數如下：
```
(window: Window) => void
```
- 窗戶
  
  視窗
  
  所建立視窗的詳細資料。
篩選器

物件選填
- windowTypes
  
  WindowType[]
  
  建立視窗類型時必須符合的條件。預設符合 ['normal', 'popup']。

onFocusChanged

browser.windows.onFocusChanged.addListener(
  callback: function,
  filters?: object,
)

當目前聚焦的視窗變更時觸發。如果所有 Chrome 視窗都失去焦點，則傳回 chrome.windows.WINDOW_ID_NONE。注意：在某些 Linux 視窗管理員中，從一個 Chrome 視窗切換到另一個視窗之前，一律會立即傳送 WINDOW_ID_NONE。

參數

callback

函式

Chrome 46 以上版本 Chrome 148 以上版本為 browser.*

callback 參數如下：
```
(windowId: number) => void
```
- windowId
  
  數字
  
  新焦點視窗的 ID。
篩選器

物件選填
- windowTypes
  
  WindowType[]
  
  移除視窗類型時必須符合的條件。預設符合 ['normal', 'popup']。

onRemoved

browser.windows.onRemoved.addListener(
  callback: function,
  filters?: object,
)

在視窗移除 (關閉) 時觸發。

參數

callback

函式

Chrome 46 以上版本 Chrome 148 以上版本為 browser.*

callback 參數如下：
```
(windowId: number) => void
```
- windowId
  
  數字
  
  已移除視窗的 ID。
篩選器

物件選填
- windowTypes
  
  WindowType[]
  
  移除視窗類型時必須符合的條件。預設符合 ['normal', 'popup']。

browser.windows 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

說明

權限

概念和用途

目前的視窗

範例

類型

CreateType

列舉

QueryOptions

屬性

Window

屬性

WindowState

列舉

WindowType

列舉

屬性

WINDOW_ID_CURRENT

值

WINDOW_ID_NONE

值

方法

create()

參數

傳回

get()

參數

傳回

getAll()

參數

傳回

getCurrent()

參數

傳回

getLastFocused()

參數

傳回

remove()

參數

傳回

update()

參數

傳回

事件

onBoundsChanged

參數

onCreated

參數

onFocusChanged

參數

onRemoved

參數

browser.windows