recursal/MDN huggingface dataset:
CacheStorage.has()
==================

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

`CacheStorage` 对象的 \*\*`has()`\*\*方法返回一个 `Promise` 对象，当 `Cache` 对象有 `cacheName` 时被处理为 `true` 。

语法
--
```

caches.has(cacheName).then(function(boolean) {
  // true: 缓存存在
});
```

### 返回值

返回一个 `Promise` 对象，缓存存在时 resolve 的布尔值为 `true` 否则为 `false` 。

### 参数

cacheName

一个表示你正在 `CacheStorage` 中查找的 `Cache` 对象 name 的 `DOMString`.

例子
--

在下面的例子中首先检测是否有名为 v1 的缓存存在，如果存在我们会向其添加内容，，如果不存在我们会做些对应的初始化动作。


```js
caches
  .has("v1")
  .then(function (hasCache) {
    if (!hasCache) {
      someCacheSetupfunction();
    } else {
      caches.open("v1").then(function (cache) {
        return cache.addAll(myAssets);
      });
    }
  })
  .catch(function () {
    // 处理异常
  });
```

规范
--

| Specification |
| --- |
| Service Workers # cache-storage-has |

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

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

参考
--

* Using Service Workers (en-US)
* `Cache`
* `WorkerGlobalScope.caches` (en-US)
CacheStorage.open()
===================

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

`CacheStorage` 接口的 **`open()`** 方法返回一个 resolve 为匹配 `cacheName` 的 `Cache` 对象的 `Promise` .

**备注：** 如果指定的 `Cache` 不存在，则使用该 `cacheName` 创建一个新的 cache，并返回一个 resolve 为该新 `Cache` 对象的`Promise`.

语法
--


```js
// "caches" is a global read-only variable, which is an instance of CacheStorage,
// For more info, refer to: https://developer.mozilla.org/zh-CN/docs/Web/API/caches

caches.open(cacheName).then(function (cache) {
  // Do something with your cache
});
```

### 参数

cacheName

要打开的 cache 对象 name.

### 返回值

一个 resolve 为请求的 `Cache` 对象的 `Promise` .

示例
--

此示例来自于 MDN sw-test example （请参阅 sw-test running live）。这里，等待 `FetchEvent` 事件触发。我们构建自定义响应，像这样：

1. 使用 `CacheStorage.match()` 检查 `CacheStorage` 中是否存在匹配请求，如果存在，则使用它。
2. 如果没有，使用 `CacheStorage.open()` 打开 `v1` cache，使用 `Cache.put()` 将默认网络请求放入 cache 中，并使用 `return response.clone()` 返回默认网络请求的克隆副本。最后一个是必须的，因为 `put()` 使用响应主体。
3. 如果此操作失败（例如，因为网络已关闭），则返回备用响应。


```js
var cachedResponse = caches
  .match(event.request)
  .catch(function () {
    return fetch(event.request);
  })
  .then(function (response) {
    caches.open("v1").then(function (cache) {
      cache.put(event.request, response);
    });
    return response.clone();
  })
  .catch(function () {
    return caches.match("/sw-test/gallery/myLittleVader.jpg");
  });
```

规范
--

| Specification |
| --- |
| Service Workers # cache-storage-open |

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

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

See also
--------

* Using Service Workers (en-US)
* `Cache`
* `WorkerGlobalScope.caches` (en-US)
NodeList.length
===============

摘要
--

返回 `NodeList` 集合中子节点数量。

语法
--


```js
numItems = nodeList.length;
```


* `numItems` 是一个整数，表示 `NodeList` 子节点的数量。
例子
--


```js
// 获取文档中的所有 p 标签
var items = document.getElementsByTagName("p");

// 循环 items 然后输出每个 p 标签 html
var gross = "";
for (var i = 0; i < items.length; i++) {
  gross += items[i].innerHTML;
}

// gross 现在集合了所有 p 标签的 HTML 内容。
```

注意
--

length 不是 元素（Element）的属性，而是 NodeList 的属性。NodeList 是使用 DOM 操作方法返回的对象，比如使用 document.getElementsByTagName 就会返回一个 NodeList 对象。

