Location.assign() - Web API 接口参考

Location.assign()
=================

**`Location.assign()`** 方法会触发窗口加载并显示指定的 URL 的内容。

如果由于安全原因无法执行跳转，那么会抛出一个 `SECURITY_ERROR` 类型的 `DOMException`。当调用此方法的脚本来源和页面的 `Location` 对象中定义的来源隶属于不同域的时候，就会抛出上述错误。

如果传入了一个无效的 URL，则会抛出一个 `SYNTAX_ERROR` 类型的 `DOMException`。

语法
--
```

location.assign(url);
```

### 参数

`url`

一个包含了要跳转到的链接的`DOMString`。

示例
--

```js
// 跳转到 Location.reload() 这篇文章
document.location.assign(
  "https://developer.mozilla.org/zh-CN/docs/Web/API/Location/reload",
);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-location-assign-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关内容
----

* 父级接口 `Location`。
* 相似的方法：`Location.replace()` 和 `Location.reload()`。


Location: ancestorOrigins - Web API 接口参考

Location: ancestorOrigins
=========================

`Location`接口的 **`ancestorOrigins`** 只读属性是一个静态的`DOMStringList`，倒序排列了此`Location`对象所属文档先前所有浏览上下文的来源。

你可以在脚本中使用`location.ancestorOrigins`来检测你的网页是否被你不希望的对象嵌入了。你也可以使用它让网页在被特定站点嵌入时做出不同的表现。

语法
--

```js
const ancestors = location.ancestorOrigins;
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-location-ancestororigins-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Location: host - Web API 接口参考

Location: host
==============

`Location` 接口的 **`host`** 属性是包含了主机的一段 `USVString`，其中包含：主机名，如果 URL 的端口号是非空的，还会跟上一个 `':'` ，最后是 URL 的端口号。

Syntax
------
```

string = object.host;
object.host = string;
```

Examples
--------

```js
var anchor = document.createElement("a");

anchor.href = "https://developer.mozilla.org/en-US/Location.host";
anchor.host == "developer.mozilla.org";

anchor.href = "https://developer.mozilla.org:443/en-US/Location.host";
anchor.host == "developer.mozilla.org";
// 这里 host 中没有包含端口号，因为 443 是 https 协议的默认端口号

anchor.href = "https://developer.mozilla.org:4097/en-US/Location.host";
anchor.host == "developer.mozilla.org:4097";
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-location-host-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Location: hostname - Web API 接口参考

Location: hostname
==================

`Location`的 **`hostname`** 属性是包含了域名的一段 `USVString`。

Syntax
------
```

string = object.hostname;
object.hostname = string;
```

Examples
--------

```js
// 在文档流中声明了一个元素： <a id="myAnchor" href="https://developer.mozilla.org/zh-CN/docs/Location.hostname">
var anchor = document.getElementById("myAnchor");
var result = anchor.hostname; // Returns:'developer.mozilla.org'
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-location-hostname-dev |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


location.reload() - Web API 接口参考

location.reload()
=================

**`location.reload()`** 方法用来刷新当前页面，就像刷新按钮一样。

该方法在跨域调用（执行该方法的脚本文件的域和 `Location` 对象所在页面的域不同）时，将会抛出 `SECURITY_ERROR` `DOMException` 异常。有关更多信息，请参阅浏览器的同源策略。

语法
--

```js
location.reload();
```

location.reload() 没有参数
----------------------

Firefox 对于该方法支持一个非标准的 `forceGet` boolean 参数 ，当值为 `true` 时，将强制 Firefox 从服务器加载页面资源。但是在其他浏览器中任何参数都是无效的，`location.reload()` 执行时将会忽略它们并且不会有任何效果。

不过你可能会看到在现有的代码中写入 `location.reload(true)` 并假装硬性重新加载在所有浏览器中均生效的使用方式。在 GitHub 中搜索 "`location.reload(true)`" 将会得到 成千上万个结果。所以现在有大量的现有代码中包含它。

由于一些历史的原因，网景浏览器的一些版本添加了对它的支持，显然被继承到了 Firefox 中。并且一度被 W3C Web APIs 工作组作为一个提案来考虑添加到 `location.reload()` 中。但是它从未实际实现过。

因此 boolean 参数当前不符合 `location.reload()` 的规范。— 实际上它*从未*成为 `location.reload()` 的规范。

规范
--

| Specification |
| --- |
| HTML Standard # dom-location-reload-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关链接
----

* `Location` 接口。
* 类似功能的方法：`Location.assign()` 和 `Location.replace()`。


Location: href - Web API 接口参考

Location: href
==============

`Location` 接口的 **`href`** 属性是一个字符串化转换器 (stringifier), 返回一个包含了完整 URL 的 `USVString` 值，且允许 href 的更新。

语法
--
```

string = object.href;
object.href = string;
```

范例
--

```js
// 假设文档中包含标签： <a id="myAnchor" href="https://developer.mozilla.org/en-US/Location/href">
var anchor = document.getElementById("myAnchor");
var result = anchor.href; // 返回：'https://developer.mozilla.org/en-US/Location/href'
```

Specifications
--------------

| Specification |
| --- |
| HTML Standard # dom-location-href-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.moveBy() - Web API 接口参考

Window.moveBy()
===============

概述
--

根据指定的值，移动当前窗口。

语法
--
```

window.moveBy(deltaX, deltaY)
```

### 参数

* `deltaX` 表示窗口在水平方向移动的像素值。
* `deltaY` 表示窗口在垂直方向移动的像素值。
示例
--

```js
function budge() {
  moveBy(10, -10);
}
```

备注
--

可以使用负值作为该函数的参数。该函数产生相对移动，而 `window.moveTo` 产生一个绝对移动。

从 Firefox 7 开始，依据下面的规则，不能再移动一个浏览器里的窗口。

1. 不能移动非 window.open 创建的窗口或 Tab。
2. 当一个窗口里有多于一个 Tab 时，不能移动该窗口。
规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-moveby |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

从 Firefox 7 开始，网站在以下情况下将不能再移动浏览器窗口。

1. 不能移动不是由 `Window.open()` 创建的窗口或标签页。
2. 当一个窗口里有多于一个标签页时，不能移动该窗口或其中的标签页。
参见
--

* `window.moveTo()`


Window.screenY - Web API 接口参考

Window.screenY
==============

概述
--

返回浏览器顶部距离系统桌面顶部的垂直距离。

语法
--
```

lLoc = window.screenY
```

* `lLoc` 距离屏幕顶部的像素值。
规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-screeny |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `window.screenX`


Window.mozInnerScreenY - Web API 接口参考

Window.mozInnerScreenY
======================

概要
--

在屏幕坐标下获取窗口视口左上角的 Y 坐标

>
> \*\*备注：\*\*该坐标是以 CSS 像素报告显示的，而不是以硬件像素。这意味着它可以受缩放级别的影响; 要计算物理屏幕像素的实际数量，需要使用`nsIDOMWindowUtils.screenPixelsPerCSSPixel` 属性
>
>
>

语法
--
```

screenY = window.mozInnerScreenY;
```

值
-

* *screenY* 存储的是 `window.mozInnerScreenY` 的属性值。
* `window.mozInnerScreenY`的属性值是一个浮点数，只读;它没有默认值。
规范
--

不属于任何 W3C 规范或标准

相关链接
----

* `window.mozInnerScreenX`
* `nsIDOMWindowUtils.screenPixelsPerCSSPixel`


Window：copy 事件 - Web API 接口参考

Window：copy 事件
==============

当用户通过浏览器的用户界面发起一个复制动作时，将触发 **`copy`** 事件。

该事件的原始目标是 `Element`，它是复制动作的预期目标。你可以在 `Window` 接口上监听这个事件，以便在捕获或冒泡阶段处理它。关于此事件的全部细节，请参见 Element：copy 事件的页面。

语法
--

在类似于 `addEventListener()` 这样的方法中使用事件名，或设置事件处理器属性。

```js
addEventListener("copy", (event) => {});

oncopy = (event) => {};
```

事件类型
----

`ClipboardEvent`。继承自 `Event`。

Event

ClipboardEvent示例
--

```js
window.addEventListener("copy", (event) => {
  console.log("已发起复制！");
});
```

规范
--

| Specification |
| --- |
| Clipboard API and events # clipboard-event-copy |
| HTML Standard # handler-oncopy |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 相关联事件：`cut`、`paste`
* `Element` 目标上的这个事件：`copy`
* `Document` 目标上的这个事件：`copy` (en-US)


Window.screenTop - Web API 接口参考

Window.screenTop
================

**`Window.screenTop`** 只读属性返回垂直距离，单位是 CSS 像素，从用户浏览器的上边界到屏幕最顶端。

**备注：** `screenTop` is an alias of the older `Window.screenY` property. `screenTop` was originally supported only in IE but was introduced everywhere due to popularity.

语法
--
```

topWindowPos = window.screenTop
```

### 返回值

A number equal to the number of CSS pixels from the top edge of the browser viewport to the top edge of the screen.

例子
--

In our screenleft-screentop example, you'll see a canvas onto which has been drawn a circle. In this example we are using `screenLeft`/`screenTop` plus `Window.requestAnimationFrame()` to constantly redraw the circle in the same physical position on the screen, even if the window position is moved.

```js
initialLeft = window.screenLeft + canvasElem.offsetLeft;
initialTop = window.screenTop + canvasElem.offsetTop;

function positionElem() {
  let newLeft = window.screenLeft + canvasElem.offsetLeft;
  let newTop = window.screenTop + canvasElem.offsetTop;

  let leftUpdate = initialLeft - newLeft;
  let topUpdate = initialTop - newTop;

  ctx.fillStyle = "rgb(0, 0, 0)";
  ctx.fillRect(0, 0, width, height);
  ctx.fillStyle = "rgb(0, 0, 255)";
  ctx.beginPath();
  ctx.arc(
    leftUpdate + width / 2,
    topUpdate + height / 2 + 35,
    50,
    degToRad(0),
    degToRad(360),
    false,
  );
  ctx.fill();

  pElem.textContent =
    "Window.screenLeft: " +
    window.screenLeft +
    ", Window.screenTop: " +
    window.screenTop;

  window.requestAnimationFrame(positionElem);
}

window.requestAnimationFrame(positionElem);
```

Also in the code we include a snippet that detects whether `screenLeft` is supported, and if not, polyfills in `screenLeft`/`screenTop` using `Window.screenX`/`Window.screenY`.

```js
if (!window.screenLeft) {
  window.screenLeft = window.screenX;
  window.screenTop = window.screenY;
}
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-screentop |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参考
--

* `window.screenLeft`
* `Window.screenY`


Window.history - Web API 接口参考

Window.history
==============

**`Window.history`** 是一个只读属性，用来获取`History` 对象的引用，`History` 对象提供了操作浏览器*会话历史*（浏览器地址栏中访问的页面，以及当前页面中通过框架加载的页面）的接口。

`History` 对象有如下方法：参见 Manipulating the browser history 中的示例和详情。尤其指出的是文章里解释了在使用 `pushState()` 和 `replaceState()` 方法前，你需要了解的安全问题。

语法
--
```

var historyObj = window.history;
```

示例
--

```js
history.back(); // 等同于点击浏览器的回退按钮
history.go(-1); //等同于 history.back();
```

附注
--

在顶层页面中，浏览器的回退和前进按钮旁的下拉菜单显示了可以通过`History`对象访问到的页面会话历史（session history）列表。

出于安全考虑，History 对象不允许未授权代码访问会话历史（session History）中其他页面的 URLs，但可以导航到其他会话历史（session History）指向的页面。

未授权代码无法清除会话历史（session History），也不能禁用回退/前进功能。最快捷的可用方式是使用location.replace()方法，提供指定的 URL 来替换当前的会话历史（session history）。

规范
--

* HTML5 History interface


Window.updateCommands() - Web API 接口参考

Window.updateCommands()
=======================

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

概要
--

更新当前 chrome 窗口（UI）的命令状态。

语法
--
```

window.updateCommands("sCommandName")
```

参数
--

* `sCommandName` 是一个特定的字符串，它描述了这种更新事件的类型 (我们用到了背景色注明).
记录
--

这将启用或禁用项目（根据需要在命令节点上设置或清除“disabled”属性），或通过在 XUL 命令节点的“state”属性中设置当前状态信息来确保命令状态反映选择的状态。

规范
--

DOM 0 级。不属于规范。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window: focus event - Web API 接口参考

Window: focus event
===================

当元素获得焦点时， **`focus`** 事件就会触发。

与 `focus` 相反的事件是 `blur`

|
|  |
| Bubbles（支持冒泡） | No |
| Cancelable（可撤销） | No |
| Interface（接口） | `FocusEvent` |
| Event handler property（事件处理程序属性） | `onfocus` |
| Sync / Async（同步/异步） | Sync |
| Composed（可组成） | Yes |

示例
--

### 在线示例

本示例在失去焦点时更改文档的外观。它使用 `addEventListener()` 监听 `focus` 和 `blur` 事件。

#### HTML

```html
<p id="log">Click on this document to give it focus.</p>
```

#### CSS

```css
.paused {
  background: #ddd;
  color: #555;
}
```

#### JavaScript

```js
function pause() {
  document.body.classList.add("paused");
  log.textContent = "FOCUS LOST!";
}

function play() {
  document.body.classList.remove("paused");
  log.textContent =
    "This document has focus. Click outside the document to lose focus.";
}

const log = document.getElementById("log");

window.addEventListener("blur", pause);
window.addEventListener("focus", play);
```

#### 结果

规范
--

| Specification |
| --- |
| UI Events # event-type-focus |
| HTML Standard # handler-onfocus |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参考
--

* 相关联事件： `blur`
* `Element` 目标上的这个事件：`focus` 事件


Window.visualViewport - Web API 接口参考

Window.visualViewport
=====================

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`Window` 接口的 visualViewport 只读属性返回一个`VisualViewport`对象，该对象表示给定窗口的可视视口。

语法
--
```

var visualViewport = Window.visualViewport
```

### 值

一个 `VisualViewport` 对象。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-visualviewport |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.getComputedStyle() - Web API 接口参考

Window.getComputedStyle()
=========================

摘要
--

`Window.getComputedStyle()`方法返回一个对象，该对象在应用活动样式表并解析这些值可能包含的任何基本计算后报告元素的所有 CSS 属性的值。私有的 CSS 属性值可以通过对象提供的 API 或通过简单地使用 CSS 属性名称进行索引来访问。

语法
--
```

let style = window.getComputedStyle(element, [pseudoElt]);
```

element

用于获取计算样式的`Element`。

pseudoElt 可选

指定一个要匹配的伪元素的字符串。必须对普通元素省略（或`null`）。

**备注：** 在 Gecko 2.0 之前版本，参数 pseudoElt 是必要的。如果为 null，则不指定其他主要浏览器必须指定此参数。Gecko 已经更改为匹配其他浏览器的行为。。

返回的`style`是一个实时的 `CSSStyleDeclaration` 对象，当元素的样式更改时，它会自动更新本身。

示例
--

```js
let elem1 = document.getElementById("elemId");
let style = window.getComputedStyle(elem1, null);

// 它等价于
// let style = document.defaultView.getComputedStyle(elem1, null);
```

```js
<style>
 #elem-container{
   position: absolute;
   left:     100px;
   top:      200px;
   height:   100px;
 }
</style>

<div id="elem-container">dummy</div>
<div id="output"></div>

<script>
  function getTheStyle(){
    let elem = document.getElementById("elem-container");
    let theCSSprop = window.getComputedStyle(elem,null).getPropertyValue("height");
    document.getElementById("output").innerHTML = theCSSprop;
   }
  getTheStyle();
