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”已被弃用，仅适用于 ChromeOS 上已列入许可名单的现有扩展程序。

枚举

“normal”
将窗口指定为标准窗口。

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

“面板”
将窗口指定为面板。

QueryOptions

Chrome 88 及更高版本

属性

  • populate

    布尔值（可选）

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

  • windowTypes

    WindowTypeWindowType[] 可选

    如果已设置，则返回的 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 对象数组，表示窗口中的当前标签页。

  • 顶部

    number 可选

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

  • 类型

    WindowType 可选

    相应浏览器窗口的类型。

  • width

    number 可选

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

WindowState

Chrome 44 及更高版本

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

枚举

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

“最小化”
最小化窗口状态。

“最大化”
最大化的窗口状态。

“fullscreen”
全屏窗口状态。

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

WindowType

Chrome 44 及更高版本

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

枚举

“normal”
常规浏览器窗口。

“弹出式窗口”
浏览器弹出式窗口。

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

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

“devtools”
开发者工具窗口。

属性

WINDOW_ID_CURRENT

表示当前窗口的 windowId 值。

值

-2

WINDOW_ID_NONE

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

值

-1

方法

create()

chrome.windows.create(
  createData?: object,
): 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 可选

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

返回

  • Promise<Window | undefined>

    Chrome 88 及更高版本

get()

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

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

参数

  • windowId

    数值

  • queryOptions

    QueryOptions 可选

    Chrome 88 及更高版本

返回

  • Promise<Window>

    Chrome 88 及更高版本

getAll()

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

获取所有窗口。

参数

  • queryOptions

    QueryOptions 可选

    Chrome 88 及更高版本

返回

  • Promise<Window[]>

    Chrome 88 及更高版本

getCurrent()

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

获取当前窗口。

参数

  • queryOptions

    QueryOptions 可选

    Chrome 88 及更高版本

返回

  • Promise<Window>

    Chrome 88 及更高版本

getLastFocused()

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

获取最近聚焦的窗口，通常是“最上层”的窗口。

参数

  • queryOptions

    QueryOptions 可选

    Chrome 88 及更高版本

返回

  • Promise<Window>

    Chrome 88 及更高版本

remove()

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

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

参数

  • windowId

    数值

返回

  • Promise<void>

    Chrome 88 及更高版本

update()

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

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

参数

  • windowId

    数值

  • updateInfo

    对象

    • drawAttention

      布尔值（可选）

      如果值为 true，则会导致窗口以吸引用户注意的方式显示，而不会更改聚焦窗口。此效果会一直持续，直到用户将焦点移至相应窗口。如果窗口已获得焦点，此选项不会产生任何影响。设置为 false 可取消之前的 drawAttention 请求。

    • 专注

      布尔值（可选）

      如果为 true，则将窗口置于前台；不能与“最小化”状态组合使用。如果值为 false，则将 z 顺序中的下一个窗口移到前面；不能与“全屏”或“最大化”状态结合使用。

    • 高度

      number 可选

      要将窗口调整为的高度（以像素为单位）。对于面板，此值会被忽略。

    • 向左

      number 可选

      窗口要移动到的位置与屏幕左边缘的偏移量（以像素为单位）。对于面板，此值会被忽略。

    • 州

      WindowState 可选

      窗口的新状态。“minimized”“maximized”和“fullscreen”状态不能与“left”“top”“width”或“height”结合使用。

    • 顶部

      number 可选

      窗口要移动到的位置与屏幕上边缘的偏移量（以像素为单位）。对于面板，此值会被忽略。

    • width

      number 可选

      要将窗口调整为的宽度（以像素为单位）。对于面板，此值会被忽略。

返回

  • Promise<Window>

    Chrome 88 及更高版本

事件

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 窗口管理器中，WINDOW_ID_NONE 始终在从一个 Chrome 窗口切换到另一个 Chrome 窗口之前立即发送。

参数

  • callback

    函数

    Chrome 46 及更高版本

    callback 参数如下所示： 

    (windowId: number) => void

    • windowId

      数值

      新聚焦窗口的 ID。

  • 过滤器

    对象（可选）

    • windowTypes

      WindowType[]

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

onRemoved

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

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

参数

  • callback

    函数

    Chrome 46 及更高版本

    callback 参数如下所示： 

    (windowId: number) => void

    • windowId

      数值

      已移除窗口的 ID。

  • 过滤器

    对象（可选）

    • windowTypes

      WindowType[]

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