length 是在 DOM 操作中非常常见的属性。最常见的是用 length 属性来判断某些节点是否存在，或者如上述一样，用在 for 循环上。

规范
--

length
NodeList.values()
=================

该方法返回一个 iterator 迭代器，可以利用迭代器遍历所有 value。

Syntax
------
```

nodeList.values();
```

### Return value

Returns an `iterator`.

Example
-------


```js
var node = document.createElement("div");
var kid1 = document.createElement("p");
var kid2 = document.createTextNode("hey");
var kid3 = document.createElement("span");

node.appendChild(kid1);
node.appendChild(kid2);
node.appendChild(kid3);

var list = node.childNodes;

// Using for..of
for (var value of list.values()) {
  console.log(value);
}
```


The result is:
```

<p>
#text "hey"
<span>
```

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

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

See also
--------

* `Node`
* `NodeList`
NodeList.prototype.forEach()
============================

`NodeList`接口的 **`forEach()`** 方法按插入顺序为列表中的每个值对调用一次参数中给定的回调。

语法
--
```

someNodeList.forEach(callback[, thisArg]);
```

### 参数

`callback`

为 `someNodeList`的每一个元素执行函数。它接受以下三个参数：

`currentValue`

`someNodeList`中的当前元素。

`currentIndex` 可选

`someNodeList`中的`currentValue`所对应的索引值。

`listObj` 可选

`someNodeList` 在 `forEach()` 方法中所属的 NodeList 对象。


`thisArg` 可选

传递 `callback` 的值一般用`this`值。

### 返回值

`undefined`.

示例
--


```js
let node = document.createElement("div");
let kid1 = document.createElement("p");
let kid2 = document.createTextNode("hey");
let kid3 = document.createElement("span");

node.appendChild(kid1);
node.appendChild(kid2);
node.appendChild(kid3);

let list = node.childNodes;

list.forEach(function (currentValue, currentIndex, listObj) {
  console.log(currentValue + ", " + currentIndex + ", " + this);
}, "myThisArg");
```


上述代码会产生以下结果：
```

[object HTMLParagraphElement], 0, myThisArg
[object Text], 1, myThisArg
[object HTMLSpanElement], 2, myThisArg
```

规范
--

| Specification |
| --- |
| DOM Standard # interface-nodelist |

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

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

参见
--

* `Node`
* `NodeList`
NodeList.item
=============

### 概述

根据给定的索引，返回一个 `NodeList`对象中包含的 Node 对象。

### 语法
```

nodeItem = nodeList.item(index)
```


* `nodeList`是一个`NodeList`对象。通常是由某个 DOM 属性或方法返回的，比如childNodes.
* `index` 是给定的索引。从 0 开始。
* `nodeItem` 是根据索引`index` 由 `item` 方法从 `nodeList` 中获取到的节点。

JavaScript 有更简单的语法来从一个 NodeList 对象中获取指定索引的节点：
```

nodeItem = nodeList[index]
```

### 例子
```

var tables = document.getElementsByTagName("table");
var firstTable = tables.item(1); // 或者简写为 tables[1]，返回一个文档中的第二个 table 元素。
```

### 备注

如果索引越界，该方法不会抛出异常，只会返回 `null`。

`item()` 不是 DOM 元素或者 DOM 节点的方法，而是 NodeList 对象的方法。

### 规范

DOM Level 1 Core: NodeList.item()

DOM Level 2 Core: NodeList.item()
NodeList.keys()
===============

**`NodeList.keys()`** 方法返回 `iterator` ，此方法允许遍历这个对象中包含的所有的键，即使这个键是 `unsigned integer（无符号整数）`.

语法
--
```

nodeList.keys();
```

### 返回值

返回 `iterator`.

例子
--


```js
var node = document.createElement("div");
var kid1 = document.createElement("p");
var kid2 = document.createTextNode("hey");
var kid3 = document.createElement("span");

node.appendChild(kid1);
node.appendChild(kid2);
node.appendChild(kid3);

var list = node.childNodes;

// Using for..of
for (var key of list.keys()) {
  console.log(key);
}
```


