说明
使用 chrome.windows
API 与浏览器窗口交互。您可以使用此 API 在浏览器中创建、修改和重新排列窗口。
权限
请求时,windows.Window
包含 tabs.Tab
对象的数组。如果您需要访问 tabs.Tab
的 url
、pendingUrl
、title
或 favIconUrl
属性,您必须在清单中声明 "tabs"
权限。例如:
{
"name": "My extension",
...
"permissions": ["tabs"],
...
}
概念和用法
当前窗口
扩展系统中的许多函数都接受可选的 windowId
参数,该参数默认为当前窗口。
当前窗口是包含当前正在执行的代码的窗口。请务必注意,此窗口可能与最顶层或聚焦的窗口不同。
例如,假设某个扩展程序基于单个 HTML 文件创建了几个标签页或窗口,并且该 HTML 文件中包含对 tabs.query()
的调用。当前窗口是包含调用页面的窗口,无论最顶部的窗口是什么。
对于 Service Worker,当前窗口的值会回退到上一个活跃窗口。在某些情况下,后台网页可能没有当前窗口。
示例
若要试用此 API,请从 chrome-extension-samples 代码库安装 Windows API 示例。
![两个窗口,每个窗口有一个标签页](https://developer.chrome.google.cn/static/docs/extensions/reference/api/windows/images/windows.png?authuser=8&hl=hu)
类型
CreateType
指定要创建的浏览器窗口类型。“panel”已被弃用,仅适用于 Chrome 操作系统中已列入许可名单的现有扩展程序。
枚举
"normal"
将窗口指定为标准窗口。
"popup"
将窗口指定为弹出式窗口。
"panel"
将窗口指定为面板。
QueryOptions
属性
-
populate
布尔值 选填
如果为 true,则
windows.Window
对象会有一个tabs
属性,其中包含tabs.Tab
对象的列表。如果扩展程序的清单文件包含"tabs"
权限,则Tab
对象仅包含url
、pendingUrl
、title
和favIconUrl
属性。 -
windowTypes
WindowType[] 可选
如果设置了此字段,则返回的
windows.Window
会根据其类型进行过滤。如果未设置,则默认过滤条件会设置为['normal', 'popup']
。
Window
属性
-
alwaysOnTop
boolean
窗口是否设置为始终位于顶部。
-
专注
boolean
窗口当前是否是聚焦窗口。
-
高度
数字可选
窗口的高度(包括框架),以像素为单位。在某些情况下,系统可能不会为窗口分配
height
属性;例如,通过sessions
API 查询关闭的窗口时。 -
id
数字可选
窗口的 ID。窗口 ID 在浏览器会话中是唯一的。在某些情况下,系统可能不会为窗口分配
ID
属性;例如,使用sessions
API 查询窗口时,此时可能会出现会话 ID。 -
无痕模式
boolean
窗口是否处于无痕式窗口。
-
剩余
数字可选
窗口与屏幕左边缘的偏移量(以像素为单位)。在某些情况下,系统可能不会为窗口分配
left
属性;例如,通过sessions
API 查询关闭的窗口时。 -
sessionId
字符串(可选)
用于唯一标识窗口的会话 ID,从
sessions
API 获取。 -
state
WindowState(可选)
此浏览器窗口的状态。
-
标签页
Tab[] 可选
一组
tabs.Tab
对象,表示窗口中的当前标签页。 -
上
数字可选
窗口相对于屏幕顶部边缘的偏移量(以像素为单位)。在某些情况下,系统可能不会为窗口分配
top
属性;例如,通过sessions
API 查询关闭的窗口时。 -
类型
WindowType(可选)
表示的浏览器窗口的类型。
-
宽度
数字可选
窗口的宽度(包括框架),以像素为单位。在某些情况下,系统可能不会为窗口分配
width
属性;例如,通过sessions
API 查询关闭的窗口时。
枚举
"normal"
正常窗口状态(非最小化、最大化或全屏)。
"minimized"
最小化窗口状态。
"maximized"
最大化窗口状态。
"fullscreen"
全屏窗口状态。
"locked-fullscreen"
锁定的全屏窗口状态。这种全屏状态无法通过用户操作退出,并且仅适用于 Chrome 操作系统中列入许可名单的扩展程序。
枚举
"normal"
一个普通的浏览器窗口。
"popup"
浏览器弹出窗口。
"panel"
在此 API 中已废弃。Chrome 应用面板式窗口。扩展程序只能查看自己的面板窗口。
"app"
在此 API 中已废弃。Chrome 应用窗口。扩展程序只能查看自身的应用窗口。
"devtools"
开发者工具窗口。
属性
方法
create()
chrome.windows.create(
createData?: object,
callback?: function,
)
创建(打开)一个新的浏览器窗口,其中包含任意尺寸、位置或默认网址(可选)。
参数
-
createData
对象(可选)
-
专注
布尔值 选填
如果为
true
,则会打开一个活动窗口。如果为false
,则会打开一个非活动窗口。 -
高度
数字可选
新窗口(包括框架)的高度(以像素为单位)。如果未指定,则默认为自然高度。
-
无痕模式
布尔值 选填
新窗口是否为无痕式窗口。
-
剩余
数字可选
新窗口距屏幕左边缘的像素数。如果未指定,新窗口将自然偏移于上次聚焦的窗口。对于面板,此值会被忽略。
-
setSelfAsOpener
布尔值 选填
Chrome 64 及更高版本如果为
true
,则新建窗口的“window.opener”会被设置为调用方,并且与调用方位于同一相关浏览上下文单元中。 -
state
WindowState(可选)
Chrome 44 及更高版本窗口的初始状态。
minimized
、maximized
和fullscreen
状态不能与left
、top
、width
或height
结合使用。 -
tabId
数字可选
要添加到新窗口的标签页 ID。
-
上
数字可选
新窗口距屏幕上边缘的像素值。如果未指定,新窗口将自然偏移于上次聚焦的窗口。对于面板,此值会被忽略。
-
类型
CreateType(可选)
指定要创建的浏览器窗口类型。
-
网址
string | string[] 可选
要在窗口中作为标签页打开的网址或网址数组。完全限定网址必须包含架构,例如“http://www.google.com”,而不是“www.google.com”。非完全限定的网址在扩展程序中会被视为相对网址。默认为“新标签页”。
-
宽度
数字可选
新窗口的宽度(以像素为单位),包括框架。如果未指定,则默认为自然宽度。
-
-
callback
函数(可选)
callback
参数如下所示:(window?: Window) => void
-
窗口
窗口(可选)
包含所创建窗口的详细信息。
-
返回
-
Promise<Window | undefined>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
get()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
)
获取窗口的相关详细信息。
参数
-
windowId
number
-
queryOptions
QueryOptions 可选
Chrome 88 及更高版本 -
callback
函数(可选)
callback
参数如下所示:(window: Window) => void
-
窗口
-
返回
-
Promise<Window>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
参数
-
queryOptions
QueryOptions 可选
Chrome 88 及更高版本 -
callback
函数(可选)
callback
参数如下所示:(windows: Window[]) => void
-
窗户
窗户[]
-
返回
-
Promise<Window[]>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getCurrent()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
)
获取当前窗口。
参数
-
queryOptions
QueryOptions 可选
Chrome 88 及更高版本 -
callback
函数(可选)
callback
参数如下所示:(window: Window) => void
-
窗口
-
返回
-
Promise<Window>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
getLastFocused()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
)
获取最近获得焦点的窗口,通常是“位于顶部”的窗口。
参数
-
queryOptions
QueryOptions 可选
Chrome 88 及更高版本 -
callback
函数(可选)
callback
参数如下所示:(window: Window) => void
-
窗口
-
返回
-
Promise<Window>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
remove()
chrome.windows.remove(
windowId: number,
callback?: function,
)
移除(关闭)窗口以及其中的所有标签页。
参数
-
windowId
number
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
update()
chrome.windows.update(
windowId: number,
updateInfo: object,
callback?: function,
)
更新窗口的属性。仅指定要更改的属性;不更改未指定的属性。
参数
-
windowId
number
-
updateInfo
对象
-
drawAttention
布尔值 选填
如果为
true
,则显示窗口的方式不会改变聚焦的窗口,吸引用户注意该窗口。该效果将持续到用户将焦点转到窗口为止。如果窗口已聚焦,则此选项无效。设置为false
可取消之前的drawAttention
请求。 -
专注
布尔值 选填
如果为
true
,则将窗口置于前面;不能与“最小化”状态结合使用。如果为false
,则将按 Z 顺序的下一个窗口置于前面;不能与“全屏”或“最大化”状态结合使用。 -
高度
数字可选
要将窗口大小调整至的高度(以像素为单位)。对于面板,此值会被忽略。
-
剩余
数字可选
要将窗口移至的距离,相对于屏幕左边缘的偏移量(以像素为单位)。对于面板,此值会被忽略。
-
state
WindowState(可选)
窗口的新状态。“minimized”“maximized”和“fullscreen”状态不能与“left”“top”“width”或“height”结合使用。
-
上
数字可选
要将窗口移至的距离,相对于屏幕顶部边缘的偏移量(以像素为单位)。对于面板,此值会被忽略。
-
宽度
数字可选
要将窗口大小调整到的宽度(以像素为单位)。对于面板,此值会被忽略。
-
-
callback
函数(可选)
callback
参数如下所示:(window: Window) => void
-
窗口
-
返回
-
Promise<Window>
Chrome 88 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
活动
onBoundsChanged
chrome.windows.onBoundsChanged.addListener(
callback: function,
)
调整窗口大小时触发;此事件仅在提交新边界时分派,而不会针对正在进行的更改分派。
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
创建窗口时触发。
参数
-
callback
功能
Chrome 46 及更高版本callback
参数如下所示:(window: Window) => void
-
窗口
所创建窗口的详细信息。
-
-
过滤条件
对象(可选)
-
windowTypes
要创建的窗口类型必须满足的条件。默认情况下,它满足
['normal', 'popup']
。
-
onFocusChanged
chrome.windows.onFocusChanged.addListener(
callback: function,
filters?: object,
)
在当前聚焦窗口发生变化时触发。如果所有 Chrome 窗口均已失去焦点,则返回 chrome.windows.WINDOW_ID_NONE
。注意:在某些 Linux 窗口管理器中,系统始终会在从一个 Chrome 窗口切换到另一个 Chrome 窗口之前立即发送 WINDOW_ID_NONE
。
参数
-
callback
功能
Chrome 46 及更高版本callback
参数如下所示:(windowId: number) => void
-
windowId
number
新聚焦窗口的 ID。
-
-
过滤条件
对象(可选)
-
windowTypes
要移除的窗口类型必须满足的条件。默认情况下,它满足
['normal', 'popup']
。
-
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
在移除(关闭)窗口时触发。
参数
-
callback
功能
Chrome 46 及更高版本callback
参数如下所示:(windowId: number) => void
-
windowId
number
已移除的窗口的 ID。
-
-
过滤条件
对象(可选)
-
windowTypes
要移除的窗口类型必须满足的条件。默认情况下,它满足
['normal', 'popup']
。
-