Chrome 现在支持标准化的 browser.* 命名空间（自 Chrome 148 起提供）。我们正在逐步更新文档。如需了解详情，请参阅我们的过渡指南。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

browser.windows

说明

使用 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

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

指定要创建的浏览器窗口类型。“panel”已弃用，仅适用于 ChromeOS 上已列入许可清单的现有扩展程序。

枚举

"normal"
将窗口指定为标准窗口。

“popup”
将窗口指定为弹窗。

"panel"
将窗口指定为面板。

QueryOptions

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

属性

populate

布尔值（可选）

如果为 true，则 windows.Window 对象具有一个 tabs 属性，其中包含 tabs.Tab 对象列表。仅当扩展程序的清单文件包含 "tabs" 权限时，Tab 对象才会包含 url、pendingUrl、title 和 favIconUrl 属性。
windowTypes

WindowType[] 可选

如果设置了此参数，系统会根据类型过滤返回的 windows.Window。如果未设置，则默认过滤条件设置为 ['normal', 'popup']。

Window

属性

alwaysOnTop

布尔值

窗口是否设置为始终置顶。
专注

布尔值

窗口当前是否为焦点窗口。
高度

number 可选

窗口的高度（包括边框，以像素为单位）。在某些情况下，窗口可能未分配 height 属性；例如，从 sessions API 查询已关闭的窗口时。
id

number 可选

窗口的 ID。窗口 ID 在浏览器会话中是唯一的。在某些情况下，窗口可能未分配 ID 属性；例如，使用 sessions API 查询窗口时，在这种情况下，可能会存在会话 ID。
无痕模式

布尔值

窗口是否为无痕式窗口。
向左

number 可选

窗口与屏幕左边缘的偏移量（以像素为单位）。在某些情况下，窗口可能未分配 left 属性；例如，从 sessions API 查询已关闭的窗口时。
sessionId

字符串可选

用于唯一标识窗口的会话 ID，从 sessions API 获取。
州

WindowState 可选

此浏览器窗口的状态。
tabs

Tab[] 可选

由表示窗口中当前标签页的 tabs.Tab 对象组成的数组。
顶部

number 可选

窗口与屏幕顶部的偏移量（以像素为单位）。在某些情况下，窗口可能未分配 top 属性；例如，从 sessions API 查询已关闭的窗口时。
类型

WindowType 可选

此浏览器窗口的类型。
width

number 可选

窗口（包括边框）的宽度（以像素为单位）。在某些情况下，窗口可能未分配 width 属性；例如，从 sessions API 查询已关闭的窗口时。

WindowState

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

此浏览器窗口的状态。在某些情况下，窗口可能未分配 state 属性；例如，从 sessions API 查询已关闭的窗口时。

枚举

"normal"
正常窗口状态（未最小化、最大化或全屏）。

"minimized"
最小化窗口状态。

"maximized"
最大化窗口状态。

"fullscreen"
全屏窗口状态。

WindowType

Chrome 44 及更高版本 browser.*（自 Chrome 148 起）

此浏览器窗口的类型。在某些情况下，窗口可能未分配 type 属性；例如，从 sessions API 查询已关闭的窗口时。

枚举

"normal"
普通浏览器窗口。

"popup"
浏览器弹出式窗口。

“panel”
此 API 中已弃用。Chrome 应用面板样式窗口。扩展程序只能看到自己的面板窗口。

“app”
在此 API 中已弃用。Chrome 应用窗口。扩展程序只能看到其应用自己的窗口。

"devtools"
开发者工具窗口。

属性

WINDOW_ID_CURRENT

表示当前窗口的 windowId 值。

值

-2

WINDOW_ID_NONE

表示没有 Chrome 浏览器窗口的 windowId 值。

值

-1

方法

create()

browser.windows.create(
  createData?: object,
): Promise<Window | undefined>

创建（打开）一个新的浏览器窗口，并提供可选的大小、位置或默认网址。

参数

createData

对象（可选）
- 专注
  
  布尔值（可选）
  
  如果为 true，则会打开一个活动窗口。如果为 false，则会打开一个闲置窗口。
- 高度
  
  number 可选
  
  新窗口的高度（以像素为单位），包括边框。如果未指定，则默认为自然高度。
- 无痕模式
  
  布尔值（可选）
  
  新窗口是否应为无痕式窗口。
- 向左
  
  number 可选
  
  新窗口距离屏幕左边缘的像素数。如果未指定，新窗口会自然地从上一个获得焦点的窗口偏移。对于面板，此值会被忽略。
- setSelfAsOpener
  
  布尔值（可选）
  
  Chrome 64 及更高版本 browser.*（自 Chrome 148 起）
  
  如果为 true，则新创建的窗口的“window.opener”会设置为调用方，并且与调用方位于同一相关浏览上下文单元中。
- 州
  
  WindowState 可选
  
  Chrome 44 及更高版本 browser.*（自 Chrome 148 起）
  
  窗口的初始状态。minimized、maximized 和 fullscreen 状态不能与 left、top、width 或 height 结合使用。
- tabId
  
  number 可选
  
  要添加到新窗口的标签页的 ID。
- 顶部
  
  number 可选
  
  新窗口距离屏幕顶部的像素数。如果未指定，新窗口会自然地从上一个获得焦点的窗口偏移。对于面板，此值会被忽略。
- 类型
  
  CreateType 可选
  
  指定要创建的浏览器窗口类型。
- 网址
  
  字符串 | 字符串 [] 可选
  
  要在窗口中作为标签页打开的网址或网址数组。完全限定网址必须包含架构，例如“http://www.google.com”，而不是“www.google.com”。非完全限定网址会被视为扩展程序内的相对网址。默认为“新标签页”页面。