结果是：
```

0
1
2
```

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

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

相关链接
----

* `Node`
* `NodeList`
NodeList.entries()
==================

该方法返回一个迭代协议，允许遍历此对象中包含的所有键/值。该值也是一个`Node` 对象。

语法
--
```

list.entries();
```

### 返回值

返回一个 `iterator`.

例子
--


```js
var node = document.createElement("div");
var kid1 = document.createElement("p");
var kid2 = document.createTextNode("hey");
var kid3 = document.createElement("span");
node.appendChild(kid1);
node.appendChild(kid2);
node.appendChild(kid3);

var list = node.childNodes;

// 使用 for..of 循环
for (var entry of list.entries()) {
  console.log(entry);
}
```


结果如下：
```

Array [ 0, <p> ]
Array [ 1, #text "hey" ]
Array [ 2, <span> ]
```

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

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

相关链接
----

* `Node`
* `NodeList`
ExtendableEvent.waitUntil()
===========================

**`ExtendableEvent.waitUntil()`** 方法告诉事件分发器该事件仍在进行。这个方法也可以用于检测进行的任务是否成功。在服务工作线程中，这个方法告诉浏览器事件一直进行，直至 promise 解决，浏览器不应该在事件中的异步操作完成之前终止服务工作线程。

service worker 中的 `install` (en-US) 事件使用 `waitUntil()` 来将服务工作线程保持在 `installing` (en-US) 阶段。如果传入 `waitUntil()` 的 promise 被拒绝，则将此次安装视为失败，丢弃这个服务工作线程。这主要用于确保在服务工作线程安装以前，所有依赖的核心缓存都已经成功载入。

service worker 中的 `activate` (en-US) 事件使用 `waitUntil()` 来延迟函数事件，如 `fetch` 和 `push`，直至传入 `waitUntil()` 的 promise 被解决。这让服务工作线程有时间更新数据库架构（database schema）和删除过时缓存，让其他事件能在一个完成更新的状态下进行。

`waitUntil()` 方法最初必须在事件回调里调用，在此之后，方法可以被调用多次，直至所有传入的 promise 被解决。

**备注：** 上述段落描述的行为已经在 Firefox 43 中被修复（参见 Firefox bug 1180274）。

语法
--


```js
waitUntil(promise)
```

### 参数

一个 `Promise`.

示例
--

在服务工作线程的 `install` 事件中使用 `waitUntil()`。


```js
addEventListener("install", (event) => {
  const preCache = async () => {
    const cache = await caches.open("static-v1");
    return cache.addAll(["/", "/about/", "/static/styles.css"]);
  };
  event.waitUntil(preCache());
});
```

规范
--

| Specification |
| --- |
| Service Workers # dom-extendableevent-waituntil |

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

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

参见
--

* 使用 Service Worker
* 是否支持 ServiceWorker
* `Promise`
CustomElementRegistry.upgrade()
===============================

CustomElementRegistry 接口的 upgrade() 方法将更新节点子树中所有包含阴影的自定义元素，甚至在它们连接到主文档之前也是如此。

语法
--
```

customElements.upgrade(root);
```

### 参数

`root`

待升级的包含阴影的派生元素`节点` 。如果没有可升级的派生实例，则不会抛出异常。

### 返回值

空。

示例
--

摘至HTML 规范:


```js
const el = document.createElement("spider-man");

class SpiderMan extends HTMLElement {}
customElements.define("spider-man", SpiderMan);

console.assert(!(el instanceof SpiderMan)); // not yet upgraded

customElements.upgrade(el);
console.assert(el instanceof SpiderMan); // upgraded!
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-upgrade-dev |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
CustomElementRegistry.get()
===========================

`CustomElementRegistry` 的 **`get()`** 方法返回以前定义自定义元素的构造函数。

语法
--
```

