说明
使用 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 键恢复该窗口。应用可通过在 keydown 和 keyup 处理程序中调用 .preventDefault() 来请求
app.window.fullscreen.overrideEsc
权限并取消事件来防止在按下 ESC 时退出全屏状态,如下所示:window.onkeydown = window.onkeyup = function(e) { if (e.keyCode == 27 /* ESC *\/) { e.preventDefault(); } };
请注意,
window.fullscreen()
会导致整个窗口进入全屏模式,不需要用户手势。HTML5 全屏 API 还可用于进入全屏模式(请参阅 Web API 了解详情)。fullscreen
函数如下所示:() => {...}
-
getBounds
void
<ph type="x-smartling-placeholder"></ph> 已弃用使用 innerBounds 或 outerBounds。
以
ContentBounds
对象的形式获取窗口的内边界。getBounds
函数如下所示:() => {...}
-
隐藏
void
隐藏窗口。如果窗口已隐藏,不执行任何操作。
hide
函数如下所示:() => {...}
-
isAlwaysOnTop
void
窗口始终位于顶部吗?
isAlwaysOnTop
函数如下所示:() => {...}
-
返回
布尔值
-
-
isFullscreen
void
窗口是否为全屏窗口?如果窗口是通过
AppWindow
或 HTML5 全屏 API 创建为全屏窗口或设为全屏,结果将为 true。isFullscreen
函数如下所示:() => {...}
-
返回
布尔值
-
-
isMaximized
void
窗口是否已最大化?
isMaximized
函数如下所示:() => {...}
-
返回
布尔值
-
-
isMinimized
void
窗口是否已最小化?
isMinimized
函数如下所示:() => {...}
-
返回
布尔值
-
-
最大化
void
最大化窗口。
maximize
函数如下所示:() => {...}
-
最小化
void
最小化窗口。
minimize
函数如下所示:() => {...}
-
moveTo
void
<ph type="x-smartling-placeholder"></ph> 自 Chrome 43 起弃用使用 outerBounds。
将窗口移至位置 (
left
,top
)。moveTo
函数如下所示:(left: number, top: number) => {...}
-
左侧
number
-
顶部
number
-
-
resizeTo
void
<ph type="x-smartling-placeholder"></ph> 自 Chrome 43 起弃用使用 outerBounds。
将窗口大小调整为
width
xheight
像素。resizeTo
函数如下所示:(width: number, height: number) => {...}
-
width
number
-
高度
number
-
-
恢复
void
恢复窗口,即退出最大化、最小化或全屏状态。
restore
函数如下所示:() => {...}
-
setAlwaysOnTop
void
设置窗口是否应位于大多数其他窗口的上方。需要
alwaysOnTopWindows
权限。setAlwaysOnTop
函数如下所示:(alwaysOnTop: boolean) => {...}
-
alwaysOnTop
布尔值
-
-
setBounds
void
<ph type="x-smartling-placeholder"></ph> 已弃用使用 innerBounds 或 outerBounds。
设置窗口的内边界。
setBounds
函数如下所示:(bounds: ContentBounds) => {...}
-
bounds
-
-
setVisibleOnAllWorkspaces
void
设置是否在所有工作区中显示该窗口。(仅适用于支持此功能的平台)。
setVisibleOnAllWorkspaces
函数如下所示:(alwaysVisible: boolean) => {...}
-
alwaysVisible
布尔值
-
-
显示
void
显示窗口。如果该窗口已处于可见状态,则不执行任何操作。如果
focused
设置为 true 或省略,则聚焦窗口。show
函数如下所示:(focused?: boolean) => {...}
-
专注
布尔值(可选)
-
Bounds
属性
-
高度
number
此属性可用于读取或写入内容或窗口的当前高度。
-
左侧
number
此属性可用于读取或写入内容或窗口的当前 X 坐标。
-
maxHeight
编号(选填)
此属性可用于读取或写入内容或窗口的当前最大高度。值
null
表示“未指定”。 -
maxWidth
编号(选填)
此属性可用于读取或写入内容或窗口的当前最大宽度。值
null
表示“未指定”。 -
minHeight
编号(选填)
此属性可用于读取或写入内容或窗口的当前最小高度。值
null
表示“未指定”。 -
minWidth
编号(选填)
此属性可用于读取或写入内容或窗口的当前最小宽度。值
null
表示“未指定”。 -
顶部
number
此属性可用于读取或写入内容或窗口的当前 Y 坐标。
-
width
number
此属性可用于读取或写入内容或窗口的当前宽度。
-
setMaximumSize
void
设置内容或窗口的最大大小限制。可将最大宽度或高度设置为
null
以移除约束条件。如果值为undefined
,约束条件将保持不变。setMaximumSize
函数如下所示:(maxWidth: number, maxHeight: number) => {...}
-
maxWidth
number
-
maxHeight
number
-
-
setMinimumSize
void
设置内容或窗口的最小尺寸约束条件。可以将最小宽度或高度设置为
null
以移除约束条件。如果值为undefined
,约束条件将保持不变。setMinimumSize
函数如下所示:(minWidth: number, minHeight: number) => {...}
-
minWidth
number
-
minHeight
number
-
-
setPosition
void
设置内容或窗口的左侧和顶部位置。
setPosition
函数如下所示:(left: number, top: number) => {...}
-
左侧
number
-
顶部
number
-
-
setSize
void
设置内容或窗口的宽度和高度。
setSize
函数如下所示:(width: number, height: number) => {...}
-
width
number
-
高度
number
-
BoundsSpecification
属性
-
高度
编号(选填)
内容或窗口的高度。
-
左侧
编号(选填)
内容或窗口的 X 坐标。
-
maxHeight
编号(选填)
内容或窗口的最大高度。
-
maxWidth
编号(选填)
内容或窗口的最大宽度。
-
minHeight
编号(选填)
内容或窗口的最小高度。
-
minWidth
编号(选填)
内容或窗口的最小宽度。
-
顶部
编号(选填)
内容或窗口的 Y 坐标。
-
width
编号(选填)
内容或窗口的宽度。
ContentBounds
属性
-
高度
编号(选填)
-
左侧
编号(选填)
-
顶部
编号(选填)
-
width
编号(选填)
CreateWindowOptions
属性
-
alwaysOnTop
布尔值(可选)
如果为 true,相应窗口将停留在大多数其他窗口的上方。如果存在多个这种类型的窗口,则当前聚焦的窗口将位于前台。需要
alwaysOnTopWindows
权限。默认值为 false。在创建后对窗口调用
setAlwaysOnTop()
即可更改此属性。 -
bounds<ph type="x-smartling-placeholder"></ph> 已弃用
使用 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。
-
图标
字符串(可选)
Chrome 54 及更高版本窗口图标的网址。当 showInShelf 设置为 true 时,窗口可以有自己的图标。该网址应为全局网址或扩展程序本地网址。
-
id
字符串(可选)
用于标识窗口的 ID。这将用于记住窗口的大小和位置,并在稍后打开具有相同 ID 的窗口时恢复该几何图形。如果创建了具有指定 ID 的窗口,而已存在具有相同 ID 的另一个窗口,则系统会聚焦当前打开的窗口,而不是创建新窗口。
-
innerBounds
用于指定窗口内容(不包括窗口装饰)的初始位置、初始大小和约束条件。如果还指定了
id
,且之前已显示过具有匹配id
的窗口,则系统会改用记住的边界。请注意,内外边界之间的内边距由操作系统决定。因此,为
innerBounds
和outerBounds
设置相同的 bounds 属性会导致错误。这是 Chrome 36 中的新属性。
-
maxHeight
编号(选填)
<ph type="x-smartling-placeholder"></ph> 已弃用使用 innerBounds 或 outerBounds。
窗口的最大高度。
-
maxWidth
编号(选填)
<ph type="x-smartling-placeholder"></ph> 已弃用使用 innerBounds 或 outerBounds。
窗口的最大宽度。
-
minHeight
编号(选填)
<ph type="x-smartling-placeholder"></ph> 已弃用使用 innerBounds 或 outerBounds。
窗口的最小高度。
-
minWidth
编号(选填)
<ph type="x-smartling-placeholder"></ph> 已弃用使用 innerBounds 或 outerBounds。
窗口的最小宽度。
-
outerBounds
用于指定窗口的初始位置、初始大小和约束条件(包括标题栏和框架等窗口装饰)。如果还指定了
id
,且之前已显示过具有匹配id
的窗口,则系统会改用记住的边界。请注意,内外边界之间的内边距由操作系统决定。因此,为
innerBounds
和outerBounds
设置相同的 bounds 属性会导致错误。这是 Chrome 36 中的新属性。
-
可调整大小
布尔值(可选)
如果为 true,用户将可以调整窗口大小。默认值为 true。
-
showInShelf
布尔值(可选)
Chrome 54 及更高版本如果为 true,该窗口将有自己的任务栏图标。否则,该窗口会与与应用相关联的其他窗口归入此任务栏。默认值为 false。如果 showInShelf 设置为 true,则需要为窗口指定 ID。
-
单例
布尔值(可选)
<ph type="x-smartling-placeholder"></ph> 已弃用不再支持具有相同 ID 的多个窗口。
默认情况下,如果您为窗口指定了 ID,则仅当不存在具有相同 ID 的其他窗口时,系统才会创建该窗口。如果已存在具有相同 ID 的窗口,则将改为激活该窗口。如果您要创建具有相同 ID 的多个窗口,可以将此属性设置为 false。
-
州
州/省级行政区(可选)
窗口的初始状态,允许创建时已全屏、最大化或最小化窗口。默认值为“normal”。
-
类型
WindowType 选填
Chrome 45 及更高版本 自 Chrome 69 起弃用所有应用窗口都使用“shell”窗口类型
要创建的窗口类型。
-
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”
“全屏”
"maximized"
"最小化"
WindowType
指定要创建的窗口类型。
枚举
"shell"
默认窗口类型。
"panel"
操作系统管理窗口(已弃用)。
方法
canSetVisibleOnAllWorkspaces()
chrome.app.window.canSetVisibleOnAllWorkspaces()
当前平台是否支持在所有工作区中显示窗口。
返回
-
布尔值
create()
chrome.app.window.create(
url: string,
options?: CreateWindowOptions,
callback?: function,
)
可以通过多种不同的方式指定窗口的大小和位置。最简单的方式是不指定任何内容,在这种情况下,系统将使用默认尺寸和依赖于平台的位置。
如需设置窗口的位置、大小和约束条件,请使用 innerBounds
或 outerBounds
属性。内部边界不包括窗口装饰。外边界包括窗口的标题栏和框架。请注意,内外边界之间的内边距由操作系统决定。因此,如果同时为内边界和外边界设置相同的属性,则会被视为错误(例如,同时设置 innerBounds.left
和 outerBounds.left
)。
如需自动记住窗口的位置,您可以为其指定 ID。如果某个窗口具有 ID,每当该窗口被移动或调整大小时,该 ID 将用于记住该窗口的大小和位置。然后,在具有相同 ID 的窗口后续打开时,将使用此大小和位置,而不是指定边界。如果您需要在记忆的默认位置以外的位置打开一个具有 ID 的窗口,则可以将其隐藏,然后将其移至所需位置,然后显示该窗口。
参数
-
网址
字符串
-
选项
-
callback
函数(可选)
callback
参数如下所示:(createdWindow: AppWindow) => void
-
createdWindow
-
返回
-
Promise<AppWindow>
Chrome 117 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
current()
chrome.app.window.current()
返回当前脚本上下文的 AppWindow
对象(即 JavaScript“window”对象)。也可在另一个页面的脚本上下文句柄上调用此方法,例如: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 中是新功能。
返回
事件
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