本頁內容屬於 Chrome 應用程式平台，該平台已於 2020 年淘汰。至少在 2025 年 1 月之前，ChromeOS 的 Enterprise 和 Education 客戶仍能享有支援。進一步瞭解如何遷移應用程式。

本頁面由 Cloud Translation API 翻譯而成。

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
```