constructor = customElements.get(name);
```

### 参数

name

你想要返回引用的构造函数的自定义元素的名字。

### 返回值

指定名字的自定义元素的构造函数，如果没有使用该名称的自定义元素定义，则为`undefined`。

例子
--


```js
customElements.define(
  "my-paragraph",
  class extends HTMLElement {
    constructor() {
      super();
      let template = document.getElementById("my-paragraph");
      let templateContent = template.content;

      const shadowRoot = this.attachShadow({ mode: "open" }).appendChild(
        templateContent.cloneNode(true),
      );
    }
  },
);

// Return a reference to the my-paragraph constructor
let ctor = customElements.get("my-paragraph");
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-get-dev |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
CustomElementRegistry.whenDefined()
===================================

当一个元素被定义时`CustomElementRegistry` 中的方法\*\*`whenDefined()`\*\* 接口返回 `Promise`.

语法
--
```

Promise<> customElements.whenDefined(name);
```

### 参数

name

自定义元素的名称

### 返回值

当自定义元素被定义时一个`Promise` 返回{jsxref("undefined")}}. 如果自定义元素已经被定义，则 resolve 立即执行。

### 例外

| Exception | Description |
| --- | --- |
| `SyntaxError` | 如果提供的 **name** 不是一个有效的 自定义元素名字, promise 的 reject 回调会接收到一个 `SyntaxError`. |

例子
--

这个例子使用 `whenDefined()` 来检测生成菜单的自定义元素何时被定义。这个菜单显示占位符内容一直到菜单内容已经准备好显示。


```html
<nav id="menu-container">
  <div class="menu-placeholder">Loading...</div>
  <nav-menu>
    <menu-item>Item 1</menu-item>
    <menu-item>Item 2</menu-item>
    ...
    <menu-item>Item N</menu-item>
  </nav-menu>
</nav>
```



```js
const container = document.getElementById("menu-container");
const placeholder = container.querySelector(".menu-placeholder");
// Fetch all the children of menu that are not yet defined.
const undefinedElements = container.querySelectorAll(":not(:defined)");

const promises = [...undefinedElements].map((button) =>
  customElements.whenDefined(button.localName),
);

// Wait for all the children to be upgraded,
// then remove the placeholder.
await Promise.all(promises);
container.removeChild(placeholder);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-customelementregistry-whendefined-dev |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
Bluetooth.requestDevice()
=========================

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

`Bluetooth`接口的 **`Bluetooth.requestDevice()`** 方法返回一个带有对应 options 的`BluetoothDevice` (en-US)对象的`Promise`对象。如果没有蓝牙设备选择界面，则此方法返回与条件匹配的第一个设备。

语法
--
```

Bluetooth.requestDevice(options).then(function(bluetoothDevice) { ... })
```

### 返回值

带有`BluetoothDevice` (en-US) 对象的`Promise` 对象。

### 参数

options

设置设备请求选项的对象。可用的选项是：

* `filters[]`: 一个 BluetoothScanFilters 数组。此过滤器由一个 BluetoothServiceUUID 数组，一个名称参数和一个 namePrefix 参数组成。
* `optionalServices[]`: 一个 BluetoothServiceUUID 数组。
* `acceptAllDevices`: boolean 表示请求脚本可以接受所有蓝牙设备。默认值为 false。

示例
--
```

//扫描选项匹配任何设备广播：

//. 标准心率服务。

//. 两个 16 位服务 ID 0x1802 和 0x1803。

//. 专有的 128 位 UUID 服务 c48e6067-5295-48d3-8d5c-0395f61792b1。

//. 名称为“设备名”的设备。

//. 名称以“前缀”开头的设备。

//

//如果设备包含电池服务，

//即使设备不通告该服务，也可以访问电池服务。

let options = {
  filters: [
    {services: ['heart_rate']},
    {services: [0x1802, 0x1803]},
    {services: ['c48e6067-5295-48d3-8d5c-0395f61792b1']},
    {name: '设备名'},
    {namePrefix: '前缀'}
  ],
  optionalServices: ['battery_service']
}

