本页面是 Chrome 应用平台文档（已于 2020 年弃用）的一部分。至少在 2025 年 1 月之前，使用 ChromeOS 的企业版和教育版客户仍可使用该功能。详细了解如何迁移应用。

此页面由 Cloud Translation API 翻译。

chrome.app.window

说明

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

类型

AppWindow

属性

contentWindow

窗口

所创建子窗口的 JavaScript“window”对象。
id

字符串

创建窗口时使用的 ID。
innerBounds

边界

窗口内容（不包括窗口装饰）的位置、大小和限制。此属性是 Chrome 36 中的新增属性。
outerBounds

边界

窗口的位置、大小和限制条件，包括窗口装饰（例如标题栏和框架）。此属性是 Chrome 36 中的新增属性。
clearAttention

void

清除对窗口的关注。

clearAttention 函数如下所示：
```
() => {...}
```
关闭

void

关闭窗口。

close 函数如下所示：
```
() => {...}
```
drawAttention

void

吸引对窗口的注意力。

drawAttention 函数如下所示：
```
() => {...}
```
焦点

void

聚焦于窗口。

focus 函数如下所示：
```
() => {...}
```
全屏

void

将窗口全屏显示。

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

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

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

fullscreen 函数如下所示：
```
() => {...}
```
getBounds

void

已弃用

使用 innerBounds 或 outerBounds。
以 ContentBounds 对象的形式获取窗口的内部边界。

getBounds 函数如下所示：
```
() => {...}
```
- 返回
  ContentBounds
隐藏

void

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

hide 函数如下所示：
```
() => {...}
```
isAlwaysOnTop

void

窗口是否始终位于顶部？

isAlwaysOnTop 函数如下所示：
```
() => {...}
```
- 返回
  布尔值
isFullscreen

void

窗口是否处于全屏模式？如果窗口已创建为全屏，或者通过 AppWindow 或 HTML5 全屏 API 将窗口设为全屏，则此属性为 true。

isFullscreen 函数如下所示：
```
() => {...}
```
- 返回
  布尔值
isMaximized

void

窗口是否已最大化？

isMaximized 函数如下所示：
```
() => {...}
```
- 返回
  布尔值
isMinimized

void

窗口是否已最小化？

isMinimized 函数如下所示：
```
() => {...}
```
- 返回
  布尔值
最大化

void

最大化窗口。

maximize 函数如下所示：
```
() => {...}
```
最小化

void

最小化窗口。

minimize 函数如下所示：
```
() => {...}
```
moveTo

void

自 Chrome 43 起已弃用

使用 outerBounds。
将窗口移动到位置 (left, top)。

moveTo 函数如下所示：
```
(left: number, top: number) => {...}
```
- 向左
  
  数值
- 顶部
  
  数值
resizeTo

void

自 Chrome 43 起已弃用

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

resizeTo 函数如下所示：
```
(width: number, height: number) => {...}
```
- width
  
  数值
- 高度
  
  数值
恢复

void

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

restore 函数如下所示：
```
() => {...}
```
setAlwaysOnTop

void

设置窗口是否应保持在大多数其他窗口之上。需要 alwaysOnTopWindows 权限。

setAlwaysOnTop 函数如下所示：
```
(alwaysOnTop: boolean) => {...}
```
- alwaysOnTop
  
  布尔值
setBounds

void

已弃用

使用 innerBounds 或 outerBounds。
设置窗口的内部边界。

setBounds 函数如下所示：
```
(bounds: ContentBounds) => {...}
```
- bounds
  
  ContentBounds
setVisibleOnAllWorkspaces

void

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

setVisibleOnAllWorkspaces 函数如下所示：
```
(alwaysVisible: boolean) => {...}
```
- alwaysVisible
  
  布尔值
显示

void

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

show 函数如下所示：
```
(focused?: boolean) => {...}
```
- 专注
  
  布尔值（可选）

Bounds

属性

高度

数值

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

数值

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

number 可选

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

number 可选

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

number 可选

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

number 可选

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

数值

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

数值

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

void

设置内容或窗口的最大尺寸限制。您可以将最大宽度或高度设置为 null，以移除限制。值为 undefined 时，相应限制将保持不变。

setMaximumSize 函数如下所示：
```
(maxWidth: number, maxHeight: number) => {...}
```
- maxWidth
  
  数值
- maxHeight
  
  数值
setMinimumSize

void

设置内容或窗口的最小尺寸限制。您可以将最小宽度或高度设置为 null 以移除限制。值为 undefined 时，相应限制将保持不变。

setMinimumSize 函数如下所示：
```
(minWidth: number, minHeight: number) => {...}
```
- minWidth
  
  数值
- minHeight
  
  数值
setPosition

void

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

setPosition 函数如下所示：
```
(left: number, top: number) => {...}
```
- 向左
  
  数值
- 顶部
  
  数值
setSize

void

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

setSize 函数如下所示：
```
(width: number, height: number) => {...}
```
- width
  
  数值
- 高度
  
  数值

BoundsSpecification

属性

高度

number 可选

内容或窗口的高度。
向左

number 可选

