refresh date: 2026-09-25 robots: noindex
说明
使用 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 示例。
类型
CreateType
指定要创建的浏览器窗口类型。“panel”已弃用，仅适用于 ChromeOS 上已列入许可名单的现有扩展程序。
枚举
"normal"
将窗口指定为标准窗口。
“popup”
将窗口指定为弹出式窗口。
“面板”
将窗口指定为面板。
QueryOptions
属性
-
populate
布尔值 （可选）
如果为 true，则
windows.Window对象具有tabs属性，其中包含tabs.Tab对象列表。仅当扩展程序的清单文件包含"tabs"权限时，Tab对象才包含url、pendingUrl、title和favIconUrl属性。 -
windowTypes
WindowType[] 可选
如果设置，则返回的
windows.Window会根据其类型进行过滤。如果未设置，则默认过滤条件设置为['normal', 'popup']。
Window
属性
-
alwaysOnTop
布尔值
窗口是否设置为始终置顶。
-
专注
布尔值
窗口当前是否为聚焦窗口。
-
高度
number 可选
窗口的高度（包括边框），以像素为单位。在某些情况下，窗口可能未分配
height属性；例如，当通过sessionsAPI 查询已关闭的窗口时。 -
id
number 可选
窗口的 ID。窗口 ID 在浏览器会话中是唯一的。在某些情况下，窗口可能未分配
ID属性；例如，当使用sessionsAPI 查询窗口时，在这种情况下，可能会存在会话 ID。 -
无痕模式
布尔值
窗口是否为无痕式窗口。
-
向左
number 可选
窗口与屏幕左边缘的偏移量（以像素为单位）。在某些情况下，窗口可能未分配
left属性；例如，当通过sessionsAPI 查询已关闭的窗口时。 -
sessionId
字符串 可选
用于唯一标识窗口的会话 ID，通过
sessionsAPI 获取。 -
州
WindowState 可选
相应浏览器窗口的状态。
-
标签页
标签页 [] 可选
表示窗口中当前标签页的
tabs.Tab对象数组。 -
顶部
number 可选
窗口与屏幕顶部边缘的偏移量（以像素为单位）。在某些情况下，窗口可能未分配
top属性；例如，当通过sessionsAPI 查询已关闭的窗口时。 -
类型
WindowType 可选
相应浏览器窗口的类型。
-
width
number 可选
窗口的宽度（包括框架），以像素为单位。在某些情况下，窗口可能未分配
width属性；例如，当通过sessionsAPI 查询已关闭的窗口时。
枚举
"normal"
正常窗口状态（未最小化、最大化或全屏）。
“最小化”
最小化窗口状态。
“最大化”
最大化窗口状态。
"fullscreen"
全屏窗口状态。
枚举
“normal”
一个普通的浏览器窗口。
"popup"
浏览器弹出式窗口。
“panel”
此 API 中已弃用。Chrome 应用面板样式的窗口。扩展程序只能看到自己的面板窗口。
“app”
此 API 中已弃用。Chrome 应用窗口。扩展程序只能看到自己的应用窗口。
“devtools”
开发者工具窗口。
属性
方法
create()
chrome.windows.create(
createData?: object,
callback?: function,
): Promise<Window | undefined>
创建（打开）一个新浏览器窗口，其中包含提供的任何可选尺寸、位置或默认网址。
参数
-
createData
对象（可选）
-
专注
布尔值 （可选）
如果值为
true，则打开一个活动窗口。如果值为false，则打开一个闲置窗口。 -
高度
number 可选
新窗口的高度（以像素为单位），包括框架。如果未指定，则默认为自然高度。
-
无痕模式
布尔值 （可选）
新窗口是否应为无痕式窗口。
-
向左
number 可选
新窗口与屏幕左边缘之间的像素数。如果未指定，新窗口会自然地从上次聚焦的窗口偏移。对于面板，系统会忽略此值。
-
setSelfAsOpener
布尔值 （可选）
Chrome 64 及更高版本如果值为
true，则新创建的窗口的“window.opener”会设置为调用方，并且与调用方位于同一相关浏览上下文单元中。 -
州
WindowState 可选
Chrome 44 及更高版本窗口的初始状态。
minimized、maximized和fullscreen状态不能与left、top、width或height状态组合使用。 -
tabId
number 可选
要添加到新窗口的标签页的 ID。
-
顶部
number 可选
新窗口与屏幕顶部边缘之间的像素数。如果未指定，新窗口会自然地从上次聚焦的窗口偏移。对于面板，系统会忽略此值。
-
类型
CreateType 可选
指定要创建的浏览器窗口类型。
-
网址
字符串 | 字符串数组 可选
要在窗口中作为标签页打开的网址或网址数组。完全限定的网址必须包含架构，例如“http://www.google.com”，而不是“www.google.com”。非完全限定网址会被视为扩展程序中的相对网址。默认为“新标签页”。
-
width
number 可选
新窗口的宽度（以像素为单位），包括框架。如果未指定，则默认为自然宽度。
-
-
callback
函数 可选
callback参数如下所示：(window?: Window) => void
-
窗口
窗口（可选）
包含有关所创建窗口的详细信息。
-
返回
-
Promise<Window | undefined>
Chrome 88 及更高版本仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
get()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
): Promise<Window>
获取有关窗口的详细信息。
参数
-
windowId
数值
-
queryOptions
QueryOptions 可选
Chrome 88 及更高版本 -
callback
函数 可选
callback参数如下所示：(window: Window) => void
-
窗口
-
返回
-
Promise<Window>
Chrome 88 及更高版本仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
getAll()
chrome.windows.getAll(
queryOptions?: QueryOptions,
callback?: function,
): Promise<Window[]>
获取所有窗口。
参数
-
queryOptions
QueryOptions 可选
Chrome 88 及更高版本 -
callback
函数 可选
callback参数如下所示：(windows: Window[]) => void
-
窗户
窗口 []
-
返回
-
Promise<Window[]>
Chrome 88 及更高版本仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
getCurrent()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
): Promise<Window>
获取当前窗口。
参数
-
queryOptions
QueryOptions 可选
Chrome 88 及更高版本 -
callback
函数 可选
callback参数如下所示：(window: Window) => void
-
窗口
-
返回
-
Promise<Window>
Chrome 88 及更高版本仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
getLastFocused()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
): Promise<Window>
获取最近聚焦的窗口，通常是“最上层”的窗口。
参数
-
queryOptions
QueryOptions 可选
Chrome 88 及更高版本 -
callback
函数 可选
callback参数如下所示：(window: Window) => void
-
窗口
-
返回
-
Promise<Window>
Chrome 88 及更高版本仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
remove()
chrome.windows.remove(
windowId: number,
callback?: function,
): Promise<void>
移除（关闭）窗口及其中的所有标签页。
参数
-
windowId
数值
-
callback
函数 可选
callback参数如下所示：() => void
返回
-
Promise<void>
Chrome 88 及更高版本仅 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
update()
chrome.windows.update(
windowId: number,
updateInfo: object,
callback?: function,
): Promise<Window>
更新窗口的属性。仅指定要更改的属性；未指定的属性保持不变。
参数
-
windowId
数值
-
updateInfo
对象
-
drawAttention
布尔值 （可选）
如果值为
true，则以吸引用户注意的方式显示窗口，而不更改聚焦窗口。此效果会一直持续，直到用户将焦点移至相应窗口。如果窗口已获得焦点，此选项不会产生任何效果。设置为false可取消之前的drawAttention请求。 -
专注
布尔值 （可选）
如果值为
true，则将窗口置于前台；不能与“最小化”状态组合使用。如果值为false，则将 z 顺序中的下一个窗口置于最前面；不能与“全屏”或“最大化”状态组合使用。 -
高度
number 可选
要将窗口调整到的高度（以像素为单位）。对于面板，系统会忽略此值。
-
向左
number 可选
从屏幕左边缘到要将窗口移动到的位置的偏移量（以像素为单位）。对于面板，系统会忽略此值。
-
州
WindowState 可选
窗口的新状态。“minimized”“maximized”和“fullscreen”状态不能与“left”“top”“width”或“height”结合使用。
-
顶部
number 可选
从屏幕顶部边缘到要将窗口移动到的位置的偏移量（以像素为单位）。对于面板，系统会忽略此值。
-
width
number 可选
窗口调整后的宽度（以像素为单位）。对于面板，系统会忽略此值。
-
-
callback
函数 可选
callback参数如下所示：(window: Window) => void
-
窗口
-
返回
-
Promise<Window>
Chrome 88 及更高版本仅 Manifest V3 及更高版本支持 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 窗口管理器中，WINDOW_ID_NONE 始终在从一个 Chrome 窗口切换到另一个 Chrome 窗口之前立即发送。
参数
-
callback
函数
Chrome 46 及更高版本callback参数如下所示：(windowId: number) => void
-
windowId
数值
新聚焦窗口的 ID。
-
-
过滤器
对象（可选）
-
windowTypes
要移除的窗口类型必须满足的条件。默认情况下，它满足
['normal', 'popup']。
-
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
在窗口被移除（关闭）时触发。
参数
-
callback
函数
Chrome 46 及更高版本callback参数如下所示：(windowId: number) => void
-
windowId
数值
已移除窗口的 ID。
-
-
过滤器
对象（可选）
-
windowTypes
要移除的窗口类型必须满足的条件。默认情况下，它满足
['normal', 'popup']。
-