chrome.windows

說明

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

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

    布林值

    是否將視窗設為一律顯示在頂端。

  • 全神貫注

    布林值

    該視窗目前是否為聚焦的視窗。

  • 高度

    編號 選填

    視窗的高度 (包括頁框高度)，以像素為單位。在某些情況下，時段無法指派 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 查詢關閉的期間。

WindowState

Chrome 44 以上版本

此瀏覽器視窗的狀態。在某些情況下，時段無法指派 state 屬性；例如透過 sessions API 查詢關閉的期間。

列舉

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

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

"maximized
最大視窗狀態。

"fullscreen"
全螢幕視窗狀態。

"locked-fullscreen"
鎖定全螢幕視窗狀態。這個全螢幕狀態無法讓使用者採取動作，而只適用於 Chrome OS 中已加入許可清單的擴充功能。

WindowType

Chrome 44 以上版本

這是瀏覽器視窗的類型。在某些情況下，時段無法指派 type 屬性；例如透過 sessions API 查詢關閉的期間。

列舉

"normal"
一般瀏覽器視窗。

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

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

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

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

屬性

WINDOW_ID_CURRENT

代表目前視窗的 windowId 值。

值

-2

WINDOW_ID_NONE

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

值

-1

方法

create()

Promise 
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()

Promise 
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 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getAll()

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

取得所有視窗。

參數

  • queryOptions

    QueryOptions 選用

    Chrome 88 以上版本
  • 回呼

    函式 選用

    callback 參數如下所示： 

    (windows: Window[]) => void

傳回

  • Promise<Window[]>

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getCurrent()

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

取得目前的視窗。

參數

  • queryOptions

    QueryOptions 選用

    Chrome 88 以上版本
  • 回呼

    函式 選用

    callback 參數如下所示： 

    (window: Window) => void

傳回

  • Promise<Window>

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getLastFocused()

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

取得最近聚焦的視窗，通常是「最上方」的視窗。

參數

  • queryOptions

    QueryOptions 選用

    Chrome 88 以上版本
  • 回呼

    函式 選用

    callback 參數如下所示： 

    (window: Window) => void

傳回

  • Promise<Window>

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

remove()

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

移除 (關閉) 視窗及內所有分頁。

參數

  • windowId

    數字

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

update()

Promise 
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&lt;Window&gt;

    Chrome 88 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

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

    • 窗戶

      視窗

      所建立視窗的詳細資料。

  • 篩選器

    物件 optional

    • windowTypes

      WindowType[]

      所建立視窗類型必須符合的條件。預設會滿足 ['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

      WindowType[]

      需移除視窗類型的條件。預設會滿足 ['normal', 'popup']。

onRemoved

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

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

參數

  • 回呼

    函式

    Chrome 46 以上版本

    callback 參數如下所示： 

    (windowId: number) => void

    • windowId

      數字

      已移除視窗的 ID。

  • 篩選器

    物件 optional

    • windowTypes

      WindowType[]

      需移除視窗類型的條件。預設會滿足 ['normal', 'popup']。