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