navigator.bluetooth.requestDevice(options).then(function(device) {
  console.log('名称：' + device.name);
  // 在此处实现设备调用
})
.catch(function(error) {
  console.log("出现错误： " + error);
});
```


查看详细示例

规范
--

| Specification |
| --- |
| Web Bluetooth # dom-bluetooth-requestdevice |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
IdleDeadline.timeRemaining()
============================

`IdleDeadline` 接口上的 **`timeRemaining()`** 方法返回当前空闲期间剩余的估计毫秒数。回调函数可以在任何时候调用此方法，以确定在必须返回之前它可以继续工作多长时间。例如，如果回调完成了一个任务，并且有另一个任务要开始，它可以调用 `timeRemaining()` 来查看是否有足够的时间来完成下一个任务。如果没有，回调函数可以立即返回，或者用剩余的时间寻找其他合适的工作。

当 `timeRemaining()` 达到 0 时，建议回调应该将控制权返回给用户代理的事件循环。

语法
--


```js
timeRemaining = IdleDeadline.timeRemaining();
```

### 返回值

一个 `DOMHighResTimeStamp` 值（是一个浮点数），表示用户代理估计在当前空闲期间内剩余的毫秒数。理想情况下，该值精确到大约 5 微秒。

如果 `IdleDeadline` 对象的 `didTimeout` (en-US) 属性为 `true` ，该方法返回 `0`。

示例
--

在文章后台任务协作调度 API 中可以查看完整示例 。

规范
--

| Specification |
| --- |
| requestIdleCallback() Cooperative Scheduling of Background Tasks # dom-idledeadline-timeremaining |

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

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

参见
--

* 后台任务协作调度
* `IdleDeadline`
* `Window.requestIdleCallback()`
* `Window.cancelIdleCallback()`
DOMRect.DOMRect()
=================

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

**`DOMRect()`** 构造函数生成一个新的 `DOMRect` 对象。

语法
--


```js
var myDOMRect = new DOMRect(x, y, width, height);
```

### 参数

x

`DOMRect` 原点的 `x` 坐标。

y

`DOMRect` 原点的 y 坐标。

width

`DOMRect` 的宽度。

height

`DOMRect` 的高度。

例子
--

想生成一个新 `DOMRect`，你可以运行一行这样的代码：


```js
myDOMRect = new DOMRect(0, 0, 100, 100);
// running 'myDOMRect' in the console would then return
// DOMRect { x: 0, y: 0, width: 100, height: 100, top: 0, right: 100, bottom: 100, left: 0 }
```

规范
--

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-domrect-domrect |

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

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

更多
--

* `DOMPoint`
* `DOMRect`
DOMPoint.x
==========

**`DOMPoint`** 的 x 属性表示该点的水平坐标。通常， `x` 的正值表示右边，负值表示左边，除非改变了默认的轴方向。

语法
--
```

var xPos = DOMPoint.x;
```

### 值

双精度浮点值，表示该点的 x 坐标值。这个值的类型并没有严格限制，意味着它可以是 `NaN` 或 `±Infinity`。

规范
--

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-dompointreadonly-x |

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

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

参见
--

* 其他坐标属性：`y`，`z`，透视值 `w`.
DOMPoint.y
==========

**`DOMPoint`** 的 **`y`** 属性表示该点的垂直坐标。`y` 值增加表示向下偏移，减小表示向上偏移，除非改变了默认轴方向。

语法
--
```

var yPos = DOMPoint.y;
```

### 值

双精度浮点值，表示该点的 y 坐标值。这个值的类型并没有严格限制，意味着它可以是 `NaN` 或 `±Infinity`。

规范
--

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-dompointreadonly-y |

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

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

参见
--

* 其他坐标属性： `x`, `z`, 透视值 `w`。
DOMPoint.DOMPoint()
===================

\*\*`DOMPoint()`\*\*构造函数创建并返回一个 `DOMPoint` 对象，可提供部分或全部属性值作为其参数。

也可以通过调用静态方法 `DOMPoint.fromPoint()` (en-US) 来创建 `DOMPoint` 。此方法接受一个 `DOMPointInit` (en-US) 兼容对象（`DOMPoint` 或 `DOMPointReadOnly` (en-US)）作为参数。

语法
--
```

