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() 的呼叫。目前的視窗是包含發出呼叫的網頁的視窗，無論最上層的視窗為何。

如果是服務工作人員，目前視窗的值會回復為上一個有效視窗。在某些情況下，背景網頁可能沒有目前的視窗。

範例

兩個視窗，每個視窗各有一個分頁

如要試用這個 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。

  • 無痕模式

    布林值

    視窗是否為無痕模式。

  • 左

    數字 選填

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

  • sessionId

    字串 選填

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

  • 州

    WindowState 選用

    這個瀏覽器視窗的狀態。

  • 分頁

    分頁[] 選填

    代表視窗中目前分頁的 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

    object 選填

    • 全神貫注

      布林值 選填

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

    • 高度

      數字 選填

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

    • 無痕模式

      布林值 選填

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

    • 左

      數字 選填

      從螢幕左側邊緣開始，新視窗的像素位置。如未指定，新視窗會自然地從最後一個焦點視窗偏移。面板會忽略這個值。

    • setSelfAsOpener

      布林值 選填

      Chrome 64 以上版本

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

    • 州

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

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

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

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

getAll()

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

取得所有視窗。

參數

  • queryOptions

    QueryOptions 選用

    Chrome 88 以上版本
  • callback

    函式 選填

    callback 參數如下： 

    (windows: Window[]) => void

傳回

  • Promise<Window[]>

    Chrome 88 以上版本

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

getCurrent()

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

取得目前視窗。

參數

  • queryOptions

    QueryOptions 選用

    Chrome 88 以上版本
  • callback

    函式 選填

    callback 參數如下： 

    (window: Window) => void

傳回

  • Promise<Window>

    Chrome 88 以上版本

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

getLastFocused()

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

取得最近一次成為焦點的視窗，通常是「最上層」的視窗。

參數

  • queryOptions

    QueryOptions 選用

    Chrome 88 以上版本
  • callback

    函式 選填

    callback 參數如下： 

    (window: Window) => void

傳回

  • Promise<Window>

    Chrome 88 以上版本

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

remove()

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

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

參數

  • windowId

    數字

  • callback

    函式 選填

    callback 參數如下： 

    () => void

傳回

  • Promise<void>

    Chrome 88 以上版本

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

update()

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

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

參數

  • windowId

    數字

  • updateInfo

    物件

    • drawAttention

      布林值 選填

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

    • 全神貫注

      布林值 選填

      如果 true，則會將視窗帶到最前面；無法與「最小化」狀態合併。如果 false，則會將 z 順序中的下一個視窗帶到前景；無法與「fullscreen」或「maximized」狀態合併。

    • 高度

      數字 選填

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

    • 左

      數字 選填

      以像素為單位，從畫面左側邊緣偏移，將視窗移至該處。面板會忽略這個值。

    • 州

      WindowState 選用

      視窗的新狀態。「minimized」、「maximized」和「fullscreen」狀態不得與「left」、「top」、「width」或「height」合併使用。

    • 頂端

      數字 選填

      以像素為單位的偏移量，表示視窗要從螢幕頂端邊緣移動多少距離。面板會忽略這個值。

    • 寬度

      數字 選填

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

  • callback

    函式 選填

    callback 參數如下： 

    (window: Window) => void

傳回

  • Promise<Window>

    Chrome 88 以上版本

    只有 Manifest V3 以上版本支援 Promise，其他平台則需使用回呼。

事件

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

    • 窗戶

      視窗

      所建立視窗的詳細資料。

  • 篩選器

    object 選填

    • 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。

  • 篩選器

    object 選填

    • windowTypes

      WindowType[]

      要移除的視窗類型必須符合的條件。根據預設，這會滿足 ['normal', 'popup']。

onRemoved

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

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

參數

  • callback

    函式

    Chrome 46 以上版本

    callback 參數如下： 

    (windowId: number) => void

    • windowId

      數字

      已移除視窗的 ID。

  • 篩選器

    object 選填

    • windowTypes

      WindowType[]

      要移除的視窗類型必須符合的條件。根據預設，這會滿足 ['normal', 'popup']。