chrome.windows

說明

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

指定要建立的瀏覽器視窗類型。「面板」已淘汰，且僅適用於 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

  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 查詢已關閉的視窗時。

WindowState

Chrome 44 以上版本

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

列舉

"normal"
正常視窗狀態 (未最小化、最大化或全螢幕)。

"最小化"
最小化視窗狀態。

「最大化」
最大化視窗狀態。

「全螢幕」
全螢幕視窗狀態。

「鎖定全螢幕」
鎖定的全螢幕視窗狀態。使用者動作無法退出這個全螢幕狀態，而且僅適用於 Chrome 作業系統的許可清單擴充功能。

WindowType

Chrome 44 以上版本

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

列舉

"normal"
一般瀏覽器視窗。

"popup"
瀏覽器彈出式視窗。

"panel"
此 API 已淘汰，Chrome 應用程式面板樣式視窗。擴充功能只能看到自己的面板視窗。

"app"
此 API 已淘汰。Chrome 應用程式視窗。擴充功能只能看到自己的應用程式視窗。

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

屬性

WINDOW_ID_CURRENT

代表目前視窗的 windowId 值。

值

-2

WINDOW_ID_NONE

windowId 值，代表缺少 Chrome 瀏覽器視窗。

值

-1

方法

create()

Promise

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 選用

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

  • url

    string|string[] optional

    要在視窗中以分頁開啟的網址或陣列。完整網址必須包含架構，例如「http://www.google.com」而非「www.google.com」。系統會將不符資格的網址視為擴充內容中的相對網址。預設為新分頁。

  • 寬度

    數字 選填

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

• 回呼

  函式選用

  callback 參數如下所示：

  (window?: Window)=>void

  • 窗戶

    視窗 選用

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

傳回

• Promise<視窗|未定義>

  Chrome 88 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

get()

Promise

chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
)

取得視窗的詳細資料。

參數

• windowId

  號碼

• queryOptions

  QueryOptions 選用

  Chrome 88 以上版本
• 回呼

  函式選用

  callback 參數如下所示：

  (window: Window)=>void

  • 窗戶

    視窗

傳回

• Promise<視窗>

  Chrome 88 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getAll()

Promise

chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

取得所有視窗。

參數

• queryOptions

  QueryOptions 選用

  Chrome 88 以上版本
• 回呼

  函式選用

  callback 參數如下所示：

  (windows: Window[])=>void

  • 窗戶

    視窗[]

傳回

• Promise<視窗[]>

  Chrome 88 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getCurrent()

Promise

chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
)

取得目前視窗。

參數

• queryOptions

  QueryOptions 選用

  Chrome 88 以上版本
• 回呼

  函式選用

  callback 參數如下所示：

  (window: Window)=>void

  • 窗戶

    視窗

傳回

• Promise<視窗>

  Chrome 88 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

getLastFocused()

Promise

chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
)

取得最近聚焦的視窗，通常是「位於頂端」的視窗。

參數

• queryOptions

  QueryOptions 選用

  Chrome 88 以上版本
• 回呼

  函式選用

  callback 參數如下所示：

  (window: Window)=>void

  • 窗戶

    視窗

傳回

• Promise<視窗>

  Chrome 88 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

remove()

Promise

chrome.windows.remove(
  windowId: number,
  callback?: function,
)

移除 (關閉) 視窗以及當中的所有分頁。

參數

• windowId

  號碼

• 回呼

  函式選用

  callback 參數如下所示：

  ()=>void

傳回

• Promise<void>

  Chrome 88 以上版本

  Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

update()

Promise

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

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

在視窗調整大小後觸發；這個事件只會在提交新的邊界時分派，而不會針對進行中的變更分派。

參數

• 回呼

  功能

  callback 參數如下所示：

  (window: Window)=>void

  • 窗戶

    視窗

onCreated

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

建立視窗時觸發。

參數

• 回呼

  功能

  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 視窗管理工具中，WINDOW_ID_NONE 一律會在 Chrome 視窗切換之前立即傳送。

參數

• 回呼

  功能

  Chrome 46 以上版本

  callback 參數如下所示：

  (windowId: number)=>void

  • windowId

    號碼

    新聚焦視窗的 ID。

• 篩選器

  物件選用

  • windowTypes

    WindowType[]

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

onRemoved

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

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

參數

• 回呼

  功能

  Chrome 46 以上版本

  callback 參數如下所示：

  (windowId: number)=>void

  • windowId

    號碼

    已移除視窗的 ID。

• 篩選器

  物件選用

  • windowTypes

    WindowType[]

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