内容或窗口的 X 坐标。
maxHeight

number 可选

内容或窗口的最大高度。
maxWidth

number 可选

内容或窗口的最大宽度。
minHeight

number 可选

内容或窗口的最小高度。
minWidth

number 可选

内容或窗口的最小宽度。
顶部

number 可选

内容或窗口的 Y 坐标。
width

number 可选

内容或窗口的宽度。

ContentBounds

属性

高度

number 可选
向左

number 可选
顶部

number 可选
width

number 可选

CreateWindowOptions

属性

alwaysOnTop

布尔值（可选）

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

在创建窗口后，调用 setAlwaysOnTop() 即可更改此属性。
bounds

ContentBounds 可选

已弃用

使用 innerBounds 或 outerBounds。
窗口中内容的大小和位置（不包括标题栏）。如果还指定了 ID，并且之前已显示过具有匹配 ID 的窗口，则系统会改用该窗口的记忆边界。
专注

布尔值（可选）

如果为 true，则在创建窗口时会聚焦于该窗口。默认值为 true。
帧

字符串 | FrameOptions 可选

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

FrameOptions 的使用在 M36 中是新增的。
已隐藏

布尔值（可选）

如果为 true，则窗口将以隐藏状态创建。创建窗口后，调用该窗口的 show() 方法即可显示该窗口。默认值为 false。
图标

字符串（选填）

Chrome 54 及更高版本

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

字符串（选填）

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

BoundsSpecification 可选

用于指定窗口内容（不包括窗口装饰）的初始位置、初始大小和限制。如果还指定了 id，并且之前已显示过具有匹配 id 的窗口，则会改用记忆的边界。

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

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

number 可选

已弃用

使用 innerBounds 或 outerBounds。
窗口的最大高度。
maxWidth

number 可选

已弃用

使用 innerBounds 或 outerBounds。
窗口的最大宽度。
minHeight

number 可选

已弃用

使用 innerBounds 或 outerBounds。
窗口的最小高度。
minWidth

number 可选

已弃用

使用 innerBounds 或 outerBounds。
窗口的最小宽度。
outerBounds

BoundsSpecification 可选

用于指定窗口（包括标题栏和框架等窗口装饰）的初始位置、初始大小和限制。如果还指定了 id，并且之前已显示过具有匹配 id 的窗口，则会改用记忆的边界。

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

此属性是 Chrome 36 中的新增属性。
可调整大小

布尔值（可选）

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

布尔值（可选）

Chrome 54 及更高版本

如果为 true，则窗口将有自己的搁架图标。否则，窗口将与关联到该应用的其他窗口一起分组显示在搁架中。默认值为 false。如果 showInShelf 设置为 true，您需要为窗口指定一个 ID。
单例

布尔值（可选）

已弃用

不再支持具有相同 ID 的多个窗口。
默认情况下，如果您为窗口指定了 ID，则仅当不存在具有相同 ID 的其他窗口时，系统才会创建该窗口。如果已存在具有相同 ID 的窗口，则会改为激活该窗口。如果您确实想创建多个具有相同 ID 的窗口，可以将此属性设置为 false。
州

州/省/自治区/直辖市（选填）

窗口的初始状态，允许创建时已处于全屏、最大化或最小化状态。默认值为“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”

"fullscreen"

“最大化”

“最小化”

WindowType

Chrome 45 及更高版本

指定要创建的窗口的类型。

枚举

“shell”
默认窗口类型。

“面板”
由操作系统管理的窗口（已弃用）。

方法

canSetVisibleOnAllWorkspaces()

chrome.app.window.canSetVisibleOnAllWorkspaces(): boolean

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

布尔值

create()

Promise

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

您可以通过多种不同的方式指定窗口的大小和位置。最简单的选项是不指定任何内容，在这种情况下，系统将使用默认大小和平台相关位置。

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

如需自动记住窗口的位置，您可以为窗口指定 ID。如果窗口具有 ID，则每当窗口移动或调整大小时，系统都会使用此 ID 来记住窗口的大小和位置。然后，在后续打开具有相同 ID 的窗口时，系统会使用此大小和位置，而不是指定的边界。如果您需要打开一个具有 ID 的窗口，但该窗口的位置不是记忆的默认位置，您可以先创建该窗口并将其隐藏，然后将其移动到所需位置，最后再显示该窗口。

参数

网址

字符串
选项

CreateWindowOptions 可选
callback

函数可选

callback 参数如下所示：
```
(createdWindow: AppWindow) => void
```
- createdWindow
  
  AppWindow

Promise<AppWindow>

Chrome 117 及更高版本

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

current()

chrome.app.window.current(): AppWindow | undefined

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

AppWindow | 未定义

get()

chrome.app.window.get(
  id: string,
): AppWindow | undefined

获取具有指定 ID 的 AppWindow。如果不存在具有指定 ID 的窗口，则返回 null。此方法是 Chrome 33 中的新增方法。

参数

id

字符串

AppWindow | 未定义

getAll()

chrome.app.window.getAll(): AppWindow[]

获取当前创建的所有应用窗口的数组。此方法是 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
```

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

说明

类型