說明
使用 chrome.windows API 與瀏覽器視窗互動。您可以使用這個 API 在瀏覽器中建立、修改及重新排列視窗。
資訊清單
系統要求時，windows.Window 會包含 tabs.Tab 物件的陣列。您必須
如要存取 url，請在資訊清單中宣告 "tabs" 權限。
tabs.Tab 的 pendingUrl、title 或 favIconUrl 屬性。例如：
{
"name": "My extension",
...
"permissions": ["tabs"],
...
}
目前的視窗
擴充功能系統中的許多函式都會使用選用 windowId 引數，該引數預設為
。
「目前的視窗」是包含目前正在執行程式碼的視窗。是 請注意，此視窗可能與最上層或聚焦的視窗不同。
舉例來說，假設某個擴充功能從一個 HTML 檔案建立幾個分頁或視窗，而且
HTML 檔案包含對 tabs.query() 的呼叫。目前的視窗是包含
呼叫網頁。
如果採用服務 Worker，目前視窗的值會改回上次使用的時段 視窗。在某些情況下，背景頁面可能沒有目前的視窗。
範例
如要試用這個 API，請安裝 chrome-extension-samples 提供的 Windows API 範例 Cloud Storage 也提供目錄同步處理功能
類型
CreateType
指定要建立的瀏覽器視窗類型。面板已淘汰，僅適用於 ChromeOS 上已加入許可清單的擴充功能。
列舉
"normal"
將視窗指定為標準視窗。
"popup"
將視窗指定為彈出式視窗。
"panel"
將視窗指定為面板。
QueryOptions
屬性
-
填入
布林值 選填
如果為 true，
windows.Window物件會包含tabs屬性，其中包含tabs.Tab物件清單。如果擴充功能的資訊清單檔案包含"tabs"權限，則Tab物件只會包含url、pendingUrl、title和favIconUrl屬性。 -
windowTypes
WindowType[] 選用
設定後，系統就會根據類型篩選傳回的
windows.Window。如未設定，預設篩選器會設為「['normal', 'popup']」。
Window
屬性
-
alwaysOnTop
布林值
是否將視窗設為一律顯示在頂端。
-
全神貫注
布林值
該視窗目前是否為聚焦的視窗。
-
高度
編號 選填
視窗的高度 (包括頁框高度)，以像素為單位。在某些情況下，時段無法指派
height屬性；例如透過sessionsAPI 查詢關閉的期間。 -
id
編號 選填
視窗的 ID。單一瀏覽器工作階段內的視窗 ID 不得重複。在某些情況下，時段無法指派
ID屬性；例如使用sessionsAPI 查詢回溯期時，可能會產生工作階段 ID。 -
無痕模式
布林值
視窗是否使用無痕模式。
-
左側
編號 選填
視窗與畫面左側邊緣的偏移值 (以像素為單位)。在某些情況下，時段無法指派
left屬性；例如透過sessionsAPI 查詢關閉的期間。 -
sessionId
string optional
用來識別特定視窗的工作階段 ID (從
sessionsAPI 取得)。 -
州
WindowState 選用
此瀏覽器視窗的狀態。
-
分頁
Tab 鍵[] 選用
代表視窗中目前分頁的
tabs.Tab物件陣列。 -
頂端
編號 選填
視窗與螢幕頂端邊緣的偏移程度 (以像素為單位)。在某些情況下，時段無法指派
top屬性；例如透過sessionsAPI 查詢關閉的期間。 -
類型
WindowType 選用
這是瀏覽器視窗的類型。
-
寬度
編號 選填
視窗的寬度 (包括頁框寬度，以像素為單位)。在某些情況下，時段無法指派
width屬性；例如透過sessionsAPI 查詢關閉的期間。
列舉
"normal"
正常視窗狀態 (未最小化、最大化或全螢幕)。
"minimized"
將視窗狀態最小化。
"maximized
最大視窗狀態。
"fullscreen"
全螢幕視窗狀態。
"locked-fullscreen"
鎖定全螢幕視窗狀態。這個全螢幕狀態無法讓使用者採取動作，而只適用於 Chrome OS 中已加入許可清單的擴充功能。
列舉
"normal"
一般瀏覽器視窗。
"popup"
瀏覽器彈出式視窗。
"panel"
此 API 已淘汰。Chrome 應用程式面板樣式視窗。擴充功能只能看到自己的面板視窗。
「應用程式」
此 API 已淘汰。Chrome 應用程式視窗。擴充功能只能看到自己的應用程式視窗。
"devtools"
開發人員工具視窗。
屬性
方法
create()
chrome.windows.create(
createData?: object,
callback?: function,
)
建立 (開啟) 新的瀏覽器視窗，並可選擇是否調整大小、位置或預設網址。
參數
-
createData
物件 optional
-
全神貫注
布林值 選填
如果為
true，請開啟使用中的視窗。如果為false，請開啟閒置視窗。 -
高度
編號 選填
新視窗 (包括頁框) 的高度 (以像素為單位)。如未指定，則會預設為自然高度。
-
無痕模式
布林值 選填
新視窗是否應為無痕式視窗。
-
左側
編號 選填
從畫面左側邊緣放置新視窗的像素數量。如未指定，新視窗將會與上次聚焦的視窗自然偏移。系統會忽略面板的這個值。
-
setSelfAsOpener
布林值 選填
Chrome 64 以上版本如果設為
true，則新建立視窗的「window.opener」已設為呼叫端，且與呼叫端的相關瀏覽情境單位相同。 -
州
WindowState 選用
Chrome 44 以上版本視窗的初始狀態。
minimized、maximized和fullscreen狀態無法與left、top、width或height合併。 -
tabId
編號 選填
要新增至新視窗的分頁 ID。
-
頂端
編號 選填
從螢幕頂端開始顯示新視窗的像素數量。如未指定，新視窗將會與上次聚焦的視窗自然偏移。系統會忽略面板的這個值。
-
類型
CreateType 選用
指定要建立的瀏覽器視窗類型。
-
網址
string |string[] 選填
要在視窗中以分頁開啟的網址或網址陣列。完全符合規定的網址必須包含架構，例如「http://www.google.com」，而不是「www.google.com」。系統會將不完整的網址視為額外資訊中的相對網址。預設為新分頁。
-
寬度
編號 選填
以像素為單位的寬度，包含頁框在內。如未指定，則會預設為自然寬度。
-
-
回呼
函式 選用
callback參數如下所示：(window?: Window) => void
-
窗戶
Window 選用
包含所建立視窗的詳細資料。
-
傳回
-
Promise<Window |未定義>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
get()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
)
取得視窗的詳細資料。
參數
-
windowId
數字
-
queryOptions
QueryOptions 選用
Chrome 88 以上版本 -
回呼
函式 選用
callback參數如下所示：(window: Window) => void
-
窗戶
-
傳回
-
Promise<Window>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
參數
-
queryOptions
QueryOptions 選用
Chrome 88 以上版本 -
回呼
函式 選用
callback參數如下所示：(windows: Window[]) => void
-
窗戶
窗戶 []
-
傳回
-
Promise<Window[]>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
getCurrent()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
)
取得目前的視窗。
參數
-
queryOptions
QueryOptions 選用
Chrome 88 以上版本 -
回呼
函式 選用
callback參數如下所示：(window: Window) => void
-
窗戶
-
傳回
-
Promise<Window>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
getLastFocused()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
)
取得最近聚焦的視窗，通常是「最上方」的視窗。
參數
-
queryOptions
QueryOptions 選用
Chrome 88 以上版本 -
回呼
函式 選用
callback參數如下所示：(window: Window) => void
-
窗戶
-
傳回
-
Promise<Window>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
remove()
chrome.windows.remove(
windowId: number,
callback?: function,
)
移除 (關閉) 視窗及內所有分頁。
參數
-
windowId
數字
-
回呼
函式 選用
callback參數如下所示：() => void
傳回
-
承諾<void>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
update()
chrome.windows.update(
windowId: number,
updateInfo: object,
callback?: function,
)
更新視窗的屬性。僅指定要變更的屬性；未指定的屬性則維持不變。
參數
-
windowId
數字
-
updateInfo
物件
-
drawAttention
布林值 選填
如果設為
true，表示視窗顯示方式會吸引使用者註意視窗，而不變更聚焦的視窗。除非使用者將焦點移至視窗，否則效果會持續有效。如果視窗已聚焦，這個選項就不會生效。設為false即可取消先前的drawAttention要求。 -
全神貫注
布林值 選填
如果是
true，則將視窗移至最前；無法與「最小化」狀態合併。如果為false，則將 z 順序的下一個視窗移至最前方；無法與「全螢幕」狀態合併「最大化」 -
高度
編號 選填
將視窗大小調整為像素的高度。系統會忽略面板的這個值。
-
左側
編號 選填
從畫面左側邊緣移動視窗的偏移值 (以像素為單位)。系統會忽略面板的這個值。
-
州
WindowState 選用
視窗的新狀態。「最小化」、「最大化」和「全螢幕」州/省無法與「left」、「top」、「width」或「height」合併。
-
頂端
編號 選填
視窗上方邊緣的偏移值 (以像素為單位)。系統會忽略面板的這個值。
-
寬度
編號 選填
將視窗大小調整至像素的寬度。系統會忽略面板的這個值。
-
-
回呼
函式 選用
callback參數如下所示：(window: Window) => void
-
窗戶
-
傳回
-
Promise<Window>
Chrome 88 以上版本Promise 僅適用於 Manifest V3 及以上版本，其他平台需要使用回呼。
活動
onBoundsChanged
chrome.windows.onBoundsChanged.addListener(
callback: function,
)
視窗大小調整時觸發；只有在確認新的邊界時，才會分派此事件，處理中的變更則不會。
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
視窗建立時觸發。
參數
-
回呼
函式
Chrome 46 以上版本callback參數如下所示：(window: Window) => void
-
窗戶
所建立視窗的詳細資料。
-
-
篩選器
物件 optional
-
windowTypes
所建立視窗類型必須符合的條件。預設會滿足
['normal', 'popup']。
-
onFocusChanged
chrome.windows.onFocusChanged.addListener(
callback: function,
filters?: object,
)
目前聚焦的視窗變更時觸發。如果所有 Chrome 視窗都失去焦點，則傳回 chrome.windows.WINDOW_ID_NONE。注意：在部分 Linux 視窗管理員中，在 Chrome 視窗切換至另一個 Chrome 視窗之前，一律會立即傳送 WINDOW_ID_NONE。
參數
-
回呼
函式
Chrome 46 以上版本callback參數如下所示：(windowId: number) => void
-
windowId
數字
新聚焦視窗的 ID。
-
-
篩選器
物件 optional
-
windowTypes
需移除視窗類型的條件。預設會滿足
['normal', 'popup']。
-
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
視窗移除時觸發 (關閉)。
參數
-
回呼
函式
Chrome 46 以上版本callback參數如下所示：(windowId: number) => void
-
windowId
數字
已移除視窗的 ID。
-
-
篩選器
物件 optional
-
windowTypes
需移除視窗類型的條件。預設會滿足
['normal', 'popup']。
-