point = new DOMPoint(x, y, z, w);
```

### 参数

`x` 可选

`x` 坐标。

`y` 可选

`y` 坐标。

`z` 可选

`z` 坐标。

`w` 可选

透视值。

示例
--

示例首先创建了一个表示当前窗口左上角的 `DOMPoint` ，接着根据第一个点创建一个新的 `DOMPoint` 并将其在垂直和水平方向上偏移 100px。


```js
var windTopLeft = new DOMPoint(window.screenX, window.screenY);
var newTopLeft = DOMPoint.fromPoint(windTopLeft);
newTopLeft.x += 100;
newTopLeft.y += 100;
```

规范
--

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-dompoint-dompoint |

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

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

参见
--

* `DOMPointReadOnly()`
* `DOMRect`
* `DOMMatrix`
DOMPoint.w
==========

**`DOMPoint`** 的 w 属性表示该点的空间透视值。

语法
--
```

var perspective = DOMPoint.w;
```

### 值

双精度浮点值，表示该点的空间透视值。这个值的类型并没有严格限制，意味着它可以是 `NaN` 或 `±Infinity`。默认值为 1.0。

规范
--

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-dompointreadonly-w |

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

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

参见
--

* 其他坐标属性：`x`，`y`，`z`.
DOMPoint.z
==========

**`DOMPoint`** 的 **`z`** 属性表示该点的深度坐标。 `z` 值为 0 表示屏幕平面，正值表示从屏幕前面向靠近用户的方向延伸，负值表示从屏幕后面向远离用户的方向延伸，除非改变了默认的轴方向。

语法
--
```

var zPos = DOMPoint.z;
```

### 值

双精度浮点值，表示该点的 z 坐标值。这个值的类型并没有严格限制，意味着它可以是 `NaN` 或 `±Infinity`。

规范
--

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # dom-dompointreadonly-z |

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

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

参见
--

* 其他坐标属性：`x`， `y`，透视值 `w`。
AbortSignal.timeout()
=====================

静态方法 **`AbortSignal.timeout()`** 返回一个指定时间后将自动中止的 `AbortSignal`。

信号在超时时使用 `TimeoutError` `DOMException` 中止，或者由于按下一个浏览器停止按钮（或者一些内置的“停止”操作）而使用 `AbortError` `DOMException` 中止。这允许 UI 区分超时错误（通常需要通知用户）和用户触发的错误（不需要通知用户）。

超时将基于活动的时间，而不是经过的时间，如果代码在指定的的 worker 中运行或者文档在往返缓存时（bfcache），将有效地暂停。

**备注：** 在编写代码时，无法组合多个信号。意思是你不能使用超时的 signal 或者通过调用 `AbortController.abort()` 直接中止下载。

语法
--


```js
AbortSignal.timeout(time)
```

### 参数

`time`

返回的 `AbortSignal` 将中止之前的“活动”时间（以毫秒为单位）。

### 返回值

一个 `AbortSignal`。

signal 中止，并且 `AbortSignal.reason` 属性将在超时时设置一个 `TimeoutError` `DOMException`，如果操作是用户触发的，则为 `AbortError` `DOMException`。

示例
--

以下简单示例展示了一个 fetch 操作，如果其在 5 秒后不成功，则超时。注意，如果不支持该方法、按下浏览器的“停止”按钮或其他原因，也可能失败。


```js
const url = "https://path\_to\_large\_file.mp4";

try {
  const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
  const result = await res.blob();
  // …
} catch (err) {
  if (err.name === "TimeoutError") {
    console.error("Timeout: It took more than 5 seconds to get the result!");
  } else if (err.name === "AbortError") {
    console.error(
      "Fetch aborted by user action (browser stop button, closing tab, etc.",
    );
  } else if (err.name === "TypeError") {
    console.error("AbortSignal.timeout() method is not supported");
  } else {
    // A network error, or some other problem.
    console.error(`Error: type: ${err.name}, message: ${err.message}`);
  }
}
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-abortsignal-timeout① |

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

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

