chrome.app.window

說明

使用 chrome.app.window API 建立視窗。視窗可選用含有標題列和大小控制項的框架。不會與任何 Chrome 瀏覽器視窗建立關聯。如需這些選項的示範，請參閱視窗狀態範例。

類型

AppWindow

屬性

• contentWindow

  視窗

  為建立的子項提供 JavaScript「視窗」物件。

• id

  字串

  建立視窗時使用的 ID。

• innerBounds

  邊界

  視窗內容的位置、大小和限制，不含視窗裝飾。這是 Chrome 36 新增的屬性。

• outerBounds

  邊界

  視窗的位置、大小和限制，包括視窗裝飾，例如標題列和框架。這是 Chrome 36 新增的屬性。

• clearAttention

  void

  視窗明顯吸引注意力。

  clearAttention 函式如下所示：

  () => {...}

• 關閉

  void

  關閉視窗。

  close 函式如下所示：

  () => {...}

• drawAttention

  void

  將焦點放在視窗上。

  drawAttention 函式如下所示：

  () => {...}

• 焦點

  void

  聚焦視窗。

  focus 函式如下所示：

  () => {...}

• 全螢幕

  void

  將視窗設為全螢幕。

  使用者可以按下 ESC 鍵還原視窗。應用程式可以要求 app.window.fullscreen.overrideEsc 權限，並在 keydown 和 keyup 處理常式中呼叫 .preventDefault() 取消事件，防止使用者按下 ESC 鍵時離開全螢幕狀態，如下所示：

  window.onkeydown = window.onkeyup = function(e) { if (e.keyCode == 27 /* ESC *\/) { e.preventDefault(); } };

  請注意，window.fullscreen() 會導致整個視窗進入全螢幕模式，且不需要使用者手勢。您也可以使用 HTML5 全螢幕 API 進入全螢幕模式 (詳情請參閱「Web API」)。

  fullscreen 函式如下所示：

  () => {...}

• getBounds

  void

  已淘汰

  請使用 innerBounds 或 outerBounds。

  以 ContentBounds 物件的形式取得視窗的內部邊界。

  getBounds 函式如下所示：

  () => {...}

  • returns

    ContentBounds

• 隱藏

  void

  隱藏視窗。如果視窗已隱藏，則不會執行任何動作。

  hide 函式如下所示：

  () => {...}

• isAlwaysOnTop

  void

  視窗是否一律顯示在最上層？

  isAlwaysOnTop 函式如下所示：

  () => {...}

  • returns

    布林值

• isFullscreen

  void

  視窗是否為全螢幕？如果視窗建立時為全螢幕，或透過 AppWindow 或 HTML5 全螢幕 API 設為全螢幕，則為 True。

  isFullscreen 函式如下所示：

  () => {...}

  • returns

    布林值

• isMaximized

  void

  視窗是否已最大化？

  isMaximized 函式如下所示：

  () => {...}

  • returns

    布林值

• isMinimized

  void

  視窗是否已縮到最小？

  isMinimized 函式如下所示：

  () => {...}

  • returns

    布林值

• maximize

  void

  將視窗放到最大。

  maximize 函式如下所示：

  () => {...}

• 最小化

  void

  將視窗縮到最小。

  minimize 函式如下所示：

  () => {...}

• moveTo

  void

  自 Chrome 43 起淘汰

  使用 outerBounds。

  將視窗移至位置 (left, top)。

  moveTo 函式如下所示：

  (left: number, top: number) => {...}

  • 左

    數字

  • 頂端

    數字

• resizeTo

  void

  自 Chrome 43 起淘汰

  使用 outerBounds。

  將視窗大小調整為 widthxheight 像素。

  resizeTo 函式如下所示：

  (width: number, height: number) => {...}

  • 寬度

    數字

  • 高度

    數字

• restore

  void

  還原視窗，退出最大化、最小化或全螢幕狀態。

  restore 函式如下所示：

  () => {...}

• setAlwaysOnTop

  void

  設定視窗是否應保持在大多數其他視窗上方。需要 alwaysOnTopWindows 權限。

  setAlwaysOnTop 函式如下所示：

  (alwaysOnTop: boolean) => {...}

  • alwaysOnTop

    布林值

• setBounds

  void

  已淘汰

  請使用 innerBounds 或 outerBounds。

  設定視窗的內部邊界。

  setBounds 函式如下所示：

  (bounds: ContentBounds) => {...}

  • bounds

    ContentBounds

• setVisibleOnAllWorkspaces

  void

  設定是否要在所有工作區顯示視窗。(僅限支援這項功能的平台)。

  setVisibleOnAllWorkspaces 函式如下所示：

  (alwaysVisible: boolean) => {...}

  • alwaysVisible

    布林值

• 顯示

  void

  顯示視窗。如果視窗已顯示，則不會有任何動作。如果 focused 設為 true 或省略，則聚焦視窗。

  show 函式如下所示：

  (focused?: boolean) => {...}

  • 全神貫注

    布林值 選填

Bounds

屬性

• 高度

  數字

  這個屬性可用於讀取或寫入內容或視窗的目前高度。

• 左

  數字

  這個屬性可用於讀取或寫入內容或視窗目前的 X 座標。

• maxHeight

  數字 選填

  這項屬性可用於讀取或寫入內容或視窗目前的最高高度。null 值表示「未指定」。

• maxWidth

  數字 選填

  這項屬性可用於讀取或寫入內容或視窗目前的寬度上限。null 值表示「未指定」。

• minHeight

  數字 選填

  這個屬性可用於讀取或寫入內容或視窗目前的最小高度。null 值表示「未指定」。

• minWidth

  數字 選填

  這個屬性可用於讀取或寫入內容或視窗目前的最小寬度。null 值表示「未指定」。

• 頂端

  數字

  這個屬性可用於讀取或寫入內容或視窗目前的 Y 座標。

• 寬度

  數字

  這個屬性可用於讀取或寫入內容或視窗的目前寬度。

• setMaximumSize

  void

  設定內容或視窗的大小上限。寬度或高度上限可設為 null，以移除限制。如果值為 undefined，限制條件會維持不變。

  setMaximumSize 函式如下所示：

  (maxWidth: number, maxHeight: number) => {...}

  • maxWidth

    數字

  • maxHeight

    數字

• setMinimumSize

  void

  設定內容或視窗的大小下限限制。將寬度或高度下限設為 null，即可移除限制。如果值為 undefined，限制條件會維持不變。

  setMinimumSize 函式如下所示：

  (minWidth: number, minHeight: number) => {...}

  • minWidth

    數字

  • minHeight

    數字

• setPosition

  void

  設定內容或視窗的左側和頂部位置。

  setPosition 函式如下所示：

  (left: number, top: number) => {...}

  • 左

    數字

  • 頂端

    數字

• setSize

  void

  設定內容或視窗的寬度和高度。

  setSize 函式如下所示：

  (width: number, height: number) => {...}

  • 寬度

    數字

  • 高度

    數字

BoundsSpecification

屬性

• 高度

  數字 選填

  內容或視窗的高度。

• 左

  數字 選填

  內容或視窗的 X 座標。

• maxHeight

  數字 選填

  內容或視窗的高度上限。

• maxWidth

  數字 選填

  內容或視窗的寬度上限。

• minHeight

  數字 選填

  內容或視窗的最小高度。

• minWidth

  數字 選填

  內容或視窗的最小寬度。

• 頂端

  數字 選填

  內容或視窗的 Y 座標。

• 寬度

  數字 選填

  內容或視窗的寬度。

ContentBounds

屬性

• 高度

  數字 選填

• 左

  數字 選填

• 頂端

  數字 選填

• 寬度

  數字 選填

CreateWindowOptions

屬性

• alwaysOnTop

  布林值 選填

  如果設為 true，視窗會保持在大多數其他視窗上方。如果有多個這類視窗，目前聚焦的視窗會位於前景。需要 alwaysOnTopWindows 權限。預設值為 false。

  建立視窗後，請對視窗呼叫 setAlwaysOnTop()，以變更這項屬性。

• bounds

  ContentBounds 選用

  已淘汰

  請使用 innerBounds 或 outerBounds。

  視窗中內容的大小和位置 (不含標題列)。如果同時指定了 ID，且先前已顯示過 ID 相符的視窗，系統會改用視窗記住的邊界。

• 全神貫注

  布林值 選填

  如果設為 true，視窗建立時會聚焦。預設為 true。

• 相框

  string | FrameOptions 選用

  框架類型：none 或 chrome (預設為 chrome)。如果是 none，可以使用 -webkit-app-region CSS 屬性，將可拖曳性套用至應用程式視窗。-webkit-app-region: drag 可用來將區域標示為可拖曳。no-drag 可用於停用巢狀元素的樣式。

  FrameOptions 是 M36 的新功能。

• 隱藏

  布林值 選填

  如果設為 true，系統會在隱藏狀態下建立視窗。視窗建立後，請呼叫 show() 顯示視窗。預設值為 false。

• 圖示

  字串 選填

  Chrome 54 以上版本

  視窗圖示的網址。如果 showInShelf 設為 true，視窗可以有自己的圖示。網址應為全域網址或擴充功能本機網址。

• id

  字串 選填

  用於識別視窗的 ID。這會用來記住視窗的大小和位置，並在之後開啟具有相同 ID 的視窗時還原該幾何圖形。如果建立的視窗 ID 與現有視窗相同，系統會聚焦於目前開啟的視窗，而不是建立新視窗。

• innerBounds

  BoundsSpecification 選填

  用於指定視窗內容 (不含視窗裝飾) 的初始位置、初始大小和限制。如果同時指定 id，且先前已顯示具有相符 id 的視窗，系統會改用記住的邊界。

  請注意，內外邊界之間的邊框間距是由 OS 決定。因此，如果為 innerBounds 和 outerBounds 設定相同的 bounds 屬性，就會發生錯誤。

  這是 Chrome 36 新增的屬性。

• maxHeight

  數字 選填

  已淘汰

  請使用 innerBounds 或 outerBounds。

  視窗高度上限。

• maxWidth

  數字 選填

  已淘汰

  請使用 innerBounds 或 outerBounds。

  視窗寬度上限。

• minHeight

  數字 選填

  已淘汰

  請使用 innerBounds 或 outerBounds。

  視窗高度下限。

• minWidth

  數字 選填

  已淘汰

  請使用 innerBounds 或 outerBounds。

  視窗寬度下限。

• outerBounds

  BoundsSpecification 選填

  用於指定視窗的初始位置、初始大小和限制 (包括標題列和框架等視窗裝飾)。如果同時指定 id，且先前已顯示具有相符 id 的視窗，系統會改用記住的邊界。

  請注意，內外邊界之間的邊框間距是由 OS 決定。因此，如果為 innerBounds 和 outerBounds 設定相同的 bounds 屬性，就會發生錯誤。

  這是 Chrome 36 新增的屬性。

• 可調整大小

  布林值 選填

  如果設為 True，使用者就能調整視窗大小。預設為 true。

• showInShelf

  布林值 選填

  Chrome 54 以上版本

  如果設為 True，視窗會有專屬的工作列圖示。否則，視窗會與應用程式相關聯的其他視窗一起分組在工作列中。預設值為 false。如果 showInShelf 設為 true，則必須指定視窗 ID。

• 單例模式

  布林值 選填

  已淘汰

  不再支援多個視窗使用相同 ID。

  根據預設，如果您為視窗指定 ID，只有在沒有其他視窗使用相同 ID 時，系統才會建立視窗。如果已有相同 ID 的視窗，系統會改為啟用該視窗。如要建立多個 ID 相同的視窗，請將這項屬性設為 false。

• state

  State 選填

  視窗的初始狀態，可建立為全螢幕、最大化或最小化。預設值為「normal」。

• 類型

  WindowType 選填

  Chrome 45 以上版本 自 Chrome 69 起淘汰

  所有應用程式視窗都使用「殼層」視窗類型

  要建立的視窗類型。

• visibleOnAllWorkspaces

  布林值 選填

  如果設為 true，且平台支援，視窗就會顯示在所有工作區。

FrameOptions

屬性

• activeColor

  字串 選填

  允許設定視窗啟用時的框架顏色。只有在框架類型為 chrome 時，才能為框架著色。

  只有在框架類型為 chrome 時，才能為框架著色。

  Chrome 36 新增了框架著色功能。

• 顏色

  字串 選填

  允許設定頁框顏色。只有在框架類型為 chrome 時，才能為框架著色。

  Chrome 36 新增了框架著色功能。

• inactiveColor

  字串 選填

  允許將視窗在非使用中時的邊框顏色，設為與使用中時不同的顏色。只有在框架類型為 chrome 時，才能為框架著色。

  inactiveColor 必須與 color 搭配使用。

  Chrome 36 新增了框架著色功能。

• 類型

  字串 選填

  框架類型：none 或 chrome (預設為 chrome)。

  如果是 none，可以使用 -webkit-app-region CSS 屬性，將可拖曳性套用至應用程式視窗。

  -webkit-app-region: drag 可用來將區域標示為可拖曳。no-drag 可用於停用巢狀元素的樣式。

State

視窗狀態：一般、全螢幕、最大化、最小化。

列舉

"normal"

"fullscreen"

"maximized"

"minimized"

WindowType

Chrome 45 以上版本

指定要建立的視窗類型。

列舉

"shell"
預設視窗類型。

「panel」
OS 代管視窗 (已淘汰)。

方法

canSetVisibleOnAllWorkspaces()

chrome.app.window.canSetVisibleOnAllWorkspaces(): boolean

目前平台是否支援在所有工作區顯示視窗。

傳回

• 布林值

create()

Promise

chrome.app.window.create(
  url: string,
  options?: CreateWindowOptions,
  callback?: function,
): Promise<AppWindow>

視窗的大小和位置可以透過多種方式指定。最簡單的做法是完全不指定任何內容，這樣系統就會使用預設大小和平台相關位置。

如要設定視窗的位置、大小和限制，請使用 innerBounds 或 outerBounds 屬性。內部邊界不含視窗裝飾。外部邊界包括視窗的標題列和框架。請注意，內外邊界之間的邊框間距是由 OS 決定。因此，如果為內外邊界設定相同屬性 (例如同時設定 innerBounds.left 和 outerBounds.left)，系統會視為錯誤。

如要自動記住視窗位置，可以為視窗指定 ID。如果視窗有 ID，系統會使用這個 ID 記住視窗的位置和大小，無論視窗移動或調整大小，都能保持一致。之後，如果開啟具有相同 ID 的視窗，系統就會使用這個大小和位置，而非指定的邊界。如要開啟視窗，並將 ID 設在預設位置以外的地方，可以先建立隱藏視窗，再將視窗移至所需位置，然後顯示視窗。

參數

• 網址

  字串

• 選項

  CreateWindowOptions 選用

• callback

  函式 選填

  callback 參數如下：

  (createdWindow: AppWindow) => void

  • createdWindow

    AppWindow

傳回

• Promise<AppWindow>

  Chrome 117 以上版本

  Promise 僅適用於 Manifest V3 以上版本，其他平台則須使用回呼。

current()

chrome.app.window.current(): AppWindow | undefined

傳回目前指令碼內容 (即 JavaScript「window」物件) 的 AppWindow 物件。您也可以在另一個網頁的指令碼內容控制代碼上呼叫這個方法，例如：otherWindow.chrome.app.window.current()。

傳回

• AppWindow | undefined

get()

chrome.app.window.get(
  id: string,
): AppWindow | undefined

取得具有指定 ID 的 AppWindow。如果沒有與指定 ID 相符的視窗，則會傳回空值。這是 Chrome 33 的新方法。

參數

• id

  字串

傳回

• AppWindow | undefined

getAll()

chrome.app.window.getAll(): AppWindow[]

取得目前建立的所有應用程式視窗陣列。這是 Chrome 33 的新方法。

傳回

• AppWindow[]

事件

onBoundsChanged

chrome.app.window.onBoundsChanged.addListener(
  callback: function,
)

在視窗大小調整時觸發。

參數

• callback

  函式

  callback 參數如下：

  () => void

onClosed

chrome.app.window.onClosed.addListener(
  callback: function,
)

在視窗關閉時觸發。請注意，這項事件應從要關閉的視窗以外的視窗 (例如背景頁面) 監聽。這是因為事件觸發時，關閉的視窗會處於終止程序，也就是說，視窗指令碼內容中的部分 API 將無法運作。

參數

• callback

  函式

  callback 參數如下：

  () => void

onFullscreened

chrome.app.window.onFullscreened.addListener(
  callback: function,
)

視窗全螢幕顯示時 (透過 AppWindow 或 HTML5 API) 觸發。

參數

• callback

  函式

  callback 參數如下：

  () => void

onMaximized

chrome.app.window.onMaximized.addListener(
  callback: function,
)

視窗最大化時觸發。

參數

• callback

  函式

  callback 參數如下：

  () => void

onMinimized

chrome.app.window.onMinimized.addListener(
  callback: function,
)

視窗縮到最小時觸發。

參數

• callback

  函式

  callback 參數如下：

  () => void

onRestored

chrome.app.window.onRestored.addListener(
  callback: function,
)

視窗從最小化或最大化狀態還原時，就會觸發這個事件。

參數

• callback

  函式

  callback 參數如下：

  () => void