</script>
```

```js
function dumpComputedStyles(elem, prop) {
  let cs = window.getComputedStyle(elem, null);
  if (prop) {
    dump(" " + prop + " : " + cs.getPropertyValue(prop) + "\n");
    return;
  }
  let len = cs.length;
  for (var i = 0; i < len; i++) {
    let style = cs[i];
    dump(" " + style + " : " + cs.getPropertyValue(style) + "\n");
  }
}
```

描述
--

返回的对象与从元素的 `style` 属性返回的对象具有相同的类型;然而，两个对象具有不同的目的。从`getComputedStyle`返回的对象是只读的，可以用于检查元素的样式（包括由一个`<style>`元素或一个外部样式表设置的那些样式）。`elt.style`对象应用于在特定元素上设置样式。

第一个参数必须是 Element 对象 (传递一个非节点元素，如 一个#text 节点，将会抛出一个错误). 从 Gecko 1.9.2 开始，现在返回的一个在 URL 周围有引号的 URL 值，像这样：`url("http://foo.com/bar.jpg")`。

`defaultView`
-------------

在许多在线的演示代码中，`getComputedStyle`是通过 `document.defaultView` 对象来调用的。大部分情况下，这是不需要的，因为可以直接通过`window`对象调用。但有一种情况，你必需要使用 `defaultView`, 那是在 firefox3.6 上访问子框架内的样式。

与伪元素一起使用
--------

getComputedStyle 可以从**伪元素**拉取样式信息 (比如，`::after`, `::before`, `::marker`, `::line-marker`—查看 详情 这里).

```html
<style>
 h3::after {
 content: "rocks!";
 }
</style>

<h3>generated content</h3>

<script>
 let h3 = document.querySelector("h3"),
 result = getComputedStyle(h3, "::after").content;
 alert(`the generated content is: ${result}`);
 console.log(`the generated content is: ${result}`);
 // the generated content is: "rocks!"
</script>
```

注意
--

返回的`CSSStyleDeclaration`对象将包含所有受支持的 CSS 属性长名称的活动值。示例名称是`border-bottom-width`，`border-width`和`border`是示例速记属性名称。仅使用像`font-size`这样的名字来查询值是最安全的。查询诸如`font`等简写名称不适用于大多数浏览器。

CSS 规范也允许使用驼峰命名，比如`fontSize`或`paddingTop`。

CSS 属性值可以使用`getPropertyValue(propName)`API 或直接索引到对象，如`cs ['z-index']`或`cs.zIndex`。

`getComputedStyle`的返回值是 `resolved values`, 通常跟 CSS2.1 中的`computed values`是相同的值。但对于一些旧的属性，比如`width`, `height`, `padding` 它们的值又为 `used values`。最初，CSS2.0 定义的计算值 Computed values 就是属性的最终值。但是 CSS2.1 重新定义了 computed values 为布局前的值，used values 布局后的值。布局前与布局后的区别是，width 或者 height 的 百分比可以代表元素的宽度，在布局后会被像素值替换。

在某些情况下，通过浏览器会特意返回不准确的值。特别是在避免 CSS 浏览历史泄露的安全问题，比如，浏览者看过某个网站，它的链接通常会变成蓝色带下划线的链接，通过判断链接的颜色（getComputedSytle(node, null).color) 是否为蓝色，就会泄露用户的浏览历史，所以浏览器会特意返回不准确的值，保护用户隐私。可以了解更多关于 css 安全的链接http://blog.mozilla.com/security/2010/03/31/plugging-the-css-history-leak/ 和 http://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/

在 CSS 过渡期间，`getComputedStyle`返回 Firefox 中的原始属性值，但返回 WebKit 中的最终属性值。

在 Firefox 中，属性值为`auto`的会直接返回使用值，而不是`auto`。比如，你在设定了一个元素的 css 为`height:30px; top: auto; bottom:0;`它的父元素`height:100px;`，在请求`top`的计算样式时，Firefox 会返回`'70px' = 100px - 30px;`。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

规范
--

* DOM Level 2 Style: getComputedStyle
* CSS Object Model specification
参见
--

* `window.getDefaultComputedStyle`
* `Resolved Value`


Window：showSaveFilePicker() 方法 - Web API 接口参考

Window：showSaveFilePicker() 方法
==============================

**安全上下文:** 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

`Window` 接口的 **`showSaveFilePicker()`** 方法用于显示一个文件选择器，以允许用户保存一个文件。可以选择一个已有文件覆盖保存，也可以输入名字新建一个文件。

语法
--

```js
showSaveFilePicker()
```

### 参数

`options` 可选

选项对象，包含以下属性：

`excludeAcceptAllOption`

布尔值，默认为 `false`。默认情况下，文件选择器带有一个允许用户选择所有类型文件的过滤选项（展开于文件类型选项中）。设置此选项为 `true` 以使该过滤选项不可用。

`suggestedName`

`String` 字符串。建议的文件名称。

`types`

允许保存的文件类型的 `Array` 数组。其中的元素为包含以下选项的对象：

`description`

可选，对此允许文件类型集合的描述。

`accept`

`Object` 对象，带有键名为 MIME 类型、键值为包含文件扩展名的 `Array` 数组的键值对（参考下方的示例）。

### 返回值

一个 `Promise` 对象，会兑现一个 `FileSystemFileHandle` 对象。

### 异常

`AbortError`

当用户直接关闭了文件选择器或选择的文件是敏感文件时将会抛出 AbortError。

安全性
---

要求发生临时性用户活动 (en-US)。用户必须与页面或 UI 元素进行交互才能使该特性正常运行。

示例
--

以下函数可以显示一个文件选择器，并突出显示文本文件类型以供选择。

```js
async function getNewFileHandle() {
  const opts = {
    types: [
      {
        description: "Text file",
        accept: { "text/plain": [".txt"] },
      },
    ],
  };
  return await window.showSaveFilePicker(opts);
}
```

规范
--

| Specification |
| --- |
| File System Access # api-showsavefilepicker |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 文件系统 API
* 文件系统访问 API：简化对本地文件的访问


Window：load 事件 - Web API 接口参考

Window：load 事件
==============

**`load`** 事件在整个页面及所有依赖资源如样式表和图片都已完成加载时触发。它与 `DOMContentLoaded` 不同，后者只要页面 DOM 加载完成就触发，无需等待依赖资源的加载。

该事件不可取消，也不会冒泡。

**备注：** *所有以 `load` 命名的事件都不会传递到 `Window` 上*，即使 `bubbles` 初始化为 `true`。要在 `window` 上捕获 `load` 事件，相关的 `load` 事件必须直接绑定到 `window` 上。

**备注：** 当主文档加载完成时，`load` 事件将在 `window` 上触发，但其有两个被修改的属性：`target` 为 `document`，以及 `path` 为 `undefined`。这是由遗留的一致性问题导致的。

语法
--

在如 `addEventListener()` 等方法中使用事件名称，或设置事件处理器属性。

```js
addEventListener("load", (event) => {});

onload = (event) => {};
```

事件类型
----

一个通用的 `Event`。

示例
--

当页面完全加载后在控制台打印一段信息：

```js
window.addEventListener("load", (event) => {
  console.log("page is fully loaded");
});
```

也可以使用 `onload` 事件处理器属性实现：

```js
window.onload = (event) => {
  console.log("page is fully loaded");
};
```

### 交互示例

#### HTML

```html
<div class="controls">
  <button id="reload" type="button">Reload</button>
</div>

<div class="event-log">
  <label for="eventLog">Event log:</label>
  <textarea
 readonly
 class="event-log-contents"
 rows="8"
 cols="30"
 id="eventLog"></textarea>
</div>
```

```
body {
  display: grid;
  grid-template-areas: "control log";
}

.controls {
  grid-area: control;
  display: flex;
  align-items: center;
  justify-content: center;
}

.event-log {
  grid-area: log;
}

.event-log-contents {
  resize: none;
}

label,
button {
  display: block;
}

#reload {
  height: 2rem;
}
```

#### JavaScript

```js
const log = document.querySelector(".event-log-contents");
const reload = document.querySelector("#reload");

reload.addEventListener("click", () => {
  log.textContent = "";
  setTimeout(() => {
    window.location.reload(true);
  }, 200);
});

window.addEventListener("load", (event) => {
  log.textContent += "load\n";
});

document.addEventListener("readystatechange", (event) => {
  log.textContent += `readystate: ${document.readyState}\n`;
});

document.addEventListener("DOMContentLoaded", (event) => {
  log.textContent += `DOMContentLoaded\n`;
});
```

#### 结果

规范
--

| Specification |
| --- |
| UI Events # event-type-load |
| HTML Standard # delay-the-load-event |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* Document readyState API
* 相关事件
    + `DOMContentLoaded`
    + `readystatechange`
    + `beforeunload`
    + `unload`


Window.window - Web API 接口参考

Window.window
=============

摘要
--

window 对象的 `window` 属性指向这个 window 对象本身。因此以下表达式所返回的 window 对象都是同一个。
```

window.window
window.window.window
window.window.window.window
  ...
```

在网页中，window 对象也是一个全局对象。这意味着：

1. 脚本中的全局变量实际上是 window 对象的属性：

```js
var global = { data: 0 };
alert(global === window.global); // displays "true"
```

2. 不用写 `window.` 前缀就可以访问 window 对象的内置属性：

```js
setTimeout("alert('Hi!')", 50); // equivalent to using window.setTimeout.
alert(window === window.window); // displays "true"
```

将 `window` 属性指向该 window 对象本身的目的，是为了更容易引用全局对象。不然，就得在最开始写代码的时候进行手动赋值：`var window = this;` 。

另外一个原因是如果没有这个属性，就不能像这样方便的写： `window.open('http://google.com/')`，而只能这样：open('http://google.com/')

使用该属性还有一个原因，有些库，特别是 JavaScript 模块希望能够提供 OOP 版本和非 OOP 版本。例如，如果引用了 `this.window.location.href` ，JavaScript 模块就可以在它定义的类里面定义一个 `window` 属性（因为默认没有全局性的 `window` 变量存在），这个属性可以在将 window 对象传进这个模块的类的构造器之后被创建。这样，这个类的方法中的 `this.window` 就指向了 window 对象。在没有命名空间的版本中，`this.window` 会重新指向 window 对象，从而很容易获取到文档的位置。还有一个优点，这个类（即使这个类定义在模块外面）的对象可以随意地改变对 window 的引用，而如果有一个写死了的 window 的引用就做不到这样。类内部的默认值仍然可以设置成当前的 window 对象。

规范
--

| Specification |
| --- |
| HTML Standard # dom-window-dev |


window.frameElement - Web API 接口参考

window.frameElement
===================

### 概述

返回嵌入当前`window`对象的元素 (比如 `<iframe>` 或者 `<object>`),如果当前`window`对象已经是顶层窗口，则返回`null`.

### 语法
```

var frameEl = window.frameElement;
```

### 例子
```

var frameEl = window.frameElement;
// 如果当前窗口被包含在一个框架里面，则将该框架的地址跳到'http://mozilla.org/'
if (frameEl)
  frameEl.src = 'http://mozilla.org/';
```

### 备注

虽然该属性名为`frameElement`,但该属性也会返回其他类型比如 `<object>` 或者其他可嵌入窗口的元素。

### 相关链接

* `window.frames` 返回一个类数组对象，返回当前窗口的所有子框架元素。
* `window.parent` 返回当前窗口的父窗口，也就是说，包含当前窗口所在的`frameElement`元素的窗口。
### 规范

WHATWG

### 浏览器兼容性

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window：confirm() 方法 - Web API 接口参考

Window：confirm() 方法
===================

`window.confirm()` 令浏览器显示一个带有可选的信息的对话框，并等待用户确认或取消该对话框。

在某些情况下（例如，当用户切换标签时）浏览器可能不会实际显示一个对话框，或者不等待用户确认或取消对话框。

语法
--

```js
confirm(message)
```

### 参数

`message`

在确认对话框中要显示的字符串。

### 返回值

一个布尔值，表示是否选择了确定（`true`）或取消（`false`）。如果浏览器忽略了页面内的对话框，那么返回值总是 `false`。

示例
--

```js
if (window.confirm("Do you really want to leave?")) {
  window.open("exit.html", "Thanks for Visiting!");
}
```

会产生：

![Firefox 确认对话框](/zh-CN/docs/Web/API/Window/confirm/firefox_confirm_dialog.png)

注意事项
----

对话框是模态窗口——它们阻止用户访问程序界面的其他部分，直到对话框被关闭。出于这个原因，你不应该过度使用任何创建对话框（或模态窗口）的函数。无论如何，有很好的应避免使用对话框进行确认的理由。

另外，`<dialog>` 元素也可用于确认。

规范
--

| Specification |
| --- |
| HTML Standard # dom-confirm-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `<dialog>` 元素
* `window.alert()`
* `window.prompt()`


storage - Web API 接口参考

storage
=======

当存储区域（localStorage 或 sessionStorage）被修改时，将触发 storage 事件。查看 Web Storage API 来获取更多信息。

常规信息
----

说明：*Web Storage*

|  |  |
| --- | --- |
| 接口 | `StorageEvent` |
| 是否冒泡 | No |
| 目标 | DefaultView (`<window>`) |
| 默认行为 | 无 |

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | `EventTarget` | 事件目标 (DOM 树中的最大目标) |
| `type` 只读  | `DOMString` | 事件的类型 |
| `bubbles` 只读  | `Boolean` | 事件通常是否会出现冒泡 |
| `cancelable` 只读  | `Boolean` | 事件是否可取消 |
| `key` 只读  | `DOMString` (string) | 键更改时 |
| `oldValue` 只读  | `DOMString` (string) | 正在更改键的旧值 |
| `newValue` 只读  | `DOMString` (string) | 正在更改键的新值 |
| `url` 只读  | `DOMString` (string) | 键更改的文档的地址 |
| `storageArea` 只读  | `Storage` | 受影响的存储对象 |

规范
--

| Specification |
| --- |
| HTML Standard # event-storage |
| HTML Standard # handler-window-onstorage |


window.setImmediate - Web API 接口参考

window.setImmediate
===================

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

该方法用来把一些需要长时间运行的操作放在一个回调函数里，在浏览器完成后面的其他语句后，就立刻执行这个回调函数。

**备注：** 该方法可能不会被批准成为标准，目前只有最新版本的 Internet Explorer 和 Node.js 0.10+ 实现了该方法。它遇到了 Gecko(Firefox) 和Webkit (Google/Apple) 的阻力。

语法
--

```js
var immediateID = setImmediate(func, [param1, param2, ...]);
var immediateID = setImmediate(func);
```

* `immediateID` 是这次 setImmediate 方法设置的唯一 ID，可以作为 `window.clearImmediate` 的参数。
* `func` 是将要执行的回调函数

所有参数都会直接传给你的函数。

备注
--

`window.clearImmediate` 方法可以用来取消通过 setImmediate 设置的将要执行的语句，就像 `window.clearTimeout` (en-US) 对应于 `window.setTimeout`一样。

该方法可以用来替代 `setTimeout(fn, 0)` 去执行繁重的操作(heavy operations)

可以通过以下几种方式来模仿该功能：

* `window.postMessage` 可以被用来触发一个 immediate 但会产生回调。请注意，Internet Explorer 8 包含 postMessage 的同步版本，这意味着它不能被用来作为代替品。
* MessageChannel 可以在 Web Workers 内部很好的被使用，而 postMessage 的语义意味着它不能在那使用。
* `setTimeout(fn, 0)`*可以使用*, 然而按照HTML 规范, 嵌套深度超过 5 级的定时器，会被限制在 4ms , 他没有为 setImmediate 的天然及时性提供合适的 polyfill.

所有这些技术都被纳入 robust setImmediate polyfill 中。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关链接
----

`window.clearImmediate`
Specification: Efficient Script Yielding

Microsoft setImmediate API Demo


window.cancelAnimationFrame - Web API 接口参考

window.cancelAnimationFrame
===========================

**`window.cancelAnimationFrame()`** 方法取消一个先前通过调用 `window.requestAnimationFrame()` 方法添加到计划中的动画帧请求。

语法
--

```js
cancelAnimationFrame(requestID)
```

### 参数

`requestID`

先前调用 `window.requestAnimationFrame()` 方法时返回的 ID。

### 返回值

无（`undefined`）。

示例
--

```js
const requestAnimationFrame =
  window.requestAnimationFrame ||
  window.mozRequestAnimationFrame ||
  window.webkitRequestAnimationFrame ||
  window.msRequestAnimationFrame;

