chrome.app.window

说明

使用 chrome.app.window API 创建窗口。Windows 还提供包含标题栏和大小控件的可选框架。它们不会与任何 Chrome 浏览器窗口相关联。如需查看这些选项的演示，请参阅窗口状态示例。

类型

AppWindow

属性

• contentWindow

  窗口

  所创建子项的 JavaScript“window”对象。

• id

  string

  创建窗口时使用的 ID。

• innerBounds

  边界

  窗口内容的位置、尺寸和约束条件，不包括窗口装饰。此属性是 Chrome 36 中的新增属性。

• outerBounds

  边界

  窗口的位置、大小和约束条件，其中包括标题栏和框架等窗口装饰。此属性是 Chrome 36 中的新增属性。

• clearAttention

  void

  明确注意窗口。

  clearAttention 函数如下所示：

  ()=> {...}

• 关闭

  void

  关闭窗口。

  close 函数如下所示：

  ()=> {...}

• drawAttention

  void

  注意窗口。

  drawAttention 函数如下所示：

  ()=> {...}

• 焦点

  void

  将焦点置于窗口。

  focus 函数如下所示：

  ()=> {...}

• 全屏

  void

  全屏显示窗口。

  用户可以通过按 Esc 键恢复窗口。应用可以通过在 keydown 和 keyup 处理程序中请求 app.window.fullscreen.overrideEsc 权限并通过调用 .preventDefault() 取消事件来阻止在按下 ESC 时退出全屏状态，如下所示：

  window.onkeydown = window.onkeyup = function(e) { if (e.keyCode == 27 /* ESC *\/) { e.preventDefault(); } };

  请注意，window.fullscreen() 会使整个窗口变为全屏模式，不需要用户手势。HTML5 Fullscreen API 也可用于进入全屏模式（如需了解详情，请参阅 Web API）。

  fullscreen 函数如下所示：

  ()=> {...}

• getBounds

  void

  已废弃

  使用 innerBounds 或 outerBounds。

  以 ContentBounds 对象的形式获取窗口的内边界。

  getBounds 函数如下所示：

  ()=> {...}

  • 返回

    ContentBounds

• 隐藏

  void

  隐藏窗口。如果窗口已隐藏，则不执行任何操作。

  hide 函数如下所示：

  ()=> {...}

• isAlwaysOnTop

  void

  窗口是否始终位于顶部？

  isAlwaysOnTop 函数如下所示：

  ()=> {...}

  • 返回

    boolean

• isFullscreen

  void

  窗口会全屏显示吗？如果窗口是全屏创建的，或通过 AppWindow 或 HTML5 全屏 API 设置为全屏，则此属性为 true。

  isFullscreen 函数如下所示：

  ()=> {...}

  • 返回

    boolean

• isMaximized

  void

  窗口是否已最大化？

  isMaximized 函数如下所示：

  ()=> {...}

  • 返回

    boolean

• isMinimized

  void

  窗口是否已最小化？

  isMinimized 函数如下所示：

  ()=> {...}

  • 返回

    boolean

• 最大化

  void

  最大化窗口。

  maximize 函数如下所示：

  ()=> {...}

• 最小化

  void

  最小化窗口。

  minimize 函数如下所示：

  ()=> {...}

• moveTo

  void

  从 Chrome 43 开始已废弃

  使用 outerBounds。

  将窗口移至位置（left、top）。

  moveTo 函数如下所示：

  (left: number,top: number)=> {...}

  • 左

    number

  • 上

    number

• resizeTo

  void

  从 Chrome 43 开始已废弃

  使用 outerBounds。

  将窗口大小调整为 widthxheight 像素。

  resizeTo 函数如下所示：

  (width: number,height: number)=> {...}

  • 宽度

    number

  • 高度

    number

• 恢复

  void

  恢复窗口，退出最大化、最小化或全屏状态。

  restore 函数如下所示：

  ()=> {...}

• setAlwaysOnTop

  void

  设置该窗口是否应位于大多数其他窗口之上。需要 alwaysOnTopWindows 权限。

  setAlwaysOnTop 函数如下所示：

  (alwaysOnTop: boolean)=> {...}

  • alwaysOnTop

    boolean

• setBounds

  void

  已废弃

  使用 innerBounds 或 outerBounds。

  设置窗口的内边界。

  setBounds 函数如下所示：

  (bounds: ContentBounds)=> {...}

  • bounds

    ContentBounds

• setVisibleOnAllWorkspaces

  void

  设置窗口是否在所有工作区中都可见。（仅适用于支持此功能的平台）。

  setVisibleOnAllWorkspaces 函数如下所示：

  (alwaysVisible: boolean)=> {...}

  • alwaysVisible

    boolean

• 显示

  void

  显示窗口。如果窗口已经显示，则不执行任何操作。如果 focused 设置为 true 或省略，则聚焦窗口。

  show 函数如下所示：

  (focused?: boolean)=> {...}

  • 专注

    布尔值 选填

Bounds

属性

• 高度

  number

  此属性可用于读取或写入内容或窗口的当前高度。

• 左

  number

  此属性可用于读取或写入内容或窗口的当前 X 坐标。

• maxHeight

  数字可选

  此属性可用于读取或写入内容或窗口的当前最大高度。值 null 表示“未指定”。

• maxWidth

  数字可选

  此属性可用于读取或写入内容或窗口的当前最大宽度。值 null 表示“未指定”。

• minHeight

  数字可选

  此属性可用于读取或写入内容或窗口的当前最小高度。值 null 表示“未指定”。

• minWidth

  数字可选

  此属性可用于读取或写入内容或窗口的当前最小宽度。值 null 表示“未指定”。

• 上

  number

  此属性可用于读取或写入内容或窗口的当前 Y 坐标。

• 宽度

  number

  此属性可用于读取或写入内容或窗口的当前宽度。

• setMaximumSize

  void

  设置内容或窗口的最大尺寸限制。您可以将最大宽度或高度设置为 null，以移除约束条件。值为 undefined 会使约束保持不变。

  setMaximumSize 函数如下所示：

  (maxWidth: number,maxHeight: number)=> {...}

  • maxWidth

    number

  • maxHeight

    number

• setMinimumSize

  void

  设置内容或窗口的最小尺寸限制。可以将最小宽度或高度设置为 null 来移除约束条件。值为 undefined 会使约束保持不变。

  setMinimumSize 函数如下所示：

  (minWidth: number,minHeight: number)=> {...}

  • minWidth

    number

  • minHeight

    number

• setPosition

  void

  设置内容或窗口的左侧和顶部位置。

  setPosition 函数如下所示：

  (left: number,top: number)=> {...}

  • 左

    number

  • 上

    number

• setSize

  void

  设置内容或窗口的宽度和高度。

  setSize 函数如下所示：

  (width: number,height: number)=> {...}

  • 宽度

    number

  • 高度

    number

BoundsSpecification

属性

• 高度

  数字可选

  内容或窗口的高度。

• 左

  数字可选

  内容或窗口的 X 坐标。

• maxHeight

  数字可选

  内容或窗口的最大高度。

• maxWidth

  数字可选

  内容或窗口的最大宽度。

• minHeight

  数字可选

  内容或窗口的最小高度。

• minWidth

  数字可选

  内容或窗口的最小宽度。

• 上

  数字可选

  内容或窗口的 Y 坐标。

• 宽度

  数字可选

  内容或窗口的宽度。

ContentBounds

属性

• 高度

  数字可选

• 左

  数字可选

• 上

  数字可选

• 宽度

  数字可选

CreateWindowOptions

属性

• alwaysOnTop

  布尔值 选填

  如果为 true，该窗口将始终位于大多数其他窗口之上。如果存在多个此类窗口，当前聚焦的窗口将位于前台。需要 alwaysOnTopWindows 权限。默认值为 false。

  创建后，对窗口调用 setAlwaysOnTop() 来更改此属性。

• bounds

  ContentBounds（可选）

  已废弃

  使用 innerBounds 或 outerBounds。

  窗口中内容（不包括标题栏）的大小和位置。如果还指定了 ID，且之前显示过具有匹配 ID 的窗口，则改用记住的窗口边界。

• 专注

  布尔值 选填

  如果为 true，则在创建窗口时获得焦点。默认值为 true。

• 帧

  string|FrameOptions 可选

  帧类型：none 或 chrome（默认为 chrome）。对于 none，-webkit-app-region CSS 属性可用于将可拖动性应用于应用的窗口。-webkit-app-region: drag 可用于将区域标记为可拖动。no-drag 可用于对嵌套元素停用此样式。

  M36 中新增了 FrameOptions 的使用。

• 已隐藏

  布尔值 选填

  如果为 true，则创建窗口时将处于隐藏状态。在创建窗口后，对窗口调用 show() 以显示它。默认值为 false。

• 图标

  字符串（可选）

  Chrome 54 及更高版本

  窗口图标的网址。当 showInShelf 设置为 true 时，窗口可以有自己的图标。此网址应为全局网址或本地扩展网址。

• id

  字符串（可选）

  用于标识窗口的 ID。它将用于记住窗口的大小和位置，并在稍后打开具有相同 ID 的窗口时恢复该几何图形。如果创建了具有指定 ID 的窗口，而已存在具有相同 ID 的另一个窗口，则系统会聚焦当前打开的窗口，而不是创建一个新窗口。

• innerBounds

  BoundsSpecification 可选

  用于指定窗口内容（不包括窗口装饰）的初始位置、初始尺寸和约束条件。如果还指定了 id，并且之前已显示包含匹配 id 的窗口，则系统会改为使用记住的边界。

  请注意，内边界和外边界之间的内边距由操作系统决定。因此，为 innerBounds 和 outerBounds 设置相同的边界属性会导致错误。

  此属性是 Chrome 36 中的新增属性。

• maxHeight

  数字可选

  已废弃

  使用 innerBounds 或 outerBounds。

  窗口的最大高度。

• maxWidth

  数字可选

  已废弃

  使用 innerBounds 或 outerBounds。

  窗口的最大宽度。

• minHeight

  数字可选

  已废弃

  使用 innerBounds 或 outerBounds。

  窗口的最小高度。

• minWidth

  数字可选

  已废弃

  使用 innerBounds 或 outerBounds。

  窗口的最小宽度。

• outerBounds

  BoundsSpecification 可选

  用于指定窗口的初始位置、初始尺寸和约束条件（包括标题栏和框架等窗口装饰）。如果还指定了 id，并且之前已显示包含匹配 id 的窗口，则系统会改为使用记住的边界。

  请注意，内边界和外边界之间的内边距由操作系统决定。因此，为 innerBounds 和 outerBounds 设置相同的边界属性会导致错误。

  此属性是 Chrome 36 中的新增属性。

• resizable

  布尔值 选填

  如果为 true，用户将可调整窗口大小。默认值为 true。

• showInShelf

  布尔值 选填

  Chrome 54 及更高版本

  如果为 true，则窗口将有自己的任务栏图标。否则，此窗口会与应用所关联的其他窗口一起显示在任务栏中。默认值为 false。如果 showInShelf 设置为 true，则需要为窗口指定 ID。

• 单例

  布尔值 选填

  已废弃

  不再支持具有相同 ID 的多个窗口。

  默认情况下，如果您为窗口指定 ID，则只有在不存在具有相同 ID 的其他窗口时才会创建窗口。如果已存在具有相同 ID 的窗口，则会激活该窗口。如果您想创建多个具有相同 ID 的窗口，可以将此属性设为 false。

• state

  状态（可选）

  窗口的初始状态，在创建时允许其处于全屏模式、最大化或最小化状态。默认值为“normal”。

• 类型

  WindowType（可选）

  Chrome 45 及更高版本 从 Chrome 69 开始已弃用

  所有应用窗口都使用“shell”窗口类型

  要创建的窗口类型。

• visibleOnAllWorkspaces

  布尔值 选填

  如果为 true，并且受平台支持，则该窗口在所有工作区中均可见。

FrameOptions

属性

• activeColor

  字符串（可选）

  允许设置窗口处于活动状态时的框架颜色。仅当帧类型为 chrome 时，才可以为帧着色。

  仅当帧类型为 chrome 时，才可以为帧着色。

  框架着色功能是 Chrome 36 的新功能。

• 颜色

  字符串（可选）

  允许设置框架颜色。仅当帧类型为 chrome 时，才可以为帧着色。

  框架着色功能是 Chrome 36 的新功能。

• inactiveColor

  字符串（可选）

  允许将窗口非活动状态的框架颜色设置为与活动状态不同。仅当帧类型为 chrome 时，才可以为帧着色。

  inactiveColor 必须与 color 结合使用。

  框架着色功能是 Chrome 36 的新功能。

• 类型

  字符串（可选）

  帧类型：none 或 chrome（默认为 chrome）。

  对于 none，可以使用 -webkit-app-region CSS 属性将可拖动性应用于应用的窗口。

  -webkit-app-region: drag 可用于将区域标记为可拖动。no-drag 可用于对嵌套元素停用此样式。

State

窗口状态：正常、全屏、最大化、最小化。

枚举

"normal"

"maximized"

WindowType

Chrome 45 及更高版本

指定要创建的窗口类型。

枚举

"shell"
默认窗口类型。

"panel"
操作系统管理的窗口（已弃用）。

方法

canSetVisibleOnAllWorkspaces()

chrome.app.window.canSetVisibleOnAllWorkspaces()

当前平台是否支持窗口在所有工作区中可见。

返回

• boolean

create()

Promise

chrome.app.window.create(
  url: string,
  options?: CreateWindowOptions,
  callback?: function,
)

窗口的尺寸和位置可通过多种不同的方式指定。最简单的选项是不指定任何内容，在这种情况下，系统将使用默认尺寸和依赖于平台的位置。

如需设置窗口的位置、大小和约束条件，请使用 innerBounds 或 outerBounds 属性。内边界不包括窗口装饰。外边界包括窗口的标题栏和框架。请注意，内边界和外边界之间的内边距由操作系统决定。因此，为内边界和外边界设置相同的属性会被视为错误（例如，同时设置 innerBounds.left 和 outerBounds.left）。

为了自动记住窗口的位置，您可以为它们提供 ID。如果窗口具有 ID，则此 ID 用于记住窗口在移动或调整大小时的尺寸和位置。然后，在随后打开具有相同 ID 的窗口时会使用此尺寸和位置，而不是指定的边界。如果您需要在系统记住的默认位置以外的位置打开具有 ID 的窗口，则可以将该窗口创建为隐藏状态，将其移至所需位置，然后显示它。

参数

• 网址

  string

• 选项

  CreateWindowOptions 可选

• callback

  函数（可选）

  callback 参数如下所示：

  (createdWindow: AppWindow)=>void

  • createdWindow

    AppWindow

返回

• Promise<AppWindow>

  Chrome 117 及更高版本

  只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。

current()

chrome.app.window.current()

返回当前脚本上下文（即 JavaScript“窗口”对象）的 AppWindow 对象。您也可以在其他网页的脚本上下文（例如：otherWindow.chrome.app.window.current()）的句柄上调用此方法。

返回

• AppWindow|未定义

get()

chrome.app.window.get(
  id: string,
)

获取具有指定 ID 的 AppWindow。如果不存在具有指定 ID 的窗口，则返回 null。这是 Chrome 33 中的新功能。

参数

• id

  string

返回

• AppWindow|未定义

getAll()

chrome.app.window.getAll()

获取当前创建的所有应用窗口的数组。这是 Chrome 33 中的新功能。

返回

• AppWindow[]

活动

onBoundsChanged

chrome.app.window.onBoundsChanged.addListener(
  callback: function,
)

在调整窗口大小时触发。

参数

• callback

  功能

  callback 参数如下所示：

  ()=>void

onClosed

chrome.app.window.onClosed.addListener(
  callback: function,
)

在窗口关闭时触发。请注意，应在关闭窗口以外的窗口中监听，例如从后台页面中监听。这是因为，在事件触发时，正在关闭的窗口会处于关闭过程中，这意味着窗口脚本上下文中的所有 API 都无法正常运作。

参数

• callback

  功能

  callback 参数如下所示：

  ()=>void

onFullscreened

chrome.app.window.onFullscreened.addListener(
  callback: function,
)

在窗口处于全屏模式（通过 AppWindow 或 HTML5 API）时触发。

参数

• callback

  功能

  callback 参数如下所示：

  ()=>void

onMaximized

chrome.app.window.onMaximized.addListener(
  callback: function,
)

在窗口最大化时触发。

参数

• callback

  功能

  callback 参数如下所示：

  ()=>void

onMinimized

chrome.app.window.onMinimized.addListener(
  callback: function,
)

在窗口最小化时触发。

参数

• callback

  功能

  callback 参数如下所示：

  ()=>void

onRestored

chrome.app.window.onRestored.addListener(
  callback: function,
)

在窗口恢复为最小化或最大化状态时触发。

参数

• callback

  功能

  callback 参数如下所示：

  ()=>void