- width
  
  number 可选
  
  新窗口的宽度（以像素为单位），包括边框。如果未指定，则默认为自然宽度。

Promise<Window | undefined>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

get()

browser.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
): Promise<Window>

获取有关窗口的详细信息。

参数

windowId

数值
queryOptions

QueryOptions 可选

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

Promise<Window>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

getAll()

browser.windows.getAll(
  queryOptions?: QueryOptions,
): Promise<Window[]>

获取所有窗口。

参数

queryOptions

QueryOptions 可选

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

Promise<Window[]>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

getCurrent()

browser.windows.getCurrent(
  queryOptions?: QueryOptions,
): Promise<Window>

获取当前窗口。

参数

queryOptions

QueryOptions 可选

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

Promise<Window>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

getLastFocused()

browser.windows.getLastFocused(
  queryOptions?: QueryOptions,
): Promise<Window>

获取最近获得焦点的窗口，通常是“最顶层”的窗口。

参数

queryOptions

QueryOptions 可选

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

Promise<Window>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

remove()

browser.windows.remove(
  windowId: number,
): Promise<void>

移除（关闭）窗口及其中的所有标签页。

参数

windowId

数值

承诺<void>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

update()

browser.windows.update(
  windowId: number,
  updateInfo: object,
): Promise<Window>

更新窗口的属性。仅指定要更改的属性；未指定的属性保持不变。

参数

windowId

数值
updateInfo

对象
- drawAttention
  
  布尔值（可选）
  
  如果为 true，则会导致窗口以吸引用户注意的方式显示，而不会更改焦点窗口。该效果会一直持续，直到用户将焦点切换到该窗口。如果窗口已获得焦点，则此选项无效。设置为 false 可取消之前的 drawAttention 请求。
- 专注
  
  布尔值（可选）
  
  如果为 true，则将窗口置于最前端；不能与“minimized”状态结合使用。如果为 false，则将 Z 轴顺序中的下一个窗口置于最前端；不能与“fullscreen”或“maximized”状态结合使用。
- 高度
  
  number 可选
  
  要将窗口调整到的高度（以像素为单位）。对于面板，此值会被忽略。
- 向左
  
  number 可选
  
  窗口移动到的位置与屏幕左边缘之间的偏移量（以像素为单位）。对于面板，此值会被忽略。
- 州
  
  WindowState 可选
  
  窗口的新状态。“minimized”“maximized”和“fullscreen”状态不能与“left”“top”“width”或“height”结合使用。
- 顶部
  
  number 可选
  
  窗口移动到的位置与屏幕顶部的偏移量（以像素为单位）。对于面板，此值会被忽略。
- width
  
  number 可选
  
  窗口调整后的宽度（以像素为单位）。对于面板，此值会被忽略。

Promise<Window>

Chrome 88 及更高版本 browser.*（自 Chrome 148 起）

事件

onBoundsChanged

Chrome 86 及更高版本 browser.*（自 Chrome 148 起）

browser.windows.onBoundsChanged.addListener(
  callback: function,
)

在窗口大小调整后触发；此事件仅在新边界提交后分派，而不会在更改过程中分派。

参数

callback

函数

callback 参数如下所示：
```
(window: Window) => void
```
- 窗口
  
  窗口

onCreated

browser.windows.onCreated.addListener(
  callback: function,
  filters?: object,
)

在创建窗口时触发。

参数

callback

函数

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

callback 参数如下所示：
```
(window: Window) => void
```
- 窗口
  
  窗口
  
  所创建窗口的详细信息。
过滤器

对象（可选）
- windowTypes
  
  WindowType[]
  
  所创建的窗口类型必须满足的条件。默认情况下，它满足 ['normal', 'popup']。

onFocusChanged

browser.windows.onFocusChanged.addListener(
  callback: function,
  filters?: object,
)

当当前获得焦点的窗口发生变化时触发。如果所有 Chrome 窗口都失去焦点，则返回 chrome.windows.WINDOW_ID_NONE。注意：在某些 Linux 窗口管理器中，WINDOW_ID_NONE 始终会在从一个 Chrome 窗口切换到另一个 Chrome 窗口之前立即发送。

参数

callback

函数

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

callback 参数如下所示：
```
(windowId: number) => void
```
- windowId
  
  数值
  
  新聚焦的窗口的 ID。
过滤器

对象（可选）
- windowTypes
  
  WindowType[]
  
  要移除的窗口类型必须满足的条件。默认情况下，它满足 ['normal', 'popup']。

onRemoved

browser.windows.onRemoved.addListener(
  callback: function,
  filters?: object,
)

在窗口被移除（关闭）时触发。

参数

callback

函数

Chrome 46 及更高版本 browser.*（自 Chrome 148 起）

callback 参数如下所示：
```
(windowId: number) => void
```
- windowId
  
  数值
  
  已移除窗口的 ID。
过滤器

对象（可选）
- windowTypes
  
  WindowType[]
  
  要移除的窗口类型必须满足的条件。默认情况下，它满足 ['normal', 'popup']。

browser.windows 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

说明

权限

概念和用法

当前窗口

示例

类型

CreateType

枚举

QueryOptions

属性

Window

属性

WindowState

枚举

WindowType

枚举

属性

WINDOW_ID_CURRENT

值

WINDOW_ID_NONE

值

方法

create()

参数

返回

get()

参数

返回

getAll()

参数

返回

getCurrent()

参数

返回

getLastFocused()

参数

返回

remove()

参数

返回

update()

参数

返回

事件

onBoundsChanged

参数

onCreated

参数

onFocusChanged

参数

onRemoved

参数

browser.windows