const cancelAnimationFrame =
  window.cancelAnimationFrame || window.mozCancelAnimationFrame;

const start = Date.now();

let myReq;

function step(timestamp) {
  const progress = timestamp - start;
  d.style.left = `${Math.min(progress / 10, 200)}px`;
  if (progress < 2000) {
    // 在每次调用 requestAnimationFrame 时，注意更新 requestId
    myReq = requestAnimationFrame(step);
  }
}
myReq = requestAnimationFrame(step);
// 取消操作使用的是最后一个 requestId
cancelAnimationFrame(myReq);
```

规范
--

| Specification |
| --- |
| HTML Standard # animationframeprovider-cancelanimationframe |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `Window.requestAnimationFrame()`
* `DedicatedWorkerGlobalScope.cancelAnimationFrame()` (en-US)


WindowEventHandlers.onmessageerror - Web API 接口参考

WindowEventHandlers.onmessageerror
==================================

`WindowEventHandlers`接口的 onmessageerror 事件处理器是一个 `EventListener`，每当一个类型为 `messageerror` 的 `EventListener` 事件在一个窗口被触发 --也就是说，当它收到的消息不能是deserialized (en-US) 。

**备注：** 此特性在 Web Worker 中可用

语法
--
```

window.onmessageerror = function() { ... };
```

规范
--

| Specification |
| --- |
| HTML Standard # event-messageerror |
| HTML Standard # handler-window-onmessageerror |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using channel messaging


Window: error event - Web API 接口参考

Window: error event
===================

当资源加载失败或无法使用时，会在`Window`对象触发`error`事件。例如：script 执行时报错。

|  |  |
| --- | --- |
| Bubbles（支持冒泡） | No |
| Cancelable（可撤销） | No |
| Interface（接口） | `Event` or `UIEvent` |
| Event handler property（事件处理程序属性） | `onerror` |

如果它是由用户界面元素生成的，或者是由事件实例生成的，那么此事件是`UIEvent`实例。

示例
--

### 在线示例

#### HTML

```html
<div class="controls">
  <button id="script-error" type="button">Generate script error</button>
  <img class="bad-img" />
</div>

<div class="event-log">
  <label>Event log:</label>
  <textarea readonly class="event-log-contents" rows="8" cols="30"></textarea>
</div>
```

```
body {
  display: grid;
  grid-template-areas: "control log";
}

.controls {
  grid-area: control;
  display: flex;
  align-items: center;
  justify-content: center;
}

.event-log {
  grid-area: log;
}

.event-log-contents {
  resize: none;
}

label,
button {
  display: block;
}

button {
  height: 2rem;
  margin: 0.5rem;
}

img {
  width: 0;
  height: 0;
}
```

#### JS

```js
const log = document.querySelector(".event-log-contents");

window.addEventListener("error", (event) => {
  log.textContent = log.textContent + `${event.type}: ${event.message}\n`;
  console.log(event);
});

const scriptError = document.querySelector("#script-error");
scriptError.addEventListener("click", () => {
  const badCode = "const s;";
  eval(badCode);
});
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # event-error |
| HTML Standard # handler-onerror |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关事件
----

* This event on `Element` targets: `error` event


Window.requestFileSystem() - Web API 接口参考

Window.requestFileSystem()
==========================

这个非标准 `Window` **`requestFileSystem()`** 方法是谷歌浏览器内核用来让 web 站点或 app 获得通过沙箱访问文件系统 . 它返回 `FileSystem` 然后就可以和 file system APIs 一起使用了

**警告：** 甚至相比较如 File 和 Directory Entries API, `requestFileSystem()` 更不规范; 只有 Chrome 支持它，所有其他浏览器已经决定不支持它了。它甚至已经从规范建议单中移除了。因此*不要使用这个方法*

语法
--

**备注：** `在所有支持它的浏览器中这个方法都有 webkit 前缀` (实际上也仅有谷歌浏览器支持).
```

window.requestFileSystem(type, size, successCallback[, errorCallback]);
```

### 参数

`type`

要请求的存储类型。指定`Window.TEMPORARY` 浏览器自行决定要不要删除文件，例如低内存，或者`Window.PERSISTENT` 如果你需要文件保持在这个地方必须用户或站点或 app 明确许可。持久存储要求用户授予站点配额

`size`

你希望你的 app 被允许的使用空间大小。

`successCallback`

成功获取文件系统时调用的函数。回调接收单个参数：一个 `FileSystem` 表示应用程序有权使用的文件系统的对象。

`errorCallback` 可选

一个可选参数，指定在试图获取文件系统时发生错误或用户拒绝创建或访问文件系统的权限时调用的函数。回调接收单个参数作为输入：一个`FileError`用来描述错误的对象

### 返回值

无返回值

示例
--

规范
--

此方法已从 文件与目录条目 API 提案中移除，因此它没有成为 W3C 或者 WHATWG 的官方规范。它不再有望成为标准。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关知识
----

* File and Directory Entries API support in Firefox


Window.getSelection - Web API 接口参考

Window.getSelection
===================

返回一个 `Selection` 对象，表示用户选择的文本范围或光标的当前位置。

语法
--
```

const selection = window.getSelection() ;
```

* `selection` 是一个 `Selection` 对象。如果想要将 `selection` 转换为字符串，可通过连接一个空字符串（""）或使用 `String.toString()` 方法。
示例
--

```js
function foo() {
  let selObj = window.getSelection();
  console.log(selObj);
  let selRange = selObj.getRangeAt(0);
  // 其他代码
}
```

备注
--

在 JavaScript 中，当一个对象被传递给期望字符串作为参数的函数中时（如 `window.alert` 或 `document.write`），对象的`toString()`方法会被调用，然后将返回值传给该函数。

在上例中，`selObj.toString()` 会在传递到 `window.alert()`时自动调用。然而，当你试图在 `Selection` 对象上使用一个 JavaScript 的`String` 对象上的属性或者方法时（如 `String.prototype.length` 或者 `String.prototype.substr()`），会导致错误（如果没有相应的属性或方法时）或返回不是期望的结果（如果存在相应的属性或方法）。如果想要将 `Selection` 对象作为一个字符串使用，请直接调用 `toString()` 方法：

```js
var selectedText = selObj.toString();
```

* `selObj` 是一个`Selection` 对象，
* `selectedText` 是一个字符串（被选中的文本）。
### 相关对象

你还可以使用 `Document.getSelection()` (en-US)，两个方法等价。

值得注意的是，目前在 Firefox, Edge (非 Chromium 版本) 及 Internet Explorer 中，`getSelection()` 对 `<textarea>` 及 `<input>` 元素不起作用。 `HTMLInputElement.setSelectionRange()` 或 `selectionStart` 及 `selectionEnd` 属性可用于解决此问题。

还要注意选择不同于焦点（详见 Selection 及输入焦点）。可使用`Document.activeElement` 来返回当前的焦点元素。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关链接
----

* HTML Editing API
* `Selection`
* `Range`
* `Document.getSelection()` (en-US)


Window：resize 事件 - Web API 接口参考

Window：resize 事件
================

文档视图（窗口）调整大小时会触发 **`resize`** 事件。

这个事件不可取消，不会冒泡。

在一些早期的浏览器中，可以在任何 HTML 元素上注册 `resize` 事件处理器。现在仍然可以设置 `onresize` 属性或使用 `addEventListener()` 在任何元素上设置一个处理器。然而，`resize` 事件只在 `window` 对象（即由 `document.defaultView` 返回）上触发。只有在 `window` 对象上注册的处理器才能接收 `resize` 事件。

虽然现在 `resize` 事件只针对窗口触发，但你可以使用 ResizeObserver API 获得其他元素的尺寸调整通知。

如果对你的应用程序来说，调整大小事件被触发了太多次，请参阅优化 window.onresize 来控制事件触发的时间。

语法
--

在像 `addEventListener()` 这样的方法中使用事件名称，或者设置事件处理器属性。

```js
addEventListener("resize", (event) => {});

onresize = (event) => {};
```

事件类型
----

`UIEvent`。继承自 `Event`。

Event

UIEvent事件属性
----

*本接口也从其父接口 `Event` 继承属性。*

`UIEvent.detail` 只读

根据事件类型不同，返回一个带有事件细节的 `long` 值。

`UIEvent.sourceCapabilities` (en-US)
实验性
 只读

返回 `InputDeviceCapabilities` 接口的一个实例，它提供了生成触摸事件相关的物理设备信息。

`UIEvent.view` 只读

返回一个 WindowProxy (en-US)，其中包含产生该事件的视图。

`UIEvent.which`
已弃用

非标准
 只读

返回被按下的数字键的 `keyCode`，或被按下的字母数字键的字符代码（`charCode`）。

示例
--

### 窗口大小记录器

以下示例报告了每次改变窗口大小时，窗口的尺寸。

#### HTML

```html
<p>缩放浏览器窗口以触发 <code>resize</code> 事件</p>
<p>窗口高度：<span id="height"></span></p>
<p>窗口宽度：<span id="width"></span></p>
```

#### JavaScript

```js
const heightOutput = document.querySelector("#height");
const widthOutput = document.querySelector("#width");

function reportWindowSize() {
  heightOutput.textContent = window.innerHeight;
  widthOutput.textContent = window.innerWidth;
}

window.onresize = reportWindowSize;
```

#### 结果

**备注：** 这里的例子是在 `<iframe>` 中输出的，所以报告的宽度和高度值是针对 `<iframe>` 的，而不是本页面所在的窗口。特别是，很难调整窗口的大小，以便看到报告高度的不同。

在示例本身窗口查看示例更容易观察到效果。

### addEventListener 等价形式

你也可以使用 `addEventListener()` 方法设定事件处理器：

```js
window.addEventListener("resize", reportWindowSize);
```

规范
--

| Specification |
| --- |
| CSSOM View Module # eventdef-window-resize |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window：queryLocalFonts() 方法 - Web API 接口参考

Window：queryLocalFonts() 方法
===========================

**实验性:** **这是一项实验性技术**
在将其用于生产之前，请仔细检查浏览器兼容性表格。

**`window.queryLocalFonts()`** 方法返回一个兑现一个表示本地可用字体的 `FontData` 对象数组的 `Promise`。

要使用此方法，用户必须同意授予 `local-fonts` 权限（可以通过 Permissions API (en-US) 查询权限状态）。此外，此功能可能会被服务器上设置的权限策略阻止。

语法
--

```js
queryLocalFonts(options)
```

### 参数

`options` 可选

包含可选配置参数。目前仅定义了一个属性：

`postscriptNames` 可选

一个包含字体 PostScript 名称的数组。如果指定了此项，则只有 PostScript 名称与数组中的 PostScript 名称匹配的字体才会包含在结果中；如果没有，所有字体都将包含在结果中。

### 返回值

一个兑现一个表示本地可用字体的 `FontData` 对象数组的 `Promise`。

### 异常

`NotAllowedError` `DOMException`

首次调用该方法后，当浏览器出现权限提示时，用户选择拒绝授予此功能的权限。

`SecurityError` `DOMException`

此特性的使用被权限策略阻止，或者不是通过用户交互（如按下按钮）调用此特性，或当前的源不透明。

示例
--

有关实时演示，请参阅字体选择演示。

### 字体枚举

以下代码片段将查询所有可用的字体并打印元数据。例如，这可以用于填充字体选择器控件。

```js
async function logFontData() {
  try {
    const availableFonts = await window.queryLocalFonts();
    for (const fontData of availableFonts) {
      console.log(fontData.postscriptName);
      console.log(fontData.fullName);
      console.log(fontData.family);
      console.log(fontData.style);
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

### 限制返回结果

要将返回的字体数据限制为特定的字体列表，使用 `postscriptNames` 选项。

```js
async function returnSpecificFonts() {
  const availableFonts = await window.queryLocalFonts({
    postscriptNames: ["Verdana", "Verdana-Bold", "Verdana-Italic"],
  });

  return availableFonts;
}
```

### 访问底层数据

`blob()` 方法提供对底层 SFNT 数据的访问——这是一种可以包含其他字体格式的字体文件格式，例如 PostScript、TrueType、OpenType 或 Web 开放字体格式（WOFF）。

```js
async function computeOutlineFormat() {
  try {
    const availableFonts = await window.queryLocalFonts({
      postscriptNames: ["ComicSansMS"],
    });
    for (const fontData of availableFonts) {
      // `blob()` 方法返回一个包含有效且完整的 SFNT 封装字体数据的 Blob。
      const sfnt = await fontData.blob();
      // 仅裁剪出我们需要的字节部分：前 4 个字节是 SFNT 版本信息。
      // 规范：https://learn.microsoft.com/zh-cn/typography/opentype/spec/otff#organization-of-an-opentype-font
      const sfntVersion = await sfnt.slice(0, 4).text();

      let outlineFormat = "UNKNOWN";
      switch (sfntVersion) {
        case "\x00\x01\x00\x00":
        case "true":
        case "typ1":
          outlineFormat = "truetype";
          break;
        case "OTTO":
          outlineFormat = "cff";
          break;
      }
      console.log("矢量字体格式：", outlineFormat);
    }
  } catch (err) {
    console.error(err.name, err.message);
  }
}
```

规范
--

| Specification |
| --- |
| Local Font Access # dom-window-querylocalfonts |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* Local Font Access API
* 使用带有本地字体的高级排版
* `@font-face`


Window：paste 事件 - Web API 接口参考

Window：paste 事件
===============

当用户通过浏览器的用户界面发起一个“粘贴”动作时，将触发 **`paste`** 事件。

该事件的原始目标是 `Element`，它是粘贴动作的预期目标。你可以在 `Window` 接口上监听这个事件，以便在捕获或冒泡阶段处理它。关于此事件的全部细节，请参见 Element：paste 事件的页面。

语法
--

在类似于 `addEventListener()` 这样的方法中使用事件名，或设置事件处理器属性。

```js
addEventListener("paste", (event) => {});

onpaste = (event) => {};
```

事件类型
----

`ClipboardEvent`。继承自 `Event`。

Event

ClipboardEvent示例
--

```js
window.addEventListener("paste", (event) => {
  console.log("已发起粘贴！");
});
```

规范
--

| Specification |
| --- |
| Clipboard API and events # clipboard-event-paste |
| HTML Standard # handler-onpaste |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 相关联事件：`cut`、`copy`
* `Element` 目标上的这个事件：`paste`
* `Document` 目标上的这个事件：`paste` (en-US)


Window：deviceorientation 事件 - Web API 接口参考

Window：deviceorientation 事件
===========================

**`deviceorientation`** 事件在方向传感器输出新数据的时候触发。其数据系传感器与地球坐标系相比较所得，也就是说在设备上可能会采用设备地磁计的数据。

参见有关方向与运动信息的说明。

该事件不可取消也不会冒泡。

语法
--

在 `addEventListener()` 方法中使用事件名称，或使用事件处理器属性。

```js
addEventListener("deviceorientation", (event) => {});

