說明
使用 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
-
-
隱藏
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。
將視窗大小調整為
width
xheight
像素。resizeTo
函式如下所示:(width: number, height: number) => {...}
-
寬度
號碼
-
高度
號碼
-
-
還原
void
還原視窗,結束最大化、最小化或全螢幕狀態。
restore
函式如下所示:() => {...}
-
setAlwaysOnTop
void
設定視窗是否應保持在大多數其他視窗上方。需要
alwaysOnTopWindows
權限。setAlwaysOnTop
函式如下所示:(alwaysOnTop: boolean) => {...}
-
alwaysOnTop
boolean
-
-
setBounds
void
已淘汰使用 innerBounds 或 outerBounds。
設定視窗的內部邊界。
setBounds
函式如下所示:(bounds: 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()
來變更這個屬性。 -
邊界已淘汰
使用 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
用於指定視窗內容的初始位置、初始大小和限制 (不包括視窗裝飾)。如果也指定了
id
,且先前已顯示相符id
的視窗,系統會改用所儲存的邊界。請注意,內部和外部邊界之間的邊框間距是由 OS 決定。因此,如果為
innerBounds
和outerBounds
設定相同的邊界屬性,就會導致錯誤。這是 Chrome 36 版的新功能。
-
maxHeight
數字 選填
已淘汰使用 innerBounds 或 outerBounds。
視窗高度上限。
-
maxWidth
數字 選填
已淘汰使用 innerBounds 或 outerBounds。
視窗寬度上限。
-
minHeight
數字 選填
已淘汰使用 innerBounds 或 outerBounds。
視窗高度下限。
-
minWidth
數字 選填
已淘汰使用 innerBounds 或 outerBounds。
視窗寬度。
-
outerBounds
用於指定視窗的初始位置、初始大小和限制 (包括標題列和頁框等視窗裝飾)。如果也指定了
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
指定要建立的視窗類型。
列舉
"shell"
預設視窗類型。
"panel"
OS 管理視窗 (已淘汰)。
方法
canSetVisibleOnAllWorkspaces()
chrome.app.window.canSetVisibleOnAllWorkspaces()
目前的平台是否支援在所有工作區中顯示視窗。
傳回
-
boolean
create()
chrome.app.window.create(
url: string,
options?: CreateWindowOptions,
callback?: function,
)
指定視窗大小和位置的方式有很多種。最簡單的做法是完全不指定任何項目,在此情況下,系統會使用預設大小和平台依附位置。
如要設定視窗的位置、大小和限制條件,請使用 innerBounds
或 outerBounds
屬性。內邊界不包含視窗裝飾。外框包括視窗的標題列和頁框。請注意,內部和外部邊界之間的邊框間距是由 OS 決定。因此,為內部和外部邊界設定相同的屬性會視為錯誤 (例如同時設定 innerBounds.left
和 outerBounds.left
)。
如要讓系統自動記住視窗的位置,你可以指定視窗位置。如果視窗具有 ID,每當視窗移動或調整大小時,這個 ID 都會用來記住視窗的大小和位置。後續開啟相同 ID 的視窗時,系統會使用這個大小和位置取代指定的邊界。如果您需要開啟視窗,其 ID 位於系統所儲存預設值以外的位置,可以建立一個隱藏視窗,然後移至所需的位置再顯示。
參數
-
網址
字串
-
選項
-
回呼
函式選用
callback
參數如下所示:(createdWindow: AppWindow) => void
-
createdWindow
-
傳回
-
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 版中的新功能。
傳回
活動
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