只读属性 **`reason`** 返回一个使用 JavaScript 值表示的中止原因。

当 signal 没有被中止时，该属性值为 `undefined`。当使用 `AbortController.abort()` 或 `AbortSignal.abort()` 中止 signal 时，可以设置一个指定的值。如果没有在这些方法中明确的设置，则默认是"AbortError"`DOMException`。

值
-

一个使用 JavaScript 值表示的中止原因，如果没有被中止，则是 `undefined`。

示例
--

在以下片段中，我们创建一个新的 `AbortController` 对象，并且获取它的 `AbortSignal`（位于 `signal` 属性中）。然后我们用 `aborted` 属性检查这个信号是否已被中止，并把相应的日志发送给控制台。


```js
const controller = new AbortController();
const signal = controller.signal;

// …

if (signal.aborted) {
  if (signal.reason) {
    console.log(`Request aborted with reason: ${signal.reason}`);
  } else {
    console.log("Request aborted but no reason was given.");
  }
} else {
  console.log("Request not aborted");
}
```

规范
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-abortsignal-reason① |

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

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

参见
--

* Fetch API
AbortSignal.abort()
===================

静态方法 **`AbortSignal.abort()`** 返回一个已经设置为中止的 `AbortSignal`（并且不会触发 `abort` 事件）。

它是以下片段的简写：


```js
const controller = new AbortController();
controller.abort();
return controller.signal;
```


例如，将它传递给一个 fetch 方法，以运行它的中止逻辑（也就是说，可能其代码的执行顺序是即使预期的 fetch 操作还没有启动，也应该运行中止逻辑）。

**备注：** 该方法在目的上类似于 `Promise.reject`。

语法
--


```js
AbortSignal.abort()
AbortSignal.abort(reason)
```

### 参数

`reason`

操作被中止的原因，可以是任意的 JavaScript 值。如果没有指定原因，则默认设置为"AbortError"`DOMException`。

### 返回值

一个 `AbortSignal.aborted` 属性设置为 `true` 的 `AbortSignal` 实例，并且 `AbortSignal.reason` 设置为指定的或者默认的原因值。

参数
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-abortsignal-abort① |

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

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

当事件关联的请求被中止时，触发 `AbortSignal` 接口的 **`abort`** 事件，例如，调用 `AbortController.abort()`。

语法
--

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


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

事件类型
----

`Event` 泛型，无任何额外的属性。

示例
--

在下面例子中，我们将创建一个新的 `AbortController` 对象，并获取它的 `AbortSignal`（在 `signal` 属性中可用）。稍后，我们使用事件处理器属性检查信号是否被中止。

你可以使用 `addEventListener` 方法来检测 `abort` 事件：


```js
const controller = new AbortController();
const signal = controller.signal;

signal.addEventListener("abort", () => {
  console.log("Request aborted");
});
```


或者使用 `onabort` 事件处理器属性：


```js
const controller = new AbortController();
const signal = controller.signal;
signal.onabort = () => {
  console.log("Request aborted");
};
```

规范
--

| Specification |
| --- |
| DOM Standard # eventdef-abortsignal-abort |
| DOM Standard # abortsignal-onabort |

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

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

**`aborted`** 是一个只读属性，它返回一个 `Boolean` (en-US) 表示与之通信的请求是否被终止（`true`）或未终止（`false`）

### 值

`true`（中止）或 `false`

示例
--

在下面的代码段中，我们创建了一个新的 `AbortController` 对象，并获取它的 `AbortSignal`（位于 `signal` 属性中）。然后我们用 `aborted` 属性检查这个信号是否已被中止，并把相应的日志发送给控制台。


```js
const controller = new AbortController();
const signal = controller.signal;

// …

if (signal.aborted) {
  console.log("Request has been aborted");
} else {
  console.log("Request not aborted");
}
```

规格
--

| Specification |
| --- |
| DOM Standard # ref-for-dom-abortsignal-aborted① |

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

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

参见
--

* Fetch API