chrome.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 及更高版本

指定要创建的浏览器窗口类型。“panel”已被弃用，仅适用于 Chrome 操作系统中已列入许可名单的现有扩展程序。

枚举

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

"popup"
将窗口指定为弹出式窗口。

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

QueryOptions

Chrome 88 及更高版本

属性

• 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 查询关闭的窗口时。

WindowState

Chrome 44 及更高版本

此浏览器窗口的状态。在某些情况下，系统可能不会为窗口分配 state 属性；例如，通过 sessions API 查询关闭的窗口时。

枚举

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

"minimized"
最小化窗口状态。

"maximized"
最大化窗口状态。

"fullscreen"
全屏窗口状态。

"locked-fullscreen"
锁定的全屏窗口状态。这种全屏状态无法通过用户操作退出，并且仅适用于 Chrome 操作系统中列入许可名单的扩展程序。

WindowType

Chrome 44 及更高版本

浏览器窗口的类型。在某些情况下，系统可能不会为窗口分配 type 属性；例如，通过 sessions API 查询关闭的窗口时。

枚举

"normal"
一个普通的浏览器窗口。

"popup"
浏览器弹出窗口。

"panel"
在此 API 中已废弃。Chrome 应用面板式窗口。扩展程序只能查看自己的面板窗口。

"app"
在此 API 中已废弃。Chrome 应用窗口。扩展程序只能查看自身的应用窗口。

"devtools"
开发者工具窗口。

属性

WINDOW_ID_CURRENT

表示当前窗口的 windowId 值。

值

-2

WINDOW_ID_NONE

windowId 值，表示不存在 Chrome 浏览器窗口。

值

-1

方法

create()

Promise

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[] optional

    要在窗口中作为标签页打开的网址或网址数组。完全限定网址必须包含架构，例如“http://www.google.com”，而不是“www.google.com”。非完全限定的网址在扩展程序中会被视为相对网址。默认为“新标签页”。

  • 宽度

    数字可选

    新窗口的宽度（以像素为单位），包括框架。如果未指定，则默认为自然宽度。

• callback

  函数（可选）

  callback 参数如下所示：

  (window?: Window)=>void

  • 窗口

    窗口（可选）

    包含所创建窗口的详细信息。

返回

• Promise<窗口|未定义>

  Chrome 88 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

get()

Promise

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 使用传递给回调函数的同一类型进行解析。

getAll()

Promise

chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
)

获取所有窗口。

参数

• queryOptions

  QueryOptions 可选

  Chrome 88 及更高版本
• callback

  函数（可选）

  callback 参数如下所示：

  (windows: Window[])=>void

  • 窗户

    窗户[]

返回

• Promise<Window[]>

  Chrome 88 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

getCurrent()

Promise

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()

Promise

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()

Promise

chrome.windows.remove(
  windowId: number,
  callback?: function,
)

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

参数

• windowId

  number

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 88 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

update()

Promise

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 86 及更高版本

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

调整窗口大小时触发；此事件仅在提交新边界时分派，而不会针对正在进行的更改分派。

参数

• callback

  功能

  callback 参数如下所示：

  (window: Window)=>void

  • 窗口

    窗户

onCreated

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

创建窗口时触发。

参数

• callback

  功能

  Chrome 46 及更高版本

  callback 参数如下所示：

  (window: Window)=>void

  • 窗口

    窗户

    所创建窗口的详细信息。

• 过滤条件

  对象（可选）

  • windowTypes

    WindowType[]

    要创建的窗口类型必须满足的条件。默认情况下，它满足 ['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

    WindowType[]

    要移除的窗口类型必须满足的条件。默认情况下，它满足 ['normal', 'popup']。

onRemoved

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

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

参数

• callback

  功能

  Chrome 46 及更高版本

  callback 参数如下所示：

  (windowId: number)=>void

  • windowId

    number

    已移除的窗口的 ID。

• 过滤条件

  对象（可选）

  • windowTypes

    WindowType[]

    要移除的窗口类型必须满足的条件。默认情况下，它满足 ['normal', 'popup']。