chrome.app.window

說明

使用 chrome.app.window API 建立視窗。Windows 提供選用的頁框，內含標題列和大小控制項。但不會與任何 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

    布林值

• 最大化

  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) => {...}

  • 界限

    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() 即可變更這項屬性。

• 界限

  ContentBounds 選用

  已淘汰

  使用 innerBounds 或 outerBounds。

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

• 全神貫注

  布林值 選填

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

• 相框

  string |FrameOptions 選用

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

  M36 新增 FrameOptions 的使用方式。

• 隱藏

  布林值 選填

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

• 圖示

  string optional

  Chrome 54 以上版本

  視窗圖示的網址。將 showInShelf 設為 true 時，視窗可有專屬的圖示。網址必須為全域或擴充功能的本機網址。

• id

  string optional

  用於識別視窗的 ID。這個屬性可用於記住視窗的大小和位置，並在稍後開啟具有相同 ID 的視窗時，還原該幾何圖形。建立含有特定 ID 的視窗時，如果另一個有相同 ID 的視窗已建立，則系統會聚焦目前開啟的視窗，不會建立新視窗。

• innerBounds

  BoundsSpecification 選用

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

  請注意，內邊界和外部邊界的邊框間距取決於 OS。因此，為 innerBounds 和 outerBounds 設定相同的邊界屬性會導致錯誤。

  這是 Chrome 36 的新功能。

• maxHeight

  編號 選填

  已淘汰

  使用 innerBounds 或 outerBounds。

  視窗高度上限。

• maxWidth

  編號 選填

  已淘汰

  使用 innerBounds 或 outerBounds。

  視窗寬度上限。

• minHeight

  編號 選填

  已淘汰

  使用 innerBounds 或 outerBounds。

  視窗高度下限。

• minWidth

  編號 選填

  已淘汰

  使用 innerBounds 或 outerBounds。

  視窗寬度下限。

• outerBounds

  BoundsSpecification 選用

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

  請注意，內邊界和外部邊界的邊框間距取決於 OS。因此，為 innerBounds 和 outerBounds 設定相同的邊界屬性會導致錯誤。

  這是 Chrome 36 的新功能。

• 可調整大小

  布林值 選填

  如果為 true，使用者可以調整視窗大小。預設為 true。

• showInShelf

  布林值 選填

  Chrome 54 以上版本

  如果是 true，視窗內會有專屬的檔案櫃圖示。否則這個視窗會與其他應用程式相關聯的視窗整合到檔案櫃中。預設值為 false。如果 showInShelf 設為 True，就必須指定視窗 ID。

• 單例模式

  布林值 選填

  已淘汰

  不再支援具有相同 ID 的多個視窗。

  在預設情況下，如果您為視窗指定 ID，只有在其他視窗皆不存在相同 ID 的情況下，系統才會建立該視窗。如果已有 ID 相同的視窗，則系統會改為啟用該視窗。如果要用同一個 ID 建立多個視窗，可以將這個屬性設為 false。

• 州

  State (州/省) 選填

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

• 類型

  WindowType 選用

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

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

  要建立的視窗類型。

• visibleOnAllWorkspaces

  布林值 選填

  如果為 true，且受到平台支援，所有工作區都會顯示視窗。

FrameOptions

屬性

• activeColor

  string optional

  設定活動時允許視窗的頁框顏色。只有在頁框類型為 chrome 時，才能使用頁框顏色。

  只有在頁框類型為 chrome 時，才能使用頁框顏色。

  Chrome 36 推出新的頁框顏色功能。

• 顏色

  string optional

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

  Chrome 36 推出新的頁框顏色功能。

• inactiveColor

  string optional

  允許將閒置時的視窗邊框顏色設為非使用中色彩。只有在頁框類型為 chrome 時，才能使用頁框顏色。

  inactiveColor 必須搭配 color 使用。

  Chrome 36 推出新的頁框顏色功能。

• 類型

  string optional

  影格類型：none 或 chrome (預設為 chrome)。

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

  -webkit-app-region: drag 可用來標記可拖曳的區域。no-drag 可用來停用巢狀元素的這個樣式。

State

視窗狀態：正常、全螢幕、已最大化、最小化。

列舉

"normal"

「全螢幕」

「最大化」

「最小化」

WindowType

Chrome 45 以上版本

指定要建立的視窗類型，

列舉

"shell"
預設視窗類型。

"panel"
由 OS 管理視窗 (已淘汰)。

方法

canSetVisibleOnAllWorkspaces()

chrome.app.window.canSetVisibleOnAllWorkspaces()

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

傳回

• 布林值

create()

Promise

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

您可以透過多種不同方式指定視窗大小和位置。最簡單的方式都不要指定任何內容，在這種情況下，系統會使用預設大小和平台相依位置。

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

如要自動記住視窗的位置，您可以提供視窗 ID。如果視窗具有 ID，則當視窗移動或調整大小時，這個 ID 就會用來記住視窗的大小和位置。接著，系統會使用此大小和位置，而不是在後續開啟具有相同 ID 的視窗時，使用指定的邊界。如果您要開啟的視窗 ID 位於系統儲存的預設位置以外的位置，您可以將其設為隱藏，然後移至想要的位置，然後顯示該視窗。

參數

• 網址

  字串

• 選項

  CreateWindowOptions 選用

• 回呼

  函式 選用

  callback 參數如下所示：

  (createdWindow: AppWindow) => void

  • createdWindow

    AppWindow

傳回

• Promise<AppWindow>

  Chrome 117 以上版本

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

current()

chrome.app.window.current()

傳回目前指令碼環境 (例如 JavaScript「window」物件) 的 AppWindow 物件。您也可以在其他網頁的指令碼內容控制代碼上呼叫這個架構，例如 otherWindow.chrome.app.window.current()。

傳回

• AppWindow |未定義

get()

chrome.app.window.get(
  id: string,
)

取得具有指定 ID 的 AppWindow。如果沒有具有指定 ID 的視窗存在 null，則會傳回空值。Chrome 33 版新增這個方法。

參數

• id

  字串

傳回

• AppWindow |未定義

getAll()

chrome.app.window.getAll()

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

傳回

• AppWindow[]

活動

onBoundsChanged

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

調整視窗大小時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void

onClosed

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

視窗關閉時觸發。請注意，這項指令應從背景頁面以外的視窗監聽。這是因為在觸發事件時，關閉的視窗會在觸發事件時關閉，這表示在視窗指令碼環境中，並非所有 API 都能正常運作。

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void

onFullscreened

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

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

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void

onMaximized

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

在視窗最大化時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void

onMinimized

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

在視窗最小化時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void

onRestored

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

在還原視窗無法最小化或最大化時觸發。

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void