ondeviceorientation = (event) => {};
```

事件类型
----

一个 `DeviceOrientationEvent`。继承了 `Event`。

Event

DeviceOrientationEvent事件属性
----

`DeviceOrientationEvent.absolute` 只读

一个布尔值，表示设备是否提供了方向数据。

`DeviceOrientationEvent.alpha` 只读

一个数字，表示设备围绕 z 轴的转动度数，范围为 0（含）到 360（不含）。

`DeviceOrientationEvent.beta` 只读

一个数字，表示设备围绕 x 轴的转动度数，范围为 -180（含）到 180（不含）。表示设备的前后运动。

`DeviceOrientationEvent.gamma` 只读

一个数字，表示设备围绕 y 轴的转动度数，范围为 -90（含）到 90（不含）。表示设备的左右运动。

`DeviceOrientationEvent.webkitCompassHeading`
非标准
 只读

一个数字，表示设备所得到的世界坐标系的 z 轴与正北方向的角度，范围为 0 到 360。

`DeviceOrientationEvent.webkitCompassAccuracy`
非标准
 只读

指南针的精准度，以正/负偏差的形式给出。通常是 10。

示例
--

```js
if (window.DeviceOrientationEvent) {
  window.addEventListener(
    "deviceorientation",
    function (event) {
      // alpha: rotation around z-axis
      var rotateDegrees = event.alpha;
      // gamma: left to right
      var leftToRight = event.gamma;
      // beta: front back motion
      var frontToBack = event.beta;

      handleOrientationEvent(frontToBack, leftToRight, rotateDegrees);
    },
    true,
  );
}

var handleOrientationEvent = function (
  frontToBack,
 leftToRight,
 rotateDegrees,
) {
  // do something amazing
};
```

规范
--

| Specification |
| --- |
| DeviceOrientation Event Specification # deviceorientation |
| DeviceOrientation Event Specification # ref-for-dom-window-ondeviceorientation |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `devicemotion`
* 检测设备朝向
* 有关方向与运动信息的说明


Window.innerWidth - Web API 接口参考

Window.innerWidth
=================

只读的 `Window` 属性 **`innerWidth`** 返回以像素为单位的窗口的内部宽度。如果垂直滚动条存在，则这个属性将包括它的宽度。

更确切地说，`innerWidth` 返回窗口的 layout viewport (en-US) 的宽度。窗口的内部高度——布局视口的高度——可以从 `innerHeight` 属性中获取到。

语法
--
```

let intViewportWidth = window.innerWidth;
```

### 值

一个整数型的值表示窗口的布局视口宽度是以像素为单位的。这个属性是只读的，并且没有默认值。

若要更改窗口的宽度，请使用 `Window` 的方法来调整窗口的大小，例如`resizeBy()` 或者 `resizeTo()`。

使用说明
----

如果你需要获取除去滚动条和边框的窗口宽度，请使用根元素 `<html>` 的`clientWidth` 属性。

`innerWidth` 属性在任何表现类似于窗口的任何窗口或对象（例如框架或选项卡）上都是可用的。

示例
--

```js
// 返回视口的宽度
var intFrameWidth = window.innerWidth;

// 返回一个框架集内的框架的视口宽度
var intFrameWidth = self.innerWidth;

// 返回最近的父级框架集的视口宽度
var intFramesetWidth = parent.innerWidth;

// 返回最外层框架集的视口宽度
var intOuterFramesetWidth = top.innerWidth;
```

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-innerwidth |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参考
--

* `window.outerWidth`
* `window.innerHeight`
* `window.outerHeight`


gamepadconnected - Web API 接口参考

gamepadconnected
================

`gamepadconnected` 事件会在浏览器检测到游戏控制器第一次连接或者第一次按下游戏键/摇杆的时候触发。

基本信息
----

文档

Gamepad

类型

事件

冒泡

No

可取消

No

Target

DefaultView (`<window>`)

默认操着

无

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读 | `DOMString` | 事件目标（DOM 树中的顶层，即 document.documentElement）。 |
| `type` 只读 | `EventTarget` | 事件的类型。 |
| `bubbles` 只读 | `Boolean` | 事件是否正常冒泡。 |
| `cancelable` 只读 | `Boolean` | 事件是否可以取消。 |
| `gamepad` 只读 | `Gamepad` | 单个游戏手柄属性，可用于访问关联游戏手柄的数据。 |

示例
--

```js
// 请注意，在实现该 API 的浏览器中，该 API 仍为供应商前缀
window.addEventListener("gamepadconnected", function (event) {
  // 所有按钮和轴值均可通过以下方式访问
  event.gamepad;
});
```

规范
--

| Specification |
| --- |
| Gamepad # event-gamepadconnected |

相关事件
----

* gamepaddisconnected (en-US)
还可以参考
-----

* Using Gamepad API (en-US)


Window.frames - Web API 接口参考

Window.frames
=============

概要
--

返回当前窗口，一个类数组对象，列出了当前窗口的所有直接子窗口。

语法
--
```

frameList = window.frames;
```

* frameList 是一个 frame 对象的集合，它类似一个数组，有 length 属性且可以使用索引（[i]）来访问。
* `frameList === window` 计算结果为 true。
* 在 window.frames 类数组中的每一项都代表了窗口对应给定对象的<frame>或<iframe>的内容，而不是 (i)frame DOM 元素（即 window.frames[ 0 ] 与 document.getElementsByTagName( "iframe" )[ 0 ].contentWindow 是相同的）。
* 有关返回值的更多详细信息，请参考 thread on mozilla.dev.platform 。
实例
--

```js
var frames = window.frames; // 或 // var frames = window.parent.frames;
for (var i = 0; i < frames.length; i++) {
  // 在这对 frames 的一个 frame 做点什么
  frames[i].document.body.style.background = "red";
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-frames-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window: hashchange event - Web API 接口参考

Window: hashchange event
========================

当 URL 的片段标识符更改时，将触发**hashchange**事件 (跟在＃符号后面的 URL 部分，包括＃符号)

|  |  |
| --- | --- |
| Bubbles | Yes |
| Cancelable | No |
| Interface | `HashChangeEvent` |
| Event handler | `onhashchange` |

示例
--

你可以在 `addEventListener` 方法中使用 `hashchange` 事件：

```js
window.addEventListener(
  "hashchange",
  function () {
    console.log("The hash has changed!");
  },
  false,
);
```

或使用 `onhashchange` 事件处理程序属性：

```js
function locationHashChanged() {
  if (location.hash === "#cool-feature") {
    console.log("You're visiting a cool feature!");
  }
}

window.onhashchange = locationHashChanged;
```

规范
--

| Specification |
| --- |
| HTML Standard # event-hashchange |
| HTML Standard # handler-window-onhashchange |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `popstate`
* `WindowEventHandlers.onhashchange`


Window.dump() - Web API 接口参考

Window.dump()
=============

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

概要
--

将信息打印到 (本地) 控制台（console）.

语法
--
```

window.dump(message);

dump(message);
```

* `message` 是要打印的字符串
注解
--

`dump()`的常见用途是调试 JavaScript。`dump`如果使用`console`选项启动了 Firefox 进程，则将消息发送到系统控制台（本地控制台）。如果`console`未指定该选项，则输出到对应终端。dump() 的输出不会发送到浏览器控制台。输出可以使用console.log（）发送到浏览器控制台。特殊的代码还能将消息记录到错误控制台 / 浏览器控制台。`Components.utils.reportError``nsIConsoleService`

`dump()`也可用于使用 JavaScript 实现的 XPCOM 组件，尽管 `window` 不是组件中的全局对象。它也明确地在沙箱中提供。但是，这种使用`dump`不受下面提到的偏好的影响 --- 它将始终显示出来。因此，建议你自己检查此偏好或使用自己的调试偏好，以确保在根本不感兴趣的情况下，不会向用户的控制台发送大量调试内容。请注意，`dump`XPCOM 组件的输出将转到`stderr`，而`dump`其他地方将输出`stdout`。

Gecko 在默认情况 **dump()** 下被禁用 - 它不会做任何事情，但也不会引起错误。要查看`dump`输出，你必须通过设置首选项`browser.dom.window.dump.enabled`来启用它。你可以在about：config或user.js 文件中设置首选项。注意：`about:config`默认情况下不会列出此首选项，你可能需要创建它（右键单击内容区域 - >新建 - >布尔值）。

在 Windows 上，你需要一个控制台才能看到任何东西。如果你还没有，请关闭应用程序并使用命令行参数重新打开`console`应该创建控制台或使用`-attach-console`现有的控制台。在其他操作系统上，从终端启动应用程序就足够了。

要将控制台输出重定向到文件，请运行 firefox *而不*使用-console 选项，并使用语法将 stderr 和 stdout 重定向到一个文件，即：
```

firefox > console.txt 2>&1
```

**备注：** 如果你希望控制台消息出现在用于启动应用程序的控制台中，则可以使用Gecko 控制台重定向器。预编译的二进制文件可以在压缩的归档文件 https://github.com/matthewkastor/Redirector/archive/master.zip 中找到，`Redirector-master\Gecko\Console Redirector\bin\Release`将所有 dll 和 exe 复制到任何你想要的地方。然后跑`Console Redirector.exe /?`

Specification
-------------

这不是标准的一部分


window.clearImmediate - Web API 接口参考

window.clearImmediate
=====================

概述
--

此方法用来清除 `window.setImmediate`.

**备注：** 该方法最近刚刚被微软提出，可能不会被 w3c 批准成为标准，目前只有最新版 Internet Explorer 实现了该方法。

语法
--

```js
clearImmediate(immediateID)
```

这里的 immediateID 是由`window.setImmediate`返回的。

例子
--

```js
var immediateID = setImmediate(function () {
  // Run some code
}

document.getElementById("button").addEventListener(function () {
  clearImmediate(immediateID);
}, false);
```

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关链接
----

`window.setImmediate`
Specification: Efficient Script Yielding


Window: rejectionhandled event - Web API 接口参考

Window: rejectionhandled event
==============================

当 `Promise` 被 `rejected` 且有 `rejection` 处理器时会在全局触发 **`rejectionhandled`** 事件 (通常是发生在 window 下，但是也可能发生在 Worker 中)。应用于调试一般应用回退。当 `Promise` 被 `rejected` 且没有 `rejection` 处理器处理时会触发 **`unhandledrejection`** 事件。这两个事件协同工作。

|  |  |
| --- | --- |
| 是否冒泡 | No |
| 是否可取消 | No |
| 接口 | PromiseRejectionEvent |
| 事件处理器属性 | onrejectionhandled |

示例
--

你可以使用`rejectionhandled 事件在控制台打印出被 rejected 的 Promise，以及被 rejected 的原因：`

```js
window.addEventListener(
  "rejectionhandled",
  (event) => {
    console.log("Promise rejected; reason: " + event.reason);
  },
  false,
);
```

规范
--

| Specification |
| --- |
| HTML Standard # unhandled-promise-rejections |
| HTML Standard # handler-window-onrejectionhandled |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* Promise 拒绝事件
* `PromiseRejectionEvent`
* `Promise`
* `unhandledrejection`


window.opener - Web API 接口参考

window.opener
=============

### 概述

返回打开当前窗口的那个窗口的引用，例如：在 window A 中打开了 window B，B.opener 返回 A.

### 语法
```

var objRef = window.opener;
```

### 例子

```js
if (window.opener != indexWin) {
  referToTop(window.opener);
}
```

### 备注

如果当前窗口是由另一个窗口打开的，**window.opener**保留了那个窗口的引用。如果当前窗口不是由其他窗口打开的，则该属性返回 null.

规范
--

| Specification |
| --- |
| HTML Standard # dom-opener-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.name - Web API 接口参考

Window.name
===========

获取/设置窗口的名称。

语法
--
```

string = window.name;
window.name = string;
```

示例
--

```js
window.name = "lab\_view";
```

备注
--

窗口的名字主要用于为超链接和表单设置目标（targets）。窗口不需要有名称。

在某些框架里（如，SessionVars 和 Dojo's dojox.io.windowName ，该属性也被用于作为 JSONP 的一个更安全的备选，来提供跨域通信（cross-domain messaging）。现代 web 应用应使用 postMessage API 进行敏感的跨域通信。

`window.name` 会调用 `toString` 将赋给它的值转换成对应的字符串表示。

（译注：此处似有不妥，私以为调用的应是 `ToString` 抽象方法。事实上，如果将一个 Symbol 类型的值赋给 `window.name`，会报 `TypeError`，而非调用 `Symbol.toString()` 转换成字符串后进行赋值。例如：

```js
window.name = Symbol.for("foo"); // TypeError
window.name = Symbol.for("foo").toString(); // "Symbol(foo)"
```

具体可参见 EMCA 语言规范中 Type Conversion 一节。）

规范
--

| Specification |
| --- |
| HTML Standard # dom-name-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window：afterprint 事件 - Web API 接口参考

Window：afterprint 事件
====================

在关联的文档开始打印或关闭打印预览后，将触发 **`afterprint`** 事件。

`beforeprint` 和 `afterprint` 事件允许页面在打印开始之前更改其内容（例如，也许是移除 banner）然后在打印完成后还原这些更改。一般来说，你应该更倾向于使用 `@media print` CSS at 规则，但在某些情况下可能有必要使用这些事件。

语法
--

在像 `addEventListener()` 的方法中使用事件名称，或设置事件处理属性。

```js
addEventListener("afterprint", (event) => {});
onafterprint = (event) => {};
```

事件类型
----

一个通用的 `Event`。

示例
--

使用 `addEventListener()`：

```js
window.addEventListener("afterprint", (event) => {
  console.log("打印后");
});
```

使用 `onafterprint` 事件处理属性：

```js
window.onafterprint = (event) => {
  console.log("打印后");
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-afterprint |
| HTML Standard # handler-window-onafterprint |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 相关事件：`beforeprint`


Window.scrollTo() - Web API 接口参考

Window.scrollTo()
=================

摘要
--

滚动到文档中的某个坐标。

语法
--
```

window.scrollTo(x-coord,y-coord )

window.scrollTo(options)
```

### 参数

* `x-coord` 是文档中的横轴坐标。
* `y-coord` 是文档中的纵轴坐标。
* `options` 是一个包含三个属性的对象：

1. `top` 等同于 `y-coord`
2. `left` 等同于 `x-coord`
3. `behavior` *类型 String，表示滚动行为，支持参数 smooth(平滑滚动),instant(瞬间滚动),默认值 auto*
例子
--
```

window.scrollTo( 0, 1000 );

// 设置滚动行为改为平滑的滚动
window.scrollTo({
    top: 1000,
    behavior: "smooth"
});
```

注意
--

该函数实际上和 window.scroll (en-US)是一样的。相对滚动可以参考 window.scrollBy (en-US)，window.scrollByLines (en-US)，和 window.scrollByPages。

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-scrollto |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.onappinstalled - Web API 接口参考

Window.onappinstalled
=====================

`Window` 对象的 **`onappinstalled`** 属性用于处理 `appinstalled` 事件，该事件是一个实现了 `Event`接口的简单事件，会在网页应用成功安装为渐进式网页应用时立即触发。

语法
--
```

window.onappinstalled = function(event) { ... };
```

示例
--

```js
window.onappinstalled = function (ev) {
  console.log("The application was installed.");
};
```

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

相关文章
----

* `Event`


window.navigator - Web API 接口参考

window.navigator
================

只读属性 **`Window.navigator`** 会返回一个 `Navigator` 对象的引用，可以用于请求运行当前代码的应用程序的相关信息。

语法
--
```

navigatorObject = window.navigator
```

例子
--

### 例子 #1：检测浏览器并返回浏览器名称字符串

```js
var sBrowser,
  sUsrAg = navigator.userAgent;

// The order matters here, and this may report false positives for unlisted browsers.

if (sUsrAg.indexOf("Firefox") > -1) {
  sBrowser = "Mozilla Firefox";
  // "Mozilla/5.0 (X11; Ubuntu; Linux x86\_64; rv:61.0) Gecko/20100101 Firefox/61.0"
} else if (sUsrAg.indexOf("Opera") > -1 || sUsrAg.indexOf("OPR") > -1) {
  sBrowser = "Opera";
  //"Mozilla/5.0 (Macintosh; Intel Mac OS X 10\_14\_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.102 Safari/537.36 OPR/57.0.3098.106"
} else if (sUsrAg.indexOf("Trident") > -1) {
  sBrowser = "Microsoft Internet Explorer";
  // "Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; .NET4.0C; .NET4.0E; Zoom 3.6.0; wbx 1.0.0; rv:11.0) like Gecko"
} else if (sUsrAg.indexOf("Edge") > -1) {
  sBrowser = "Microsoft Edge";
  // "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36 Edge/16.16299"
} else if (sUsrAg.indexOf("Chrome") > -1) {
  sBrowser = "Google Chrome or Chromium";
  // "Mozilla/5.0 (X11; Linux x86\_64) AppleWebKit/537.36 (KHTML, like Gecko) Ubuntu Chromium/66.0.3359.181 Chrome/66.0.3359.181 Safari/537.36"
} else if (sUsrAg.indexOf("Safari") > -1) {
  sBrowser = "Apple Safari";
  // "Mozilla/5.0 (iPhone; CPU iPhone OS 11\_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/11.0 Mobile/15E148 Safari/604.1 980x1306"
} else {
  sBrowser = "unknown";
}

alert("当前浏览器为：" + sBrowser);
```

### 例子 #2：检测浏览器并返回代表当前浏览器的索引数字

```js
function getBrowserId() {
  var aKeys = ["MSIE", "Firefox", "Safari", "Chrome", "Opera"],
    sUsrAg = navigator.userAgent,
    nIdx = aKeys.length - 1;

  for (nIdx; nIdx > -1 && sUsrAg.indexOf(aKeys[nIdx]) === -1; nIdx--);

  return nIdx;
}

console.log(getBrowserId());
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-navigator |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

*


Window.ondevicemotion - Web API 接口参考

Window.ondevicemotion
=====================

摘要
--

一个发送到窗口的`devicemotion`事件处理程序。

语法
--
```

window.ondevicemotion = funcRef;
```

Where `funcRef` is a reference to a function. This function receives a `DeviceMotionEvent` object describing the motion that occurred.

这里的`funcRef`是一个函数的引用。这个函数接收一个`DeviceMotionEvent` 对象类型的参数描述发生的动作。

规范
--

| Specification |
| --- |
| DeviceOrientation Event Specification # devicemotion |
| DeviceOrientation Event Specification # ref-for-dom-window-ondevicemotion |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参考
--

* `devicemotion`
* `DeviceMotionEvent`
* Detecting device orientation


Window.fullScreen - Web API 接口参考

Window.fullScreen
=================

概述
--

这个属性表明了窗口是否处于全屏模式下。仅在 Gecko 1.9（Firefox 3）以及之后的版本中有意义，详情参见后附备注。

语法
--
```

isInFullScreen = windowRef.fullScreen;
```

在取得 chrome privileges 的情况下，这个属性是可读写的，否则将是只读属性。如果你试图在未取得 chrome privileges 的情况下设置这个属性，虽然实际上修改会失败，却并不会抛出错误。这是为了阻止在 IE 浏览器中意图通过修改这个属性而进行恶意攻击的脚本。

返回值
---

`isInFullScreen`

一个布尔值。可能的值如下：

* `true`: 窗口处于全屏模式下。
* `false`: 窗口未处于全屏模式下。

示例
--
```

if (window.fullScreen) {
    // it's fullscreen!
} else {
    // not fullscreen!
}
```

规范
--

DOM 0 级。window.fullScreen 并不属于任何 W3C 规范或技术推荐中。

备注
--

* 这个属性仅在 Mozilla 1.9（Firefox 3）及之后才有意义。Mozilla 1.8 及早期版本确实有这个属性，但它总是返回 false，即使在窗口确实处于全屏模式的情况下 (Firefox bug 127013)。
* 在常规窗口与全屏窗口之间切换会在相应的窗口中触发“resize”事件。


requestIdleCallback - Web API 接口参考

requestIdleCallback
===================

**`window.requestIdleCallback()`** 方法插入一个函数，这个函数将在浏览器空闲时期被调用。这使开发者能够在主事件循环上执行后台和低优先级工作，而不会影响延迟关键事件，如动画和输入响应。函数一般会按先进先调用的顺序执行，然而，如果回调函数指定了执行超时时间`timeout`，则有可能为了在超时前执行函数而打乱执行顺序。

你可以在空闲回调函数中调用 **`requestIdleCallback()`**，以便在下一次通过事件循环之前调度另一个回调。

**备注：** 强烈建议使用`timeout`选项进行必要的工作，否则可能会在触发回调之前经过几秒钟。

语法
--

```js
requestIdleCallback(callback)
requestIdleCallback(callback, options)
```

### 参数

`callback`

一个在事件循环空闲时即将被调用的函数的引用。函数会接收到一个名为 `IdleDeadline` 的参数，这个参数可以获取当前空闲时间以及回调是否在超时时间前已经执行的状态。

`options` 可选

包括可选的配置参数。具有如下属性：

* `timeout`：如果指定了 timeout，并且有一个正值，而回调在 timeout 毫秒过后还没有被调用，那么回调任务将放入事件循环中排队，即使这样做有可能对性能产生负面影响。

### 返回值

一个 ID，可以把它传入 `Window.cancelIdleCallback()` 方法来结束回调。

示例
--

请阅读我们这篇后台任务 API 的协同调度文章中的完整示例。

规范
--

| Specification |
| --- |
| requestIdleCallback() Cooperative Scheduling of Background Tasks # the-requestidlecallback-method |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

查看更多
----

* `window.cancelIdleCallback()`
* `IdleDeadline`
* `window.setTimeout()`
* `window.setInterval()`
* `window.requestAnimationFrame`


Window：cut 事件 - Web API 接口参考

Window：cut 事件
=============

当用户通过浏览器的用户界面发起一个“剪切”动作时，将触发 **`cut`** 事件。

该事件的原始目标是 `Element`，它是剪切动作的预期目标。你可以在 `Window` 接口上监听这个事件，以便在捕获或冒泡阶段处理它。关于此事件的全部细节，请参见 Element：cut 事件的页面。

语法
--

在类似于 `addEventListener()` 这样的方法中使用事件名，或设置事件处理器属性。

```js
addEventListener("cut", (event) => {});

oncut = (event) => {};
```

事件类型
----

`ClipboardEvent`。继承自 `Event`。

Event

ClipboardEvent示例
--

```js
window.addEventListener("cut", (event) => {
  console.log("已发起剪切！");
});
```

规范
--

| Specification |
| --- |
| Clipboard API and events # clipboard-event-cut |
| HTML Standard # handler-oncut |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 相关联事件：`copy`、`paste`
* `Element` 目标上的这个事件：`cut`
* `Document` 目标上的这个事件：`cut` (en-US)


window.document - Web API 接口参考

window.document
===============

**`window.document`** 返回当前窗口内的文档节点（`document`）

**备注：** 从 Firefox 3 和 IE7 开始，访问其他页面内的文档节点会受到同源策略的影响。

语法
--

```js
doc = window.document;
```

参数
--

* `doc`是一个指向`document`对象的引用
例子
--

```html
<!doctype html>
<html>
  <head>
    <title>Hello, World!</title>
  </head>
  <body>
    <script type="text/javascript">
 var doc = window.document;
 alert(doc.title); // 弹出：Hello, World!
 </script>
  </body>
</html>
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-document-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.sizeToContent() - Web API 接口参考

Window.sizeToContent()
======================

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

**`Window.sizeToContent()`** 方法根据窗口内容调整窗口大小。为了使其工作，在调用此函数时应加载 DOM 内容，例如，一旦抛出 {domxref("Document/DOMContentLoaded\_event", "DOMContentLoaded")}} 事件。

可以强行的调整窗口的最小尺寸。

语法
--

```js
sizeToContent()
```

示例
--

```js
window.sizeToContent();
```

规范
--

此特性不属于任何规范。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `Window`


Window：online 事件 - Web API 接口参考

Window：online 事件
================

当浏览器能够访问网络，且 `Navigator.onLine` (en-US) 的值被设为 `true` 时，`Window` 接口的 **`online`** 事件将被触发。

**备注：** 该事件不能用于确定某个网站可否访问。网站自身问题或防火墙都有可能阻止对特定网站的访问。

|  |  |
| --- | --- |
| 是否冒泡 | 否 |
| 是否可取消 | 否 |
| 接口 | `Event` |
| Event handler property | `ononline` |

示例
--

```js
// addEventListener version
window.addEventListener("online", (event) => {
  console.log("You are now connected to the network.");
});

// ononline version
window.ononline = (event) => {
  console.log("You are now connected to the network.");
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-online |
| HTML Standard # handler-window-ononline |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `offline`


Window：alert() 方法 - Web API 接口参考

Window：alert() 方法
=================

`window.alert()` 令浏览器显示一个带有可选的信息的对话框，并等待用户离开该对话框。

在某些情况下（例如，当用户切换标签时）浏览器可能不会实际显示一个对话框，或者不等待用户离开对话框。

语法
--

```js
alert()
alert(message)
```

### 参数

`message` 可选

是要显示在警告对话框中的字符串，如果传入其他类型的值，会转换成字符串。

### 返回值

无（`undefined`）。

示例
--

```js
window.alert("Hello world!");
alert("Hello world!");
```

都会显示如下：

![黑色警报对话框。在左上方的小圆圈图标后面有白色的开括号和闭括号，包含 JavaScript Application 白色文本。在左下方，有一个“Hello world!”白色的文字。右下方有一个蓝色的小按钮。这个按钮的文字是黑色的 OK](/zh-CN/docs/Web/API/Window/alert/alerthelloworld.png)

注意事项
----

警告对话框应该用于不需要用户做出任何反应的信息，除了对信息的确认之外。

对话框是模态窗口——它们阻止用户访问程序界面的其他部分，直到对话框被关闭。出于这个原因，你不应该过度使用任何创建对话框（或模态窗口）的函数。

另外，`<dialog>` 元素也可用于显示警告。

规范
--

| Specification |
| --- |
| HTML Standard # dom-alert-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `<dialog>` 元素
* `confirm`
* `prompt`


Window：open() 方法 - Web API 接口参考

Window：open() 方法
================

`Window` 接口的 **`open()`** 方法，是用指定的名称将指定的资源加载到新的或已存在的浏览上下文（标签、窗口或 iframe）中。

语法
--

```js
open()
open(url)
open(url, target)
open(url, target, windowFeatures)
```

### 参数

* `url` 可选
    + : 一个字符串，表示要加载的资源的 URL 或路径。如果指定空字符串（`""`）或省略此参数，则会在目标浏览上下文中打开一个空白页。
* `target` 可选
    + : 一个不含空格的字符串，用于指定加载资源的浏览上下文的名称。如果该名称无法识别现有的上下文，则会创建一个新的上下文，并赋予指定的名称。还可以使用特殊的 `target` 关键字：`_self`、`_blank`、`_parent` 和 `_top`。该名称可用作 `<a>` 或 `<form>` 元素的 `target` 属性。
* `windowFeatures` 可选
    + : 一个字符串，包含以逗号分隔的窗口特性列表，形式为 `name=value`，布尔特性则仅为 `name`。这些特性包括窗口的默认大小和位置、是否打开最小弹出窗口等选项。支持以下选项：

    `popup`

    如果启用此特性，则要求使用最小弹出窗口。弹出窗口中包含的用户界面功能将由浏览器自动决定，一般只包括地址栏。

    如果未启用 `popup`，也没有声明窗口特性，则新的浏览上下文将是一个标签页。

    **备注：** 在 `windowFeatures` 参数中指定除 `noopener` 或 `noreferrer` 以外的任何特性，也会产生请求弹出窗口的效果。

    要启用该特性，可以不指定 `popup` 值，或将其设置为 `yes`, `1` 或 `true`。

    例如：`popup=yes`、`popup=1`、`popup=true` 和`popup` 的结果完全相同。

    `width` 或 `innerWidth`

    指定内容区域（包括滚动条）的宽度。最小要求值为 100。

    `height` 或 `innerHeight`

    指定内容区域（包括滚动条）的高度。最小要求值为 100。

    `left` 或 `screenX`

    指定从用户操作系统定义的工作区左侧到新窗口生成位置的距离（以像素为单位）。

    `top` 或 `screenY`

    指定从用户操作系统定义的工作区顶部到新窗口生成位置的距离（以像素为单位）。

    `noopener`

    如果设置了此特性，新窗口将无法通过 `Window.opener` 访问原窗口，并返回 `null`。

    使用 `noopener` 时，在决定是否打开新的浏览上下文时，除 `_top`、`_self` 和 `_parent` 以外的非空目标名称会像 `_blank` 一样处理。

    `noreferrer`

    如果设置了此特性，浏览器将省略 `Referer` 标头，并将 `noopener` 设为 true。更多信息请参阅 `rel="noreferrer"` (en-US) 。

**备注：** `windowFeatures` 中要求的位置（`top`、`left`）和尺寸（`width`、`height`）值，如果其中任何一个值不允许在用户操作系统应用程序的工作区内呈现整个浏览器弹出窗口，**则将被更正**。换句话说，新弹出窗口的任何部分最初都不能置于屏幕之外。

### 返回值

一个 `WindowProxy` (en-US) 对象。只要符合同源策略安全要求，返回的引用就可用于访问新窗口的属性和方法。

描述
--

`Window` 接口的 `open()` 方法将 URL 作为参数，并将其识别的资源加载到新的或现有的标签页或窗口中。`target` 参数决定将资源加载到哪个窗口或标签页，`windowFeatures` 参数可用于控制打开一个具有最少用户界面功能的新弹出窗口，并控制其大小和位置。

请注意，远程 URL 不会立即加载。当 `window.open()` 返回时，窗口总是包含 `about:blank`。URL 的实际获取是延迟进行的，并在当前脚本块执行完毕后开始。窗口创建和引用资源的加载是异步进行的。

示例
--

### 打开一个新标签页

```js
window.open("https://www.mozilla.org/", "mozillaTab");
```

### 打开一个弹出窗口

另外，下面的示例演示了如何使用 `popup` 特性打开弹出窗口。

**警告：** 现代浏览器已内置弹出窗口阻止程序，将弹出窗口的打开限制在直接响应用户输入的情况下。在点击之外打开的弹出窗口可能会显示通知，让用户选择启用或放弃。

```js
window.open("https://www.mozilla.org/", "mozillaWindow", "popup");
```

可以控制新弹出窗口的大小和位置：

```js
const windowFeatures = "left=100,top=100,width=320,height=320";
const handle = window.open(
  "https://www.mozilla.org/",
  "mozillaWindow",
  windowFeatures,
);
if (!handle) {
  // 不允许打开此窗口
  // 可能被内置弹窗阻止程序阻止了
  // …
}
```

渐进增强
----

在某些情况下，JavaScript 被禁用或不可用，`window.open()` 将无法工作。我们可以提供替代解决方案，使网站或应用程序仍能正常运行，而不是完全依赖于该特性的存在。

### 在禁用 JavaScript 时提供替代方法

如果 JavaScript 支持被禁用或不存在，那么用户代理将相应地创建一个辅助窗口，或根据其对 `target` 属性的处理方式来渲染所引用的资源。我们的目标和想法是向用户提供（而不是*强迫*）一种打开引用资源的方式。

#### HTML

```html
<a href="https://www.wikipedia.org/" target="OpenWikipediaWindow">
  维基百科，自由的百科全书（在其他可能存在的标签页中打开）
</a>
```

#### JavaScript

```js
let windowObjectReference = null; // 全局变量
function openRequestedTab(url, windowName) {
  if (windowObjectReference === null || windowObjectReference.closed) {
    windowObjectReference = window.open(url, windowName);
  } else {
    windowObjectReference.focus();
  }
}

const link = document.querySelector("a[target='OpenWikipediaWindow']");
link.addEventListener(
  "click",
  (event) => {
    openRequestedTab(link.href);
    event.preventDefault();
  },
  false,
);
```

上述代码解决了一些与链接打开弹出窗口有关的可用性问题。代码中的 `event.preventDefault()` 的目的是取消链接的默认操作：如果执行了 `click` 的事件监听器，则无需执行链接的默认操作。但如果用户的浏览器禁用或不支持 JavaScript，则会忽略 `click` 的事件监听器，浏览器会在名称为 `"WikipediaWindowName"` 的目标框架或窗口中加载引用的资源。如果没有名称为 `"WikipediaWindowName"` 的框架或窗口，浏览器将创建一个新窗口并将其命名为 `"WikipediaWindowName"`。

**备注：** 有关 `target` 属性的更多细节，请参阅 `<a>` 或 `<form>`。

### 复用已有窗口，避免 `target="_blank"`

使用 `"_blank"` 作为 target 属性值会在用户桌面上创建多个新的无名窗口，这些窗口无法循环使用或重复使用。请尝试为 `target` 属性提供一个有意义的名称，并在页面上重复使用这样的 `target` 属性，这样点击另一个链接就可以在一个已经创建和渲染的窗口中加载引用的资源（因此可以加快用户的操作速度），从而证明首先创建一个辅助窗口是合理的（以及用户系统资源和时间的消耗）。在链接中使用单个 `target` 属性值并重复使用该属性值对用户资源更为友好，因为它只创建一个二级窗口，并可循环使用。

下面是一个可以打开二级窗口并重复用于其他链接的示例：

#### HTML

```html
<p>
  <a href="https://www.wikipedia.org/" target="SingleSecondaryWindowName">
    维基百科，自由的百科全书（在其他可能存在的标签页中打开）
  </a>
</p>
<p>
  <a
 href="https://support.mozilla.org/products/firefox"
 target="SingleSecondaryWindowName">
    Firefox 疑难解答（在其他可能存在的标签页中打开）
  </a>
</p>
```

#### JavaScript

```js
let windowObjectReference = null; // 全局变量
let previousURL; /\* 全局变量，用于存储当前二级窗口中的网址 \*/
function openRequestedSingleTab(url) {
  if (windowObjectReference === null || windowObjectReference.closed) {
    windowObjectReference = window.open(url, "SingleSecondaryWindowName");
  } else if (previousURL !== url) {
    windowObjectReference = window.open(url, "SingleSecondaryWindowName");
    /\* 如果要加载的资源是不同的，则我们会将其加载到已打开的辅助窗口中，然后将该窗口拉回到其父窗口的顶部或前面。\*/
    windowObjectReference.focus();
  } else {
    windowObjectReference.focus();
  }
  previousURL = url;
  /\* 解释：我们存储当前的 url，以便在再次调用此函数时对 url
 进行比较。 \*/
}

const links = document.querySelectorAll(
  "a[target='SingleSecondaryWindowName']",
);
for (const link of links) {
  link.addEventListener(
    "click",
    (event) => {
      openRequestedSingleTab(link.href);
      event.preventDefault();
    },
    false,
  );
}
```

同源策略
----

如果新打开的浏览上下文不共享相同的源，则打开脚本将无法与浏览上下文的内容进行交互（读取或写入）。

```js
// 来自 example.com 的脚本
const otherOriginContext = window.open("https://example.org");
// example.com 和 example.org 是非同源的

console.log(otherOriginContext.origin);
// DOMException: Permission denied to access property "origin" on cross-origin object
```

```js
// 来自 example.com 的脚本
const sameOriginContext = window.open("https://example.com");
// 此时，新的浏览上下文是同源的

console.log(sameOriginContext.origin);
// https://example.com
```

如需了解更多信息，请参阅同源策略一文。

无障碍
---

### 避免使用 window.open()

出于多种原因，最好不要使用 `window.open()`：

* 现代浏览器提供弹出窗口阻止功能。
* 现代浏览器提供选项卡浏览功能，而支持选项卡功能的浏览器用户在大多数情况下更喜欢打开新选项卡，而不是打开新窗口。
* 用户可以使用浏览器的内置功能或扩展功能来选择在新窗口、同一窗口、新标签页、同一标签页或后台打开链接。使用 `window.open()` 强制以特定方式打开链接会使用户感到困惑，并忽略他们的习惯。
* 弹出窗口没有菜单工具栏，而新标签页使用浏览器窗口的用户界面；因此，许多用户更喜欢标签页浏览，因为界面保持稳定。
### 避免在 HTML 代码中内联使用 window.open()

避免 `<a href="#" onclick="window.open(…);">` 或 `<a href="javascript:window\.open(…)" …>`。

当复制/拖动链接、在新标签/窗口中打开链接、添加书签时，或者当 JavaScript 正在加载、出错或禁用时，这些虚假的 `href` 值会导致意外的行为。它们还会向屏幕阅读器等辅助技术传达不正确的语义。

如有必要，请使用 `<button>` 元素代替。一般来说，*只应使用链接导航到真正的 URL*。

### 始终指明指向二级窗口的链接

指明可打开新窗口的链接，以帮助用户导航。

```html
<a target="WikipediaWindow" href="https://www.wikipedia.org">
  维基百科（在新标签页打开）
</a>
```

这样做的目的是在上下文发生变化时向用户发出警告，以尽量减少用户的困惑：改变当前窗口或弹出新的窗口会让用户感到非常迷惑（在弹出窗口的情况下，没有工具栏提供返回上一个窗口的“上一页”按钮）。

如果在上下文发生极端变化之前就明确指出，那么用户就可以决定是否要继续使用，或者为这种变化做好准备：他们不仅不会感到困惑或迷失方向，而且更有经验的用户还可以更好地决定如何打开这些链接（是否在新窗口、是否在同一窗口、是否在新标签页、是否“在后台”）。

* WebAIM：链接与超文本——超文本链接
* MDN / 理解 WCAG，指南 3.2 (en-US)
* G200：只在必要时从链接打开新窗口和标签页
* G201：打开新窗口时，给用户额外提示
规范
--

| Specification |
| --- |
| HTML Standard # dom-open-dev |
| CSSOM View Module # the-features-argument-to-the-open()-method |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `target` 属性文档：
    + `<a>`
    + `<form>`
* `window.close()`
* `window.closed`
* `window.focus()`
* `window.opener`
* `rel="opener"` 和 `rel="noopener"`
* 同源策略


unload - Web API 接口参考

unload
======

当文档或一个子资源正在被卸载时，触发 **`unload`** 事件。

|  |  |
| --- | --- |
| 可冒泡（Bubbles） | No |
| 可取消（Cancelable） | No |
| 接口（Interface） | `Event` |
| 事件处理程序属性（Event handler property） | `onunload` |

它在下面两个事件后被触发：

1. beforeunload (en-US) (可取消默认行为的事件)
2. pagehide (en-US)

文档处于以下状态：

* 所有资源仍存在 (图片，iframe 等.)
* 对于终端用户所有资源均不可见
* 界面交互无效 (`window.open`, `alert`, `confirm` 等.)
* 错误不会停止卸载文档的过程

请注意`unload`事件也遵循文档树：父 iframe 会在子 iframe 卸载前卸载 (参考下面的例子).

示例
--

```html
<!doctype html>
<html>
  <head>
    <title>Parent Frame</title>
    <script>
 window.addEventListener("beforeunload", function (event) {
 console.log("I am the 1st one.");
 });
 window.addEventListener("unload", function (event) {
 console.log("I am the 3rd one.");
 });
 </script>
  </head>
  <body>
    <iframe src="child-frame.html"></iframe>
  </body>
</html>
```

下面是 `child-frame.html 的内容`:

```html
<!doctype html>
<html>
  <head>
    <title>Child Frame</title>
    <script>
 window.addEventListener("beforeunload", function (event) {
 console.log("I am the 2nd one.");
 });
 window.addEventListener("unload", function (event) {
 console.log("I am the 4th and last one…");
 });
 </script>
  </head>
  <body>
    ☻
  </body>
</html>
```

当父 iframe 被卸载，事件将按 `console.log()` 消息描述的顺序触发。

规范
--

| Specification |
| --- |
| HTML Standard # event-unload |
| HTML Standard # handler-window-onunload |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 相关事件：`DOMContentLoaded`、`readystatechange`、`load`
* Unloading Documents — unload a document


Window.close() - Web API 接口参考

Window.close()
==============

**`Window.close()`** 方法关闭当前窗口或某个指定的窗口。

该方法只能由 `Window.open()` 方法打开的窗口的 `window` 对象来调用。如果一个窗口不是由脚本打开的，那么，在调用该方法时，JavaScript 控制台会出现类似下面的错误：`不能使用脚本关闭一个不是由脚本打开的窗口。` 或 `Scripts may not close windows that were not opened by script.` 。

同时也要注意，对于由 `HTMLIFrameElement.contentWindow` 返回的 `Window` 对象，`close()` 也没有效果。

语法
--
```

window.close();
```

例子
--

### 关闭一个由 `window.open()`方法打开的窗口

这个例子展示了如何使用这个方法关闭使用 `window.open()` 打开的窗口

```js
// 用于存储将要打开的窗口（的引用）的全局变量
var openedWindow;

function openWindow() {
  openedWindow = window.open("moreinfo.htm");
}

function closeOpenedWindow() {
  openedWindow.close();
}
```

### 关闭当前窗口

当直接调用 window 对象的 `close()` 方法而非在一个 window 实例上调用 `close()` 时，浏览器会关闭最前面的窗口，无论是不是你的脚本创建的这个窗口。（Firefox 35.0.1：脚本不能关闭不是他打开的窗口）

```js
function closeCurrentWindow() {
  window.close();
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-window-close-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


window.parent - Web API 接口参考

window.parent
=============

### 概述

返回当前窗口的父窗口对象。

如果一个窗口没有父窗口，则它的 `parent` 属性为自身的引用。

如果当前窗口是一个 `<iframe>`, `<object>`, 或者 `<frame>`,则它的父窗口是嵌入它的那个窗口

### 语法
```

var parentWindow = window.parent;
```

### 例子
```

if (window.parent != window.top) {
  // 至少有三层窗口
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-parent-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `window.frameElement` 返回嵌入当前窗口的 frame 对象。
* `window.top` 返回当前窗口最顶层的父窗口。


Window.outerWidth - Web API 接口参考

Window.outerWidth
=================

概述
--

`Window.outerWidth` 获取浏览器窗口外部的宽度。表示整个浏览器窗口的宽度，包括侧边栏（如果存在）、窗口镶边（window chrome）和调正窗口大小的边框（window resizing borders/handles）。

该属性为只读，没有默认值。

语法
--
```

outWindowWidth = window.outerWidth;
```

`outWindowWidth` 是窗口的外层的宽度。

备注
--

要改变一个窗口的大小，可参考 `window.resizeBy()` 和 `window.resizeTo()`。

要获取一个窗口的内层宽度（inner width），即页面被展示的区域，请参考 `window.innerWidth`。

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

规范
--

DOM Level 0。不属于任何 W3C 技术规范或推荐。the To do in Notes

相关链接
----

* `window.outerHeight`, `window.innerHeight`, `window.innerWidth`
* `window.resizeBy()`, `window.resizeTo()`


Window：location 属性 - Web API 接口参考

Window：location 属性
==================

**`Window.location`** 只读属性返回一个 `Location` 对象，其中包含有关文档当前位置的信息。

尽管 `Window.location` 是一个*只读* `Location` 对象，你仍然可以将字符串赋值给它。这意味着可以在大多数情况下像字符串一样处理 `location`——`location = 'http://www.example.com'`——与 `location.href = 'http://www.example.com'` 等价。

参见 `Location` 的文档以查看所有可能的属性值。

值
-

一个 `Location` 对象。

示例
--

### 简单示例

```js
alert(location);
// 弹出“https://developer.mozilla.org/zh-CN/docs/Web/API/window.location”
```

### 示例 1：导航到一个新页面

只要赋给 location 对象一个新值，文档就会使用新的 URL 加载，就好像使用修改后的 URL 调用了 `location.assign()` 一样。

请注意，与导航相关的沙箱标志可能会导致抛出异常和导航失败。

```js
location.assign("https://www.mozilla.org"); // 或
location = "https://www.mozilla.org";
```

### 示例 2：重新加载当前页面

```js
location.reload();
```

### 示例 3

考虑下面的示例，该例使用 `replace()` 方法重新加载页面，并将 `location.pathname` 的值插入到 hash：

```js
function reloadPageWithHash() {
  location.replace(`https://example.com/#${location.pathname}`);
}
```

### 示例 4：弹出警告框，显示当前 URL 的属性：

```js
function showLoc() {
  const logLines = [
    "属性（类型）值",
    `location (${typeof location})：${location}`,
  ];
  for (const prop in location) {
    logLines.push(
      `${prop} (${typeof location[prop]})：${location[prop] || "n/a"}`,
    );
  }
  alert(logLines.join("\n"));
}

// HTML 代码形式：<button onclick="showLoc();">显示 location 属性</button>
```

### 示例 5：通过修改 `search` 属性向服务器发送字符串数据：

```js
function sendData(data) {
  location.search = data;
}

// HTML 代码形式：<button onclick="sendData('一些数据');">发送数据</button>
```

当前 URL 将带上“?Some%20data”发送到服务端（如果服务端不处理，则使用修改后的查询字符串重新加载当前文档）。

### 示例 6：不改变 `hash` 属性情况下使用书签

```html
<!doctype html>
<html lang="en-US">
  <head>
    <meta charset="UTF-8" />
    <title>MDN 示例</title>
    <script>
 function showNode(node) {
 document.documentElement.scrollTop = node.offsetTop;
 document.documentElement.scrollLeft = node.offsetLeft;
 }

 function showBookmark(bookmark, useHash) {
 if (arguments.length === 1 || useHash) {
 location.hash = bookmark;
 return;
 }
 const bookmarkElement = document.querySelector(bookmark);
 if (bookmarkElement) {
 showNode(bookmarkElement);
 }
 }
 </script>
    <style>
 span.intLink {
 cursor: pointer;
 color: #0000ff;
 text-decoration: underline;
 }
 </style>
  </head>

  <body>
    <p>
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam ultrices
      dolor ac dolor imperdiet ullamcorper. Suspendisse quam libero, luctus
      auctor mollis sed, malesuada condimentum magna. Quisque in ante tellus, in
      placerat est. Pellentesque habitant morbi tristique senectus et netus et
      malesuada fames ac turpis egestas. Donec a mi magna, quis mattis dolor.
      Etiam sit amet ligula quis urna auctor imperdiet nec faucibus ante. Mauris
      vel consectetur dolor. Nunc eget elit eget velit pulvinar fringilla
      consectetur aliquam purus. Curabitur convallis, justo posuere porta
      egestas, velit erat ornare tortor, non viverra justo diam eget arcu.
      Phasellus adipiscing fermentum nibh ac commodo. Nam turpis nunc, suscipit
      a hendrerit vitae, volutpat non ipsum.
    </p>
    <p>
      Duis lobortis sapien quis nisl luctus porttitor. In tempor semper libero,
      eu tincidunt dolor eleifend sit amet. Ut nec velit in dolor tincidunt
      rhoncus non non diam. Morbi auctor ornare orci, non euismod felis gravida
      nec. Curabitur elementum nisi a eros rutrum nec blandit diam placerat.
      Aenean tincidunt risus ut nisi consectetur cursus. Ut vitae quam elit.
      Donec dignissim est in quam tempor consequat. Aliquam aliquam diam non
      felis convallis suscipit. Nulla facilisi. Donec lacus risus, dignissim et
      fringilla et, egestas vel eros. Duis malesuada accumsan dui, at fringilla
      mauris bibendum quis. Cras adipiscing ultricies fermentum. Praesent
      bibendum condimentum feugiat.
    </p>
    <p id="myBookmark1">
      [ <span class="intLink" onclick="showBookmark('#myBookmark2');"
 >前往 2 号书签</span
 > ]
    </p>
    <p>
      Vivamus blandit massa ut metus mattis in fringilla lectus imperdiet. Proin
      ac ante a felis ornare vehicula. Fusce pellentesque lacus vitae eros
      convallis ut mollis magna pellentesque. Pellentesque placerat enim at
      lacus ultricies vitae facilisis nisi fringilla. In tincidunt tincidunt
      tincidunt. Nulla vitae tempor nisl. Etiam congue, elit vitae egestas
      mollis, ipsum nisi malesuada turpis, a volutpat arcu arcu id risus.
    </p>
    <p>
      Nam faucibus, ligula eu fringilla pulvinar, lectus tellus iaculis nunc,
      vitae scelerisque metus leo non metus. Proin mattis lobortis lobortis.
      Quisque accumsan faucibus erat, vel varius tortor ultricies ac. Lorem
      ipsum dolor sit amet, consectetur adipiscing elit. Sed nec libero nunc.
      Nullam tortor nunc, elementum a consectetur et, ultrices eu orci. Lorem
      ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque a nisl eu
      sem vehicula egestas.
    </p>
    <p>
      Aenean viverra varius mauris, sed elementum lacus interdum non. Phasellus
      sit amet lectus vitae eros egestas pellentesque fermentum eget magna.
      Quisque mauris nisl, gravida vitae placerat et, condimentum id metus.
      Nulla eu est dictum dolor pulvinar volutpat. Pellentesque vitae
      sollicitudin nunc. Donec neque magna, lobortis id egestas nec, sodales
      quis lectus. Fusce cursus sollicitudin porta. Suspendisse ut tortor in
      mauris tincidunt rhoncus. Maecenas tincidunt fermentum facilisis.
      Pellentesque habitant morbi tristique senectus et netus et malesuada fames
      ac turpis egestas.
    </p>
    <p>
      Suspendisse turpis nisl, consectetur in lacinia ut, ornare vel mi. Lorem
      ipsum dolor sit amet, consectetur adipiscing elit. Proin non lectus eu
      turpis vulputate cursus. Mauris interdum tincidunt erat id pharetra.
      Nullam in libero elit, sed consequat lectus. Morbi odio nisi, porta vitae
      molestie ut, gravida ut nunc. Ut non est dui, id ullamcorper orci.
      Praesent vel elementum felis. Maecenas ornare, dui quis auctor hendrerit,
      turpis sem ullamcorper odio, in auctor magna metus quis leo. Morbi at odio
      ante.
    </p>
    <p>
      Curabitur est ipsum, porta ac viverra faucibus, eleifend sed eros. In sit
      amet vehicula tortor. Vestibulum viverra pellentesque erat a elementum.
      Integer commodo ultricies lorem, eget tincidunt risus viverra et. In enim
      turpis, porttitor ac ornare et, suscipit sit amet nisl. Vestibulum ante
      ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae;
      Pellentesque vel ultrices nibh. Sed commodo aliquam aliquam. Nulla
      euismod, odio ut eleifend mollis, nisi dui gravida nibh, vitae laoreet
      turpis purus id ipsum. Donec convallis, velit non scelerisque bibendum,
      diam nulla auctor nunc, vel dictum risus ipsum sit amet est. Praesent ut
      nibh sit amet nibh congue pulvinar. Suspendisse dictum porttitor tempor.
    </p>
    <p>
      Vestibulum dignissim erat vitae lectus auctor ac bibendum eros semper.
      Integer aliquet, leo non ornare faucibus, risus arcu tristique dolor, a
      aliquet massa mauris quis arcu. In porttitor, lectus ac semper egestas,
      ligula magna laoreet libero, eu commodo mauris odio id ante. In hac
      habitasse platea dictumst. In pretium erat diam, nec consequat eros.
      Praesent augue mi, consequat sed porttitor at, volutpat vitae eros. Sed
      pretium pharetra dapibus. Donec auctor interdum erat, lacinia molestie
      nibh commodo ut. Maecenas vestibulum vulputate felis, ut ullamcorper arcu
      faucibus in. Curabitur id arcu est. In semper mollis lorem at
      pellentesque. Sed lectus nisl, vestibulum id scelerisque eu, feugiat et
      tortor. Pellentesque porttitor facilisis ultricies.
    </p>
    <p id="myBookmark2">
      [ <span class="intLink" onclick="showBookmark('#myBookmark1');"
 >前往 1 号书签</span
 >
      |
      <span class="intLink" onclick="showBookmark('#myBookmark1', false);"
 >不使用 location.hash 前往 1 号书签</span
 >
      |
      <span class="intLink" onclick="showBookmark('#myBookmark3');"
 >前往 3 号书签</span
 > ]
    </p>
    </p>
    <p>
      Fusce cursus pulvinar aliquam. Duis justo enim, ornare vitae elementum
      sed, porta a quam. Aliquam eu enim eu libero mollis tempus. Morbi ornare
      aliquam posuere. Proin faucibus luctus libero, sed ultrices lorem sagittis
      et. Vestibulum malesuada, ante nec molestie vehicula, quam diam mollis
      ipsum, rhoncus posuere mauris lectus in eros. Nullam feugiat ultrices
      augue, ac sodales sem mollis in.
    </p>
    <p id="myBookmark3"><em>Here is the bookmark #3</em></p>
    <p>
      Proin vitae sem non lorem pellentesque molestie. Nam tempus massa et
      turpis placerat sit amet sollicitudin orci sodales. Pellentesque enim
      enim, sagittis a lobortis ut, tempus sed arcu. Aliquam augue turpis,
      varius vel bibendum ut, aliquam at diam. Nam lobortis, dui eu hendrerit
      pellentesque, sem neque porttitor erat, non dapibus velit lectus in metus.
      Vestibulum sit amet felis enim. In quis est vitae nunc malesuada consequat
      nec nec sapien. Suspendisse aliquam massa placerat dui lacinia luctus sed
      vitae risus. Fusce tempus, neque id ultrices volutpat, mi urna auctor
      arcu, viverra semper libero sem vel enim. Mauris dictum, elit non placerat
      malesuada, libero elit euismod nibh, nec posuere massa arcu eu risus.
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer urna
      velit, dapibus eget varius feugiat, pellentesque sit amet ligula. Maecenas
      nulla nisl, facilisis eu egestas scelerisque, mollis eget metus.
      Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere
      cubilia Curae; Morbi sed congue mi.
    </p>
    <p>
      Fusce metus velit, pharetra at vestibulum nec, facilisis porttitor mi.
      Curabitur ligula sapien, fermentum vel porttitor id, rutrum sit amet
      magna. Sed sit amet sollicitudin turpis. Aenean luctus rhoncus dolor, et
      pulvinar ante egestas et. Donec ac massa orci, quis dapibus augue. Vivamus
      consectetur auctor pellentesque. Praesent vestibulum tincidunt ante sed
      consectetur. Cum sociis natoque penatibus et magnis dis parturient montes,
      nascetur ridiculus mus. Fusce purus metus, imperdiet vitae iaculis
      convallis, bibendum vitae turpis.
    </p>
    <p>
      Fusce aliquet molestie dolor, in ornare dui sodales nec. In molestie
      sollicitudin felis a porta. Mauris nec orci sit amet orci blandit
      tristique congue nec nunc. Praesent et tellus sollicitudin mauris accumsan
      fringilla. Morbi sodales, justo eu sollicitudin lacinia, lectus sapien
      ullamcorper eros, quis molestie urna elit bibendum risus. Proin eget
      tincidunt quam. Nam luctus commodo mauris, eu posuere nunc luctus non.
      Nulla facilisi. Vivamus eget leo rhoncus quam accumsan fringilla. Aliquam
      sit amet lorem est. Nullam vel tellus nibh, id imperdiet orci. Integer
      egestas leo eu turpis blandit scelerisque.
    </p>
    <p>
      Etiam in blandit tellus. Integer sed varius quam. Vestibulum dapibus mi
      gravida arcu viverra blandit. Praesent tristique augue id sem adipiscing
      pellentesque. Sed sollicitudin, leo sed interdum elementum, nisi ante
      condimentum leo, eget ornare libero diam semper quam. Vivamus augue urna,
      porta eget ultrices et, dapibus ut ligula. Ut laoreet consequat faucibus.
      Praesent at lectus ut lectus malesuada mollis. Nam interdum adipiscing
      eros, nec sodales mi porta nec. Proin et quam vitae sem interdum aliquet.
      Proin vel odio at lacus vehicula aliquet.
    </p>
    <p>
      Etiam placerat dui ut sem ornare vel vestibulum augue mattis. Sed semper
      malesuada mi, eu bibendum lacus lobortis nec. Etiam fringilla elementum
      risus, eget consequat urna laoreet nec. Etiam mollis quam non sem
      convallis vel consectetur lectus ullamcorper. Aenean mattis lacus quis
      ligula mattis eget vestibulum diam hendrerit. In non placerat mauris.
      Praesent faucibus nunc quis eros sagittis viverra. In hac habitasse platea
      dictumst. Suspendisse eget nisl erat, ac molestie massa. Praesent mollis
      vestibulum tincidunt. Fusce suscipit laoreet malesuada. Aliquam erat
      volutpat. Aliquam dictum elementum rhoncus. Praesent in est massa,
      pulvinar sodales nunc. Pellentesque gravida euismod mi ac convallis.
    </p>
    <p>
      Mauris vel odio vel nulla facilisis lacinia. Aliquam ultrices est at leo
      blandit tincidunt. Vestibulum ante ipsum primis in faucibus orci luctus et
      ultrices posuere cubilia Curae; Suspendisse porttitor adipiscing
      facilisis. Duis cursus quam iaculis augue interdum porttitor. Vestibulum
      ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia
      Curae; Duis vulputate magna ac metus pretium condimentum. In tempus, est
      eget vestibulum blandit, velit massa dignissim nisl, ut scelerisque lorem
      neque vel velit. Maecenas fermentum commodo viverra. Curabitur a nibh non
      velit aliquam cursus. Integer semper condimentum tortor a pellentesque.
      Pellentesque semper, nisl id porttitor vehicula, sem dui feugiat lacus,
      vitae consequat augue urna vel odio.
    </p>
    <p>
      Vestibulum id neque nec turpis iaculis pulvinar et a massa. Vestibulum sed
      nibh vitae arcu eleifend egestas. Mauris fermentum ultrices blandit.
      Suspendisse vitae lorem libero. Aenean et pellentesque tellus. Morbi quis
      neque orci, eu dignissim dui. Fusce sollicitudin mauris ac arcu vestibulum
      imperdiet. Proin ultricies nisl sit amet enim imperdiet eu ornare dui
      tempus. Maecenas lobortis nisi a tortor vestibulum vel eleifend tellus
      vestibulum. Donec metus sapien, hendrerit a fermentum id, dictum quis
      libero.
    </p>
    <p>
      Pellentesque a lorem nulla, in tempor justo. Duis odio nisl, dignissim sed
      consequat sit amet, hendrerit ac neque. Nunc ac augue nec massa tempor
      rhoncus. Nam feugiat, tellus a varius euismod, justo nisl faucibus velit,
      ut vulputate justo massa eu nibh. Sed bibendum urna quis magna facilisis
      in accumsan dolor malesuada. Morbi sit amet nunc risus, in faucibus sem.
      Nullam sollicitudin magna sed sem mollis id commodo libero condimentum.
      Duis eu massa et lacus semper molestie ut adipiscing sem.
    </p>
    <p>
      Sed id nulla mi, eget suscipit eros. Aliquam tempus molestie rutrum. In
      quis varius elit. Nullam dignissim neque nec velit vulputate porttitor.
      Mauris ac ligula sit amet elit fermentum rhoncus. In tellus urna, pulvinar
      quis condimentum ut, porta nec justo. In hac habitasse platea dictumst.
      Proin volutpat elit id quam molestie ac commodo lacus sagittis. Quisque
      placerat, augue tempor placerat pulvinar, nisi nisi venenatis urna, eget
      convallis eros velit quis magna. Suspendisse volutpat iaculis quam, ut
      tristique lacus luctus quis.
    </p>
    <p>
      Nullam commodo suscipit lacus non aliquet. Phasellus ac nisl lorem, sed
      facilisis ligula. Nam cursus lobortis placerat. Sed dui nisi, elementum eu
      sodales ac, placerat sit amet mauris. Pellentesque dapibus tellus ut ipsum
      aliquam eu auctor dui vehicula. Quisque ultrices laoreet erat, at ultrices
      tortor sodales non. Sed venenatis luctus magna, ultricies ultricies nunc
      fringilla eget. Praesent scelerisque urna vitae nibh tristique varius
      consequat neque luctus. Integer ornare, erat a porta tempus, velit justo
      fermentum elit, a fermentum metus nisi eu ipsum. Vivamus eget augue vel
      dui viverra adipiscing congue ut massa. Praesent vitae eros erat, pulvinar
      laoreet magna. Maecenas vestibulum mollis nunc in posuere. Pellentesque
      sit amet metus a turpis lobortis tempor eu vel tortor. Cras sodales
      eleifend interdum.
    </p>
  </body>
</html>
```

下面代码做同样的事，但是页面滚动带有动画效果：

```js
const showBookmark = (() => {
  let _useHash;
  let _scrollX;
  let _scrollY;
  let _nodeX;
  let _nodeY;
  let _itFrame;
  let _scrollId = -1;
  let _bookMark;

  // duration：每帧的毫秒数
  // frames：每个滚动下的帧数
  let duration = 200;
  let frames = 10;

  function \_next() {
    if (_itFrame > frames) {
      clearInterval(_scrollId);
      _scrollId = -1;
      return;
    }
    _isBot = true;
    document.documentElement.scrollTop = Math.round(
      _scrollY + ((_nodeY - _scrollY) \* _itFrame) / frames,
    );
    document.documentElement.scrollLeft = Math.round(
      _scrollX + ((_nodeX - _scrollX) \* _itFrame) / frames,
    );
    if (_useHash && _itFrame === frames) {
      location.hash = _bookMark;
    }
    _itFrame++;
  }

  function \_chkOwner() {
    if (_isBot) {
      _isBot = false;
      return;
    }
    if (_scrollId > -1) {
      clearInterval(_scrollId);
      _scrollId = -1;
    }
  }

  window.addEventListener("scroll", _chkOwner, false);

  return (bookmark, useHash) => {
    const node = document.querySelector(bookmark);
    _scrollY = document.documentElement.scrollTop;
    _scrollX = document.documentElement.scrollLeft;
    _bookMark = bookmark;
    _useHash = useHash === true;
    _nodeX = node.offsetLeft;
    _nodeY = node.offsetTop;
    _itFrame = 1;
    if (_scrollId === -1) {
      _scrollId = setInterval(_next, Math.round(duration / frames));
    }
  };
})();
```

规范
--

| Specification |
| --- |
| HTML Standard # the-location-interface |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 返回值所在的 `Location` 接口
* 含有相似信息，但在文档对象中的 `Document.location`。
* 修改浏览器历史记录
* `hashchange`


Window.scroll() - Web API 接口参考

Window.scroll()
===============

概述
--

滚动窗口至文档中的特定位置。

语法
--
```

window.scroll(x-coord, y-coord)
window.scroll(options)
```

### 参数

* `x-coord` 值表示你想要置于左上角的像素点的横坐标。
* `y-coord` 值表示你想要置于左上角的像素点的纵坐标。

- 或者 -

* `options` 值是一个 `ScrollToOptions` 字典
示例
--

```html
<!-- 把纵轴上第 100 个像素置于窗口顶部 -->

<button onClick="scroll(0, 100);">点击以向下滚动 100 像素</button>
```

使用 `options`:

```js
window.scroll({
  top: 100,
  left: 100,
  behavior: "smooth",
});
```

备注
--

window.scrollTo 实际上和该方法是相同的。想要重复地滚动某个距离，请使用 window.scrollBy. 参见 window.scrollByLines, window.scrollByPages.

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-scroll |


Window.screenX - Web API 接口参考

Window.screenX
==============

概述
--

返回浏览器左边界到操作系统桌面左边界的水平距离。

语法
--
```

lLoc = window.screenX
```

* `lLoc` 为浏览器左边到系统桌面左边的像素值
规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-screenx |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `Window.screenY`


Window.mozInnerScreenX - Web API 接口参考

Window.mozInnerScreenX
======================

概要
--

在屏幕坐标中获取窗口视口左上角的 X 坐标

**备注：** 该坐标以 CSS 像素报告显示，而不是硬件像素。这意味着它可以受缩放级别的影响; 要计算物理屏幕像素的实际数量，需要使用 `nsIDOMWindowUtils.screenPixelsPerCSSPixel` 属性。

语法
--
```

screenX = window.mozInnerScreenX;
```

值
-

* *screenX* 存储的是 `window.mozInnerScreenX` 的属性值。
* `window.mozInnerScreenX` 属性的值是一个浮点数，只读; 它没有默认值。
规范
--

不属于任何 W3C 规范或标准。

相关链接
----

* `window.mozInnerScreenY`
* `nsIDOMWindowUtils.screenPixelsPerCSSPixel`


Window.closed - Web API 接口参考

Window.closed
=============

概述
--

此只读属性表示所引用的窗口是否关闭。

语法
--
```

isClosed = windowRef.closed;
```

`isClosed`

一个布尔值。可能的值：

* `true`: 窗口已被关闭。
* `false`: 窗口是打开的。

示例
--

### 更改一个弹出窗口的 URL

下面的示例演示怎样更改一个已打开的弹出窗口的 URL。尝试更改 URL 之前，它使用 window.opener 属性来检查有窗口被打开，并且该窗口没有关闭：

```js
// Check that an opener exists and is not closed
if (window.opener && !window.opener.closed) {
  window.opener.location.href = "http://www.mozilla.org";
}
```

请注意，弹出窗口只能访问打开他们的窗口。

### 刷新先前打开的弹出窗口

在这个例子中，函数 refreshPopupWindow() 调用重载方法的弹出的位置要刷新其数据的对象。如果弹出窗口尚未打开，或者用户已关闭它打开一个新窗口。

```js
var popupWindow = null;

function refreshPopupWindow() {
  if (popupWindow && !popupWindow.closed) {
    // popupWindow is open, refresh it
    popupWindow.location.reload(true);
  } else {
    // Open a new popup window
    popupWindow = window.open("popup.html", "dataWindow");
  }
}
```

技术说明
----

HTML5


Window.resizeBy() - Web API 接口参考

Window.resizeBy()
=================

概述
--

调整窗口大小。

语法
--
```

window.resizeBy(xDelta, yDelta)
```

### 参数

* `xDelta` 为窗口水平方向变化的像素值。
* `yDelta` 为窗口垂直方向变化的像素值。
例子
--

```js
// 缩小窗口
window.resizeBy(-200, -200);
```

备注
--

该方法相对于窗口当前大小来调整该窗口的大小。要以绝对大小方式调整窗口的大小，可使用 `window.resizeTo`。

从 Firefox 7，依据下面的规则，不能再调整浏览器内一个窗口的默认大小了：

1. 不能调整非 window.open 方法打开的窗口或 Tab 的大小。
2. 当一个窗口内包含有一个以上的 Tab 时，不能调整窗口的大小。
规范
--

DOM Level 0。不属于规范。


Window: 页面隐藏事件 (pagehide event) - Web API 接口参考

Window: 页面隐藏事件 (pagehide event)
===============================

当浏览器在显示与会话历史记录不同的页面的过程中隐藏当前页面时，**`pagehide`**(页面隐藏) 事件会被发送到一个`Window` 。例如，当用户单击浏览器的“后退”按钮时，当前页面在显示上一页之前会收到一个`pagehide`(页面隐藏) 事件。

|  |  |
| --- | --- |
| Bubbles(冒泡) | No |
| Cancelable(可取消) | No |
| Interface(接口) | `PageTransitionEvent` |
| Event handler property(事件处理程序属性) | `onpagehide` |

例子
--

在此示例中，建立了一个事件处理程序以监视 `pagehide` (页面隐藏) 事件，并在持久保存页面以进行可能的重用时执行特殊处理。

```js
window.addEventListener(
  "pagehide",
  (event) => {
    if (event.persisted) {
      /\* the page isn't being discarded, so it can be reused later \*/
    }
  },
  false,
);
```

这也可以使用 `Window` 上的 `onpagehide` 事件处理程序属性来编写：

```js
window.onpagehide = (event) => {
  if (event.persisted) {
    /\* the page isn't being discarded, so it can be reused later \*/
  }
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-pagehide |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

了解更多
----

* The `pageshow` event


window.length - Web API 接口参考

window.length
=============

概述
--

返回当前窗口中包含的框架数量 (框架包括`frame`和`iframe`两种元素).

语法
--
```

framesCount = window.length;
```

* `framesCount`就是该窗口中框架的数量。
示例
--

```js
if (window.length) {
  // 该窗口包含至少一个子框架
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-length-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Window.onbeforeinstallprompt - Web API 接口参考

Window.onbeforeinstallprompt
============================

**`Window.onbeforeinstallprompt`** 属性是一个事件处理程序，用于处理一个 `beforeinstallprompt`，当一个 Web 清单存在时，它将在移动设备上发送，但是在提示用户将网站保存到主屏幕之前。

句法
--
```

window.addEventListener("beforeinstallprompt", function(event) { ... });

window.onbeforeinstallprompt = function(event) { ...};
```

范例
--

The following example uses the beforeinstallprompt function to verify that it is an appropriate time to display an installation prompt to the user. If it is not, the event is redispatched.

```js
let isTooSoon = true;
window.addEventListener("beforeinstallprompt", function (e) {
  if (isTooSoon) {
    e.preventDefault(); // Prevents prompt display
    // Prompt later instead:
    setTimeout(function () {
      isTooSoon = false;
      e.prompt(); // Shows prompt
    }, 10000);
  }

  // The event was re-dispatched in response to our request
  // ...
});
```

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `BeforeInstallPromptEvent.prompt`
* `BeforeInstallPromptEvent`


Window.devicePixelRatio - Web API 接口参考

Window.devicePixelRatio
=======================

`Window` 接口的 **`devicePixelRatio`** 返回当前显示设备的*物理像素*分辨率与*CSS 像素*分辨率之比。此值也可以解释为像素大小的比率：一个 CSS 像素的大小与一个物理像素的大小。简单来说，它告诉浏览器应使用多少屏幕实际像素来绘制单个 CSS 像素。

当处理标准显示器与 HiDPI 或 Retina 显示器之间的差异时，这很有用，后者使用更多的屏幕像素绘制相同的对象，从而获得更清晰的图像。

你可以使用`window.matchMedia()` 检查`devicePixelRatio`的值是否发生更改（例如，如果用户将窗口拖动到带有 不同的像素密度）。请参阅下面的例子。

语法
--
```

value = window.devicePixelRatio;
```

### 值

一个双精度浮点值，指示显示器的物理像素分辨率与 CSS 像素分辨率之比。值 1 表示经典 96 DPI（在某些平台上为 76 DPI）显示，而对于 HiDPI / Retina 显示屏则期望值为 2。在异常低分辨率的显示器中，或更常见的是，当屏幕的像素深度比简单地将 96 或 76 DPI 的标准分辨率提高一倍时，可能还会返回其他值。

示例
--

### 在 `<canvas>` 中更正分辨率

`<canvas>`可能在视网膜屏幕上显得太模糊。使用`window.devicePixelRatio`确定应添加多少额外的像素密度以使图像更清晰。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

// Set display size (css pixels).
var size = 200;
canvas.style.width = size + "px";
canvas.style.height = size + "px";

// Set actual size in memory (scaled to account for extra pixel density).
var scale = window.devicePixelRatio; // Change to 1 on retina screens to see blurry canvas.
canvas.width = Math.floor(size \* scale);
canvas.height = Math.floor(size \* scale);

// Normalize coordinate system to use css pixels.
ctx.scale(scale, scale);

ctx.fillStyle = "#bada55";
ctx.fillRect(10, 10, 300, 300);
ctx.fillStyle = "#ffffff";
ctx.font = "18px Arial";
ctx.textAlign = "center";
ctx.textBaseline = "middle";

var x = size / 2;
var y = size / 2;

var textString = "I love MDN";
ctx.fillText(textString, x, y);
```

![This image describe the impact of different value on retina display. ](/zh-CN/docs/Web/API/Window/devicePixelRatio/devicepixelration_diff..png)

### 监视屏幕分辨率或缩放级别的更改

在此示例中，我们将设置一个媒体查询并观看它以查看设备分辨率何时更改，以便我们可以检查`devicePixelRatio`的值来处理所需的任何更新。

#### JavaScript

JavaScript 代码创建媒体查询，以监控设备分辨率并在每次更改时检查`devicePixelRatio`的值。

```js
let pixelRatioBox = document.querySelector(".pixel-ratio");
let mqString = `(resolution: ${window.devicePixelRatio}dppx)`;

const updatePixelRatio = () => {
  let pr = window.devicePixelRatio;
  let prString = (pr \* 100).toFixed(0);
  pixelRatioBox.innerText = `${prString}% (${pr.toFixed(2)})`;
};

updatePixelRatio();

matchMedia(mqString).addListener(updatePixelRatio);
```

字符串`mqString`设置为媒体查询本身。媒体查询以`(resolution: 1dppx)`（对于标准显示）或`(resolution: 2dppx)`（对于 Retina / HiDPI 显示）开始，检查当前显示分辨率是否与每个像素`px`的实际设备像素点匹配。

`updatePixelRatio()`函数获取`devicePixelRatio`的当前值，然后将`pixelRatioBox`的 `innerText`设置为一个字符串，该字符串同时显示百分比和原始十进制值比率，最多两位小数。

然后，调用`updatePixelRatio()`函数一次以显示起始值，然后使用`matchMedia()` 和 `addEventListener()`来将`updatePixelRatio()`设置为`change`事件的处理程序。

#### HTML

HTML 将创建包含说明的框和将显示当前像素比率信息的`pixel-ratio` 框。

```html
<div class="container">
  <div class="inner-container">
    <p>
      This example demonstrates the effect of zooming the page in and out (or
      moving it to a screen with a different scaling factor) on the value of the
      property <code>Window.devicePixelRatio</code>. Try it and watch what
      happens!
    </p>
  </div>
  <div class="pixel-ratio"></div>
</div>
```

#### CSS

```css
body {
  font:
    22px arial,
    sans-serif;
}

.container {
  top: 2em;
  width: 22em;
  height: 14em;
  border: 2px solid #22d;
  margin: 0 auto;
  padding: 0;
  background-color: #a9f;
}

.inner-container {
  padding: 1em 2em;
  text-align: justify;
  text-justify: auto;
}

.pixel-ratio {
  position: relative;
  margin: auto;
  height: 1.2em;
  text-align: right;
  bottom: 0;
  right: 1em;
  font-weight: bold;
}
```

#### 结果

规范
--

| Specification |
| --- |
| CSSOM View Module # dom-window-devicepixelratio |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* Media queries
* Using media queries
* CSS `resolution` media query (en-US)


Window：offline 事件 - Web API 接口参考

Window：offline 事件
=================

`offline` 事件在浏览器失去网络连接时，在 `Window` 接口上触发。并且 `Navigator.onLine` (en-US) 的值变为 `false`。

语法
--

在类似 `addEventListener()` 这样的方法中使用事件名称，或者设置事件处理器属性。

```js
addEventListener("offline", (event) => {});
onoffline = (event) => {};
```

事件类型
----

一个 `Event`。

事件处理方法别名
--------

除了 `Window` 接口以外，事情处理方法属性 `onoffline` 同样可以用于以下目标：

* `HTMLBodyElement`
* `HTMLFrameSetElement` (en-US)
* `SVGSVGElement`
示例
--

```js
// addEventListener 版本
window.addEventListener("offline", (event) => {
  console.log("网络连接已断开。");
});

// onoffline 版本
window.onoffline = (event) => {
  console.log("网络连接已断开。");
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-offline |
| HTML Standard # handler-window-onoffline |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* `online`


Window.localStorage - Web API 接口参考

Window.localStorage
===================

只读的`localStorage` 属性允许你访问一个`Document` 源（origin）的对象 `Storage`；存储的数据将保存在浏览器会话中。`localStorage` 类似 `sessionStorage`，但其区别在于：存储在 `localStorage` 的数据可以长期保留；而当页面会话结束——也就是说，当页面被关闭时，存储在 `sessionStorage` 的数据会被清除。

应注意，无论数据存储在 `localStorage` 还是 `sessionStorage` ，**它们都特定于页面的协议。**

另外，`localStorage` 中的键值对总是以字符串的形式存储。 (需要注意，和 js 对象相比，键值对总是以字符串的形式存储意味着数值类型会自动转化为字符串类型).

语法
--

```js
myStorage = localStorage;
```

### 值

一个可被用于访问当前源（origin）的本地存储空间的 `Storage` 对象。

### 异常

`SecurityError`

请求违反了一个策略声明，或者源（origin）不是 一个有效的 scheme/host/port tuple （例如如果 origin 使用 `file:` 或者 `data:` 形式将可能发生）。比如，用户可以有禁用允许对指定的 origin 存留数据的浏览器配置。

示例
--

下面的代码片段访问了当前域名下的本地 `Storage` 对象，并通过 `Storage.setItem()` 增加了一个数据项目。

```js
localStorage.setItem("myCat", "Tom");
```

该语法用于读取 `localStorage` 项，如下：

```js
let cat = localStorage.getItem("myCat");
```

该语法用于移除 `localStorage` 项，如下：

```js
localStorage.removeItem("myCat");
```

该语法用于移除所有的 `localStorage` 项，如下：

```js
// 移除所有
localStorage.clear();
```

**备注：** 请参考 Using the Web Storage API 的完整示例文章。

规范
--

| Specification |
| --- |
| HTML Standard # dom-localstorage-dev |

浏览器兼容性
------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

参见
--

* 使用 Web Storage API
* Local storage（Window.localStorage） (en-US)
* `LocalStorage` (en-US)
* `SessionStorage` (en-US)
* `Window.sessionStorage`


Window.scrollByLines() - Web API 接口参考

Window.scrollByLines()
======================

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

概要
--

按给定的行数滚动文档。

语法
--
```

window.scrollByLines(lines)
```

参数
--

* `lines` 要滚动的行数。
* `lines` 可以是正整数，也可以是负整数。
例子
--

```html
<!-- 向下滚动 5 行。 -->
<button onclick="scrollByLines(5);">down 5 lines</button>
```

```html
<!-- 向上滚动 5 行。 -->
<button onclick="scrollByLines(-5);">up 5 lines</button>
```

规范
--

这不是任何规范的一部分。

参考
--

* `window.scrollBy`, `window.scrollByPages`