chrome.windows

refresh date: 2026-09-25 robots: noindex

說明

使用 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 以上版本

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

列舉

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

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

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

QueryOptions

Chrome 88 以上版本

屬性

• 填入

  布林值 選填

  如果為 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 以上版本

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

列舉

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

"minimized"
最小化視窗狀態。

"maximized"
視窗最大化狀態。

"fullscreen"
全螢幕視窗狀態。

WindowType

Chrome 44 以上版本

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

列舉

"normal"
一般瀏覽器視窗。

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

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

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

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

屬性

WINDOW_ID_CURRENT

代表目前視窗的 windowId 值。

值

-2

WINDOW_ID_NONE

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

值

-1

方法

create()

Promise

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

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

參數

• createData

  物件 選填

  • 全神貫注

    布林值 選填

    如果為 true，則會開啟使用中的視窗。如果 false，則開啟閒置視窗。

  • 高度

    數字 選填

    新視窗的高度 (以像素為單位)，包括框架。如未指定，則預設為自然高度。

  • incognito

    布林值 選填

    新視窗是否應為無痕視窗。

  • 左

    數字 選填

    新視窗與螢幕左側邊緣的距離 (以像素為單位)。如未指定，新視窗會自然地從最後一個聚焦視窗偏移。面板會忽略這個值。

  • setSelfAsOpener

    布林值 選填

    Chrome 64 以上版本

    如果為 true，新建立視窗的「window.opener」會設為呼叫端，且與呼叫端位於相同的相關瀏覽情境單元。

  • state

    WindowState 選填

    Chrome 44 以上版本

    視窗的初始狀態。minimized、maximized 和 fullscreen 狀態無法與 left、top、width 或 height 結合。

  • tabId

    數字 選填

    要新增至新視窗的分頁 ID。

  • 頂端

    數字 選填

    新視窗與螢幕頂端邊緣的距離 (以像素為單位)。如未指定，新視窗會自然地從最後一個聚焦視窗偏移。面板會忽略這個值。

  • 類型

    CreateType 選用

    指定要建立的瀏覽器視窗類型。

  • 網址

    字串 | 字串 [] 選填

    要在視窗中開啟為分頁的網址或網址陣列。完整網址必須包含配置，例如「http://www.google.com」，而非「www.google.com」。非完整網址會視為擴充功能內的相對網址。預設為新分頁。

  • 寬度

    數字 選填

    新視窗的寬度 (以像素為單位)，包括框架。如未指定，則預設為自然寬度。

• callback

  函式 選填

  callback 參數如下：

  (window?: Window) => void

  • 窗戶

    Window 選填

    包含所建立視窗的詳細資料。

傳回

• Promise<Window | undefined>

  Chrome 88 以上版本

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

get()

Promise

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

取得視窗詳細資料。

參數

• windowId

  數字

• queryOptions

  QueryOptions 選用

  Chrome 88 以上版本
• callback

  函式 選填

  callback 參數如下：

  (window: Window) => void

  • 窗戶

    視窗

傳回

• Promise<Window>

  Chrome 88 以上版本

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getAll()

Promise

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

取得所有視窗。

參數

• queryOptions

  QueryOptions 選用

  Chrome 88 以上版本
• callback

  函式 選填

  callback 參數如下：

  (windows: Window[]) => void

  • 窗戶

    視窗[]

傳回

• Promise<Window[]>

  Chrome 88 以上版本

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getCurrent()

Promise

chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

取得目前視窗。

參數

• queryOptions

  QueryOptions 選用

  Chrome 88 以上版本
• callback

  函式 選填

  callback 參數如下：

  (window: Window) => void

  • 窗戶

    視窗

傳回

• Promise<Window>

  Chrome 88 以上版本

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

getLastFocused()

Promise

chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

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

參數

• queryOptions

  QueryOptions 選用

  Chrome 88 以上版本
• callback

  函式 選填

  callback 參數如下：

  (window: Window) => void

  • 窗戶

    視窗

傳回

• Promise<Window>

  Chrome 88 以上版本

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

remove()

Promise

chrome.windows.remove(
  windowId: number,
  callback?: function,
): Promise<void>

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

參數

• windowId

  數字

• callback

  函式 選填

  callback 參數如下：

  () => void

傳回

• 承諾<void>

  Chrome 88 以上版本

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

update()

Promise

chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
): Promise<Window>

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

參數

• windowId

  數字

• updateInfo

  物件

  • drawAttention

    布林值 選填

    如果為 true，則會以吸引使用者注意的方式顯示視窗，但不會變更焦點視窗。直到使用者將焦點切換至該視窗為止。如果視窗已取得焦點，這個選項就不會生效。設為 false 即可取消先前的 drawAttention 要求。

  • 全神貫注

    布林值 選填

    如果為 true，則會將視窗移至最前方；無法與「minimized」狀態合併使用。如果為 false，則會將 Z 軸順序中的下一個視窗移至最前方；無法與「fullscreen」或「maximized」狀態合併使用。

  • 高度

    數字 選填

    視窗調整後的高度 (以像素為單位)。面板會忽略這個值。

  • 左

    數字 選填

    視窗要移至的位置與螢幕左側邊緣的距離 (以像素為單位)。面板會忽略這個值。

  • state

    WindowState 選填

    視窗的新狀態。「minimized」、「maximized」和「fullscreen」狀態無法與「left」、「top」、「width」或「height」合併。

  • 頂端

    數字 選填

    視窗與螢幕頂端的距離 (以像素為單位)。面板會忽略這個值。

  • 寬度

    數字 選填

    視窗調整後的寬度 (以像素為單位)。面板會忽略這個值。

• callback

  函式 選填

  callback 參數如下：

  (window: Window) => void

  • 窗戶

    視窗

傳回

• Promise<Window>

  Chrome 88 以上版本

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

事件

onBoundsChanged

Chrome 86 以上版本

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

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

參數

• callback

  函式

  callback 參數如下：

  (window: Window) => void

  • 窗戶

    視窗

onCreated

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

建立視窗時觸發。

參數

• callback

  函式

  Chrome 46 以上版本

  callback 參數如下：

  (window: Window) => void

  • 窗戶

    視窗

    所建立視窗的詳細資料。

• 篩選器

  物件 選填

  • windowTypes

    WindowType[]

    建立視窗類型時必須符合的條件。預設符合 ['normal', 'popup']。

onFocusChanged

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

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

參數

• callback

  函式

  Chrome 46 以上版本

  callback 參數如下：

  (windowId: number) => void

  • windowId

    數字

    新焦點視窗的 ID。

• 篩選器

  物件 選填

  • windowTypes

    WindowType[]

    移除視窗類型時必須符合的條件。預設符合 ['normal', 'popup']。

onRemoved

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

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

參數

• callback

  函式

  Chrome 46 以上版本

  callback 參數如下：

  (windowId: number) => void

  • windowId

    數字

    已移除視窗的 ID。

• 篩選器

  物件 選填

  • windowTypes

    WindowType[]

    移除視窗類型時必須符合的條件。預設符合 ['normal', 'popup']。