chrome.app.window

說明

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

類型

AppWindow

屬性

• contentWindow

  視窗

  已建立子項的 JavaScript「window」物件。

• id

  字串

  建立視窗時使用的 ID。

• innerBounds

  邊界

  視窗內容的位置、大小和限制，不包括視窗裝飾。這是 Chrome 36 版的新功能。

• outerBounds

  邊界

  視窗的位置、大小和限制，包括視窗裝飾，例如標題列和頁框。這是 Chrome 36 版的新功能。

• clearAttention

  void

  清楚注意視窗。

  clearAttention 函式如下所示：

  ()=> {...}

• 關閉

  void

  關閉視窗。

  close 函式如下所示：

  ()=> {...}

• drawAttention

  void

  將注意力放在視窗上。

  drawAttention 函式如下所示：

  ()=> {...}

• 主軸

  void

  將焦點對準視窗。

  focus 函式如下所示：

  ()=> {...}

• 全螢幕

  void

  全螢幕視窗。

  使用者只要按下 ESC 鍵即可還原視窗。應用程式可在按下 ESC 時要求 app.window.fullscreen.overrideEsc 權限，並藉由在 keydown 和 keyup 處理常式呼叫 .preventDefault() 來取消事件，藉此防止系統保留全螢幕狀態，如下所示：

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

  請注意，window.fullscreen() 會使整個視窗變成全螢幕，且不需使用者手勢。HTML5 全螢幕 API 也也可用來進入全螢幕模式 (詳情請參閱網路 API)。

  fullscreen 函式如下所示：

  ()=> {...}

• getBounds

  void

  已淘汰

  使用 innerBounds 或 outerBounds。

  將視窗的內部邊界做為 ContentBounds 物件取得。

  getBounds 函式如下所示：

  ()=> {...}

  • returns

    ContentBounds

• 隱藏

  void

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

  hide 函式如下所示：

  ()=> {...}

• isAlwaysOnTop

  void

  窗戶是否總是在最上層？

  isAlwaysOnTop 函式如下所示：

  ()=> {...}

  • returns

    boolean

• isFullscreen

  void

  視窗是否為全螢幕？如果視窗是以全螢幕建立，或透過 AppWindow 或 HTML5 全螢幕 API 設為全螢幕，則此屬性為 true。

  isFullscreen 函式如下所示：

  ()=> {...}

  • returns

    boolean

• isMaximized

  void

  視窗是否已最大化？

  isMaximized 函式如下所示：

  ()=> {...}

  • returns

    boolean

• isMinimized

  void

  窗戶是否最小化？

  isMinimized 函式如下所示：

  ()=> {...}

  • returns

    boolean

• 最大化

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

  • 寬度

    號碼

  • 高度

    號碼

• 還原

  void

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

  restore 函式如下所示：

  ()=> {...}

• setAlwaysOnTop

  void

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

  setAlwaysOnTop 函式如下所示：

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

  • alwaysOnTop

    boolean

• setBounds

  void

  已淘汰

  使用 innerBounds 或 outerBounds。

  設定視窗的內部邊界。

  setBounds 函式如下所示：

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

  • 邊界

    ContentBounds

• setVisibleOnAllWorkspaces

  void

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

  setVisibleOnAllWorkspaces 函式如下所示：

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

  • alwaysVisible

    boolean

• 顯示

  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 可用於停用巢狀元素的這個樣式。

  FrameOptions 的使用方式為 M36 的新功能。

• 隱藏

  布林值 (選用)

  如果為 true，則會以隱藏狀態建立視窗。建立完成後，在視窗中呼叫 show() 來顯示內容。預設值為 false。

• 圖示

  字串 選用

  Chrome 54 以上版本

  視窗圖示的網址。當 showInShelf 設為 true 時，視窗可以有自己的圖示。這個網址必須是全域網址或擴充功能的本機網址。

• id

  字串 選用

  用於識別視窗的 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 版的新功能。

• resizable

  布林值 (選用)

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

• showInShelf

  布林值 (選用)

  Chrome 54 以上版本

  如果為 true，視窗將有專屬的檔案櫃圖示。否則，視窗會與該應用程式相關聯的其他視窗歸在檔案櫃中。預設為 False。如果 showInShelf 設為 True，就必須指定視窗 ID。

• 單例模式

  布林值 (選用)

  已淘汰

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

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

• state

  狀態 選填

  視窗的初始狀態，允許建立全螢幕、最大化或最小化。預設為「一般」。

• 類型

  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

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

列舉

WindowType

Chrome 45 以上版本

指定要建立的視窗類型。

列舉

"shell"
預設視窗類型。

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

方法

canSetVisibleOnAllWorkspaces()

chrome.app.window.canSetVisibleOnAllWorkspaces()

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

傳回

• boolean

create()

Promise

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

指定視窗大小和位置的方式有很多種。最簡單的做法是完全不指定任何項目，在此情況下，系統會使用預設大小和平台依附位置。

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

如要讓系統自動記住視窗的位置，你可以指定視窗位置。如果視窗具有 ID，每當視窗移動或調整大小時，這個 ID 都會用來記住視窗的大小和位置。後續開啟相同 ID 的視窗時，系統會使用這個大小和位置取代指定的邊界。如果您需要開啟視窗，其 ID 位於系統所儲存預設值以外的位置，可以建立一個隱藏視窗，然後移至所需的位置再顯示。

參數

• url

  字串

• 選項

  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 的視窗，就會傳回空值。這是 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