說明
使用 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 也提供目錄同步處理功能
![兩個視窗,每個視窗各包含一個分頁](https://developer.chrome.com/static/docs/extensions/reference/api/windows/images/windows.png?authuser=1&hl=zh-tw)
類型
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
屬性;例如透過sessions
API 查詢關閉的期間。 -
id
編號 選填
視窗的 ID。單一瀏覽器工作階段內的視窗 ID 不得重複。在某些情況下,時段無法指派
ID
屬性;例如使用sessions
API 查詢回溯期時,可能會產生工作階段 ID。 -
無痕模式
布林值
視窗是否使用無痕模式。
-
左側
編號 選填
視窗與畫面左側邊緣的偏移值 (以像素為單位)。在某些情況下,時段無法指派
left
屬性;例如透過sessions
API 查詢關閉的期間。 -
sessionId
string optional
用來識別特定視窗的工作階段 ID (從
sessions
API 取得)。 -
州
WindowState 選用
此瀏覽器視窗的狀態。
-
分頁
Tab 鍵[] 選用
代表視窗中目前分頁的
tabs.Tab
物件陣列。 -
頂端
編號 選填
視窗與螢幕頂端邊緣的偏移程度 (以像素為單位)。在某些情況下,時段無法指派
top
屬性;例如透過sessions
API 查詢關閉的期間。 -
類型
WindowType 選用
這是瀏覽器視窗的類型。
-
寬度
編號 選填
視窗的寬度 (包括頁框寬度,以像素為單位)。在某些情況下,時段無法指派
width
屬性;例如透過sessions
API 查詢關閉的期間。
列舉
"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']
。
-