說明
使用 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 範例。
![兩個視窗,每個視窗各有一個分頁](https://developer.chrome.google.cn/static/docs/extensions/reference/api/windows/images/windows.png?authuser=3&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
boolean
是否將視窗設為一律顯示在上方。
-
全神貫注
boolean
表示視窗目前是否為焦點。
-
高度
數字 選填
視窗高度 (包括頁框),以像素為單位。在某些情況下,視窗可能無法指派
height
屬性;例如透過sessions
API 查詢已關閉的視窗時。 -
id
數字 選填
視窗的 ID。瀏覽器工作階段中的視窗 ID 是唯一的。在某些情況下,視窗可能無法指派
ID
屬性;舉例來說,使用sessions
API 查詢時段時,可能會顯示工作階段 ID。 -
無痕模式
boolean
視窗是否使用無痕模式。
-
左
數字 選填
視窗與螢幕左側邊緣的偏移值 (以像素為單位)。在某些情況下,視窗可能無法指派
left
屬性;例如透過sessions
API 查詢已關閉的視窗時。 -
sessionId
字串 選用
用於識別特定視窗的工作階段 ID,可從
sessions
API 取得。 -
state
WindowState 選用
這個瀏覽器視窗的狀態。
-
分頁
Tab[] 選用
tabs.Tab
物件陣列,代表視窗中目前的分頁。 -
上
數字 選填
視窗與螢幕頂端邊緣的偏移值 (以像素為單位)。在某些情況下,視窗可能無法指派
top
屬性;例如透過sessions
API 查詢已關閉的視窗時。 -
類型
WindowType 選用
這是指瀏覽器視窗的類型。
-
寬度
數字 選填
視窗寬度 (包含頁框),以像素為單位。在某些情況下,視窗可能無法指派
width
屬性;例如透過sessions
API 查詢已關閉的視窗時。
列舉
"normal"
正常視窗狀態 (未最小化、最大化或全螢幕)。
"最小化"
最小化視窗狀態。
「最大化」
最大化視窗狀態。
「全螢幕」
全螢幕視窗狀態。
「鎖定全螢幕」
鎖定的全螢幕視窗狀態。使用者動作無法退出這個全螢幕狀態,而且僅適用於 Chrome 作業系統的許可清單擴充功能。
列舉
"normal"
一般瀏覽器視窗。
"popup"
瀏覽器彈出式視窗。
"panel"
此 API 已淘汰,Chrome 應用程式面板樣式視窗。擴充功能只能看到自己的面板視窗。
"app"
此 API 已淘汰。Chrome 應用程式視窗。擴充功能只能看到自己的應用程式視窗。
"devtools"
開發人員工具視窗。
屬性
方法
create()
chrome.windows.create(
createData?: object,
callback?: function,
)
建立 (開啟) 新的瀏覽器視窗,其中包含大小調整選項、位置或預設網址。
參數
-
createData
物件選用
-
全神貫注
布林值 (選用)
如果為
true
,系統會開啟使用中的視窗。如果為false
,則會開啟閒置視窗。 -
高度
數字 選填
新視窗的高度 (以像素為單位,包括頁框)。如果未指定,則預設為自然高度。
-
無痕模式
布林值 (選用)
是否要為新視窗建立無痕式視窗。
-
左
數字 選填
將新視窗從螢幕左側邊緣調整至適當位置的像素數。如未指定,則新視窗會與最後一個聚焦的視窗自然偏移。如果是面板,系統會忽略這個值。
-
setSelfAsOpener
布林值 (選用)
Chrome 64 以上版本如果為
true
,則新建視窗的「window.opener」會設為呼叫端,且與呼叫端位於相同的相關瀏覽情境單元。 -
state
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
-
窗戶
視窗 選用
包含已建立視窗的詳細資料。
-
傳回
-
Promise<Window | undefined>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
get()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
)
取得視窗的詳細資料。
參數
-
windowId
號碼
-
queryOptions
QueryOptions 選用
Chrome 88 以上版本 -
回呼
函式選用
callback
參數如下所示:(window: Window) => void
-
窗戶
-
傳回
-
Promise<視窗>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
參數
-
queryOptions
QueryOptions 選用
Chrome 88 以上版本 -
回呼
函式選用
callback
參數如下所示:(windows: Window[]) => void
-
窗戶
視窗[]
-
傳回
-
Promise<視窗[]>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getCurrent()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
)
取得目前視窗。
參數
-
queryOptions
QueryOptions 選用
Chrome 88 以上版本 -
回呼
函式選用
callback
參數如下所示:(window: Window) => void
-
窗戶
-
傳回
-
Promise<視窗>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
getLastFocused()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
)
取得最近聚焦的視窗,通常是「位於頂端」的視窗。
參數
-
queryOptions
QueryOptions 選用
Chrome 88 以上版本 -
回呼
函式選用
callback
參數如下所示:(window: Window) => void
-
窗戶
-
傳回
-
Promise<視窗>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
remove()
chrome.windows.remove(
windowId: number,
callback?: function,
)
移除 (關閉) 視窗以及當中的所有分頁。
參數
-
windowId
號碼
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
update()
chrome.windows.update(
windowId: number,
updateInfo: object,
callback?: function,
)
更新視窗的屬性。僅指定要變更的屬性;未指定的屬性維持不變。
參數
-
windowId
號碼
-
updateInfo
物件
-
drawAttention
布林值 (選用)
設為
true
時,系統會以此方式顯示視窗,吸引使用者註意視窗,但不會變更聚焦視窗。這類效果會持續作用,直到使用者將焦點變更為視窗為止。如果視窗已聚焦,這個選項就不會發揮作用。如要取消先前的drawAttention
要求,請設為false
。 -
全神貫注
布林值 (選用)
如果為
true
,請將視窗移至最前方;無法與「最小化」狀態合併。如果為false
,請將下一個視窗排在 Z 順序最前面;不能與「全螢幕」或「最大化」狀態合併使用。 -
高度
數字 選填
將視窗調整為像素的高度。如果是面板,系統會忽略這個值。
-
左
數字 選填
將視窗移至螢幕左側邊緣的偏移值 (以像素為單位)。如果是面板,系統會忽略這個值。
-
state
WindowState 選用
視窗的新狀態。「最小化」、「最大化」和「全螢幕」狀態無法與「左」、「頂端」、「寬度」或「高度」合併。
-
上
數字 選填
將視窗移至螢幕頂端邊緣的偏移值 (以像素為單位)。如果是面板,系統會忽略這個值。
-
寬度
數字 選填
將視窗大小調整成像素的寬度。如果是面板,系統會忽略這個值。
-
-
回呼
函式選用
callback
參數如下所示:(window: Window) => void
-
窗戶
-
傳回
-
Promise<視窗>
Chrome 88 以上版本Manifest V3 以上版本支援 Promise,但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。
活動
onBoundsChanged
chrome.windows.onBoundsChanged.addListener(
callback: function,
)
在視窗調整大小後觸發;這個事件只會在提交新的邊界時分派,而不會針對進行中的變更分派。
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
建立視窗時觸發。
參數
-
回呼
功能
Chrome 46 以上版本callback
參數如下所示:(window: Window) => void
-
窗戶
已建立視窗的詳細資料。
-
-
篩選器
物件選用
-
windowTypes
所建立視窗類型的條件必須符合條件。預設為符合
['normal', 'popup']
。
-
onFocusChanged
chrome.windows.onFocusChanged.addListener(
callback: function,
filters?: object,
)
當目前聚焦的視窗變更時觸發。如果所有 Chrome 視窗都失去焦點,則傳回 chrome.windows.WINDOW_ID_NONE
。注意:在某些 Linux 視窗管理工具中,WINDOW_ID_NONE
一律會在 Chrome 視窗切換之前立即傳送。
參數
-
回呼
功能
Chrome 46 以上版本callback
參數如下所示:(windowId: number) => void
-
windowId
號碼
新聚焦視窗的 ID。
-
-
篩選器
物件選用
-
windowTypes
要移除的視窗類型必須符合的條件。預設為符合
['normal', 'popup']
。
-
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
刪除視窗時觸發 (關閉)。
參數
-
回呼
功能
Chrome 46 以上版本callback
參數如下所示:(windowId: number) => void
-
windowId
號碼
已移除視窗的 ID。
-
-
篩選器
物件選用
-
windowTypes
要移除的視窗類型必須符合的條件。預設為符合
['normal', 'popup']
。
-