recursal/MDN huggingface dataset:
HTMLCollection.namedItem()
==========================

`HTMLCollection` 接口的 **`namedItem()`** 方法返回第一个与集合中的 `id` 或者 `name` 属性匹配成功的 `Element`，如果没有匹配成功，则返回 `null`。

在 JavaScript 中，对一个 `String` 使用数组括号语法，例如 `collection["value"]` 等价于 `collection.namedItem("value")`。

语法
--


```js
const item = collection.namedItem(key);
```

### 参数

* `key` 是一个字符串，表示我们正在查找元素的 `id` 或者 `name` 属性。
### 返回值

* `item` 是 `HTMLCollection` 第一个与 *key* 匹配的 `Element`，如果没有，则返回 `null`。
示例
--

### HTML


```html
<div id="personal">
  <span name="title">Dr.</span>
  <span name="firstname">John</span>
  <span name="lastname">Doe</span>
  <span id="degree">(MD)</span>
</div>
```

### JavaScript


```js
const container = document.getElementById("personal");

// Returns the HTMLSpanElement with the name "title" if no such element exists null is returned
const titleSpan = container.children.namedItem("title");

// The following variants return undefined instead of null if there's no element with a matching name or id
const firstnameSpan = container.children["firstname"];
const lastnameSpan = container.children.lastname;

// Returns the span element with the id "degree"
const degreeSpan = container.children.namedItem("degree");

const output = document.createElement("div");
output.textContent = `Result: ${titleSpan.textContent} ${firstnameSpan.textContent} ${lastnameSpan.textContent} ${degreeSpan.textContent}`;

container.insertAdjacentElement("afterend", output);
```

规范
--

| Specification |
| --- |
| DOM Standard # dom-htmlcollection-nameditem-key |

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

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

小结

**elements** 返回一个 `HTMLFormControlsCollection` (en-US) (`HTMLCollection`) 其中包含 FORM 的所有控件。需要注意的是，其中不包括 `type` 等于 `image` 的 `input` 元素。

你可以通过 name (en-US) 或 id来访问对应的控件。

语法
--
```

nodeList = HTMLFormElement.elements
```

实例
--


```js
var inputs = document.getElementById("form1").elements;
var inputByIndex = inputs[2];
var inputByName = inputs["login"];
```

规范
--

* HTML5, Section 4.10.3, The form Element
* DOM Level 2 HTML: elements
HTMLFormElement.action
======================

**`HTMLFormElement.action`** 这个 js 语句能够定义一个`<form>`元素中的 action 属性

表单的 action 属性是在服务器上提交表单，这个属性可以被检索或者设置。

语法
--
```

string = form.action
form.action = string
```

例子
--

form.action = "/cgi-bin/publish";

详细说明
----

HTML 5, Section 4.10.19.6, Form submission

DOM Level 2 HTML: action
HTMLFormElement.reportValidity()
================================

Baseline 2023
-------------

Newly availableSince March 2023, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Learn more
* See full compatibility
* Report feedback
方法 **`HTMLFormElement.reportValidity()`** 返回布尔值，如果 form 表单的子表单控件满足验证限制条件，则该方法返回 `true` ，否则返回`false`。当返回 `false` 时，每个不合法的子控件的 `invalid` (en-US) 事件将会被触发，并且验证中存在的问题会报告该用户。

Syntax
------
```

HTMLFormElement.reportValidity()
```

### Return value

`布尔`Example
-------


```js
document.forms["myform"].addEventListener(
  "invalid",
  function () {
    // Optional response here
  },
  false,
);

document.forms["myform"].addEventListener(
  "submit",
  function () {
    document.forms["myform"].reportValidity();
  },
  false,
);
```

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

| Specification |
| --- |
| HTML Standard # dom-cva-reportvalidity-dev |

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

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

`GlobalEventHandlers` 混入对象的属性 **`onformdata`** 是用于处理 `formdata` 事件的，它在整个列表展示所构建的表单数据之后被触发。触发会发生在表单发送时，但也可能由对某个`FormData()` 结构体的调用所触发。`onformdata` 在 `HTMLFormElement`上有效。

语法
--
```

target.onformdata = functionRef;
```

### Value

`functionRef` 是一个函数名或者称为 function expression. 此函数接受一个`FormDataEvent` (en-US)对象作为其唯一表达式参数。

示例
--


```js
// grab reference to form

const formElem = document.querySelector("form");

// submit handler

formElem.addEventListener("submit", (e) => {
  // on form submission, prevent default
  e.preventDefault();

  // construct a FormData object, which fires the formdata event
  new FormData(formElem);
});

// formdata handler to retrieve data

formElem.onformdata = (e) => {
  console.log("formdata fired");

  // Get the form data from the event object
  let data = e.formData;
  for (var value of data.values()) {
    console.log(value);
  }

  // submit the data via XHR
  var request = new XMLHttpRequest();
  request.open("POST", "/formHandler");
  request.send(data);
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-formdata |

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

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

参见
--

* `formdata` 事件
* `FormDataEvent` (en-US)
* 使用 FormData 对象
HTMLFormElement: submit event
=============================

当表单 `<form>` 提交的时候触发 `submit` 事件。

|  |  |
| --- | --- |
| 是否冒泡 | 是（虽然其通常被看作不冒泡的简单事件） |
| 是否可取消 | 是 |
| 接口 | `SubmitEvent` (en-US) |
| 事件处理器属性 | `GlobalEventHandlers.onsubmit` |

注意 `submit` 事件只能作用于 `<form>` 元素本身，不能作用于 `<button>` 或者 <input type="submit">。但 `SubmitEvent` (en-US) 被用于表单提交时，会携带 `submitter` 属性，这是触发提交请求时会调用的按钮。

当用户点击提交按钮（`<button>` 或 <input type="submit">），亦或是在表单里输入时（e.g. <input type="text">）按下 `Enter` 键，`submit` 事件将会被触发。直接调用 `form.submit()` 方法时，事件不会发送到表单。

**备注：** 当试图提交一个未通过验证的表单时，会触发 `invalid` 事件。在这种情况下，表单提交将会被验证机制阻止。因此，`sumbit` 事件也就不存在了。

示例
--

这个示例使用 `EventTarget.addEventListener()` 去监听表单的提交。并记录当前的 `Event.timeStamp`，然后阻止提交表单的默认操作。

### HTML


```html
<form id="form">
  <label>Test field: <input type="text" /></label>
  <br /><br />
  <button type="submit">Submit form</button>
</form>
<p id="log"></p>
```

### JavaScript


```js
function logSubmit(event) {
  log.textContent = `Form Submitted! Time stamp: ${event.timeStamp}`;
  event.preventDefault();
}

const form = document.getElementById("form");
const log = document.getElementById("log");
form.addEventListener("submit", logSubmit);
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # event-submit |
| HTML Standard # handler-onsubmit |

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

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

参见
--

* HTML `<form>` 元素
* 相关事件：`invalid`
HTMLFormElement.enctype
=======================

**`HTMLFormElement.enctype`** 属性常用来指明提交表单的内容类型，可选的值如下：

* `application/x-www-form-urlencoded`: 初始的默认值
* `multipart/form-data`: 适用于使用`<input>` 标签上传文件
* `text/plain`: HTML5 引入的类型

这些值可以通过元素 `<button>` or `<input>` 的属性 form.enctype 来改写

语法
--
```

string = form.enctype
form.enctype = string
```

例子
--
```

form.enctype = "application/x-www-form-urlencoded";
```

参考
--

HTML 5, Section 4.10.19.6, Form submission

DOM Level 2 HTML: enctype
form.submit
===========

**`HTMLFormElement.submit()`** 用来提交表单 `<form>`。

这个方法和触发提交表单按钮很类似，但有所不同：

* 没有引发 `submit` 事件。即，表单的 `onsubmit` 事件处理程序不会运行。
* 不会触发约束验证 。

`HTMLFormElement.requestSubmit()` 方法与触发表单提交的 `<button>` 的效果是相同的。

如果一个表单控件（比如一个提交按钮）的 `name` 或 `id` 的值为 `submit`，则它将覆盖表单的 submit 方法。

使用 `HTMLFormElement.submit()` 方法时，属性 `type="submit"` 的 `<input>` 不会与表单一起被提交，但在使用原始的 HTML 表单提交时，它将被提交。

语法
--


```js
submit()
```

### 参数

无。

### 返回值

无（`undefined`）。

示例
--


```js
document.forms["myform"].submit();
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-form-submit-dev |

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

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

`HTMLFormElement` 的 **`requestSubmit()`** 方法要求使用一个指定的提交按钮提交表单。

语法
--


```js
requestSubmit()
requestSubmit(submitter)
```

### 参数

`submitter` 可选

提交按钮，其属性描述了提交表单的方式。可以是 `type` 属性为 `submit` 的 `<input>` 或 `<button>` 元素。

如果你省略了 `submitter` 参数，表单元素自身会作为 submitter 使用。

### 返回值

无（`undefined`）。

### 异常

`TypeError`

如果指定的 `submitter` 不是一个提交按钮则抛出该错误。

`NotFoundError` `DOMException`

如果调用 `requestSubmit()` 时指定的 `submitter` 不是表单的成员则抛出该错误。submitter 必须是一个表单元素的后代或者必须具有引用表单的 `form` 属性。

使用说明
----

显而易见的问题是：我们一开始就有 `submit()` 方法，为什么还要有这个方法？

答案是显而易见的。`submit()` 仅仅是提交表单。而 `requestSubmit()` 的行为就像是点击了提交按钮一样。表单的内容会被验证并且表单仅在验证通过时提交。表单在被提交后，表单对象上会触发 `submit` 事件。

示例
--

在下面的示例中，如果可用，会尝试使用 `requestSubmit()` 发送请求提交表单。如果一个找到有 ID 为 `main-submit` 的提交按钮，则将其用于提交表单。否则，表单提交时不携带 `submitter` 参数，所以直接由表单自己提交。

另一方面，如果 `requestSubmit()` 不是可用的，这个代码回退到调用表单的 `submit()` 方法。


```js
let myForm = document.querySelector("form");
let submitButton = myForm.querySelector("#main-submit");

if (myForm.requestSubmit) {
  if (submitButton) {
    myForm.requestSubmit(submitButton);
  } else {
    myForm.requestSubmit();
  }
} else {
  myForm.submit();
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-form-requestsubmit-dev |

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

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

当表单被重置时触发`reset`事件。

综合信息
----

Specification

HTML5

Interface
`Event`
Bubbles

是（可以指定不发生冒泡的简单事件）

Cancelable

是

Target

Element

默认行为

重置父表单元素所有的值。

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | `EventTarget` | 事件的目标（DOM 树最顶端的元素）。 |
| `type` 只读  | `DOMString` | 事件的类型。 |
| `bubbles` 只读  | `Boolean` | 是否指定事件冒泡。 |
| `cancelable` 只读  | `Boolean` | 事件是否可以被取消。 |

规范
--

| Specification |
| --- |
| HTML Standard # event-reset |
form.reset
==========

### 概述

`reset` 方法可以重置一个表单内的所有表单控件的值到初始状态。

### 语法
```

HTMLFormElement.reset()
```

### 例子
```

document.forms["myform"].reset();
```

### 备注

运行该方法和点击表单的重置按钮是一样的效果。

### 规范

DOM Level 2 HTML: reset
MediaDevices.getDisplayMedia()
==============================

这个 `MediaDevices` 接口的 **`getDisplayMedia()`** 方法提示用户去选择和授权捕获展示的内容或部分内容（如一个窗口）在一个`MediaStream` 里。然后，这个媒体流可以通过使用 MediaStream Recording API 被记录或者作为WebRTC 会话的一部分被传输。

去 Using the Screen Capture API (en-US) 查找更多详情和例子。

语法
--
```

var promise = navigator.mediaDevices.getDisplayMedia(constraints);
```

### 参数

`constraints` 可选

一个可选的`MediaStreamConstraints` (en-US)对象，它指定了返回的`MediaStream`的要求。因为`getDisplayMedia()`需要视频轨道，所以即使`constraints` 对象没有明确请求视频轨道，返回的流也会有一个。

### 返回值

一个被解析为 `MediaStream` 的 `Promise`，其中包含一个视频轨道。视频轨道的内容来自用户选择的屏幕区域以及一个可选的音频轨道。

**备注：** 浏览器对音频的支持程度各不相同，既取决于是否支持，也取决于音频源。点击 浏览器兼容性 来查看各个浏览器的支持性。

### 异常

来自返回的 promise 的拒绝是通过将`DOMException`错误对象传递给 promise 的失败处理程序来进行的。可能的错误是：

`AbortError` ［中止错误］

发生了与以下任何其他异常不匹配的错误或故障。

`InvalidStateError` ［拒绝错误］

调用 `getDisplayMedia()` 的 context 中的 `document` 不是完全激活的; 例如，也许它不是最前面的标签。

`NotAllowedError` ［拒绝错误］

用户拒绝授予访问屏幕区域的权限，或者不允许当前浏览实例访问屏幕共享。

`NotFoundError` ［找不到错误］

没有可用于捕获的屏幕视频源。

`NotReadableError` ［无法读取错误］

用户选择了屏幕，窗口，标签或其他屏幕数据源，但发生了硬件或操作系统级别错误或锁定，从而预先占用了共享所选源。

`OverconstrainedError` ［转换错误］

创建流后，由于无法生成兼容的流导致应用指定的 `constraints` 失效。

`TypeError` ［类型错误］

指定的 `constraints` 包括调用 `getDisplayMedia()` 时不允许的`constraints`。这些不受支持的`constraints`是 `advanced` 的，任何约束又有一个名为 `min` 或 `exact` 的成员。

示例
--

在下面的示例中，我们创建了一个 `startCapture()` 方法，该方法在给定由 `displayMediaOptions` 参数指定的一组选项的情况下启动屏幕捕获。选项以 `MediaStreamConstraints` (en-US)对象的形式指定，该对象指定首选流配置和从中捕获视频的显示表面


```js
async function startCapture(displayMediaOptions) {
  let captureStream = null;

  try {
    captureStream =
      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
  } catch (err) {
    console.error("Error: " + err);
  }
  return captureStream;
}
```


这里使用 `await` 来进行异步等待 `getDisplayMedia()`来进行 `MediaStream`解析，其中包含指定选项所请求的显示内容。之后，流被返回给调用者以供其使用，可能是使用 `RTCPeerConnection.addTrack()`添加到 WebRTC 调用来从流中添加视频轨道。

规范
--

| Specification |
| --- |
| Screen Capture # dom-mediadevices-getdisplaymedia |

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

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

参考
--

* Screen Capture API
* Using the Screen Capture API (en-US)
* 媒体捕捉与媒体流 API
* WebRTC API
* `getUserMedia()`: Capturing media from a camera and/or microphone
MediaDevices.enumerateDevices()
===============================

`MediaDevices` 的方法 **`enumerateDevices()`** 请求一个可用的媒体输入和输出设备的列表，例如麦克风，摄像机，耳机设备等。返回的 `Promise` (en-US) 完成时，会带有一个描述设备的 `MediaDeviceInfo` (en-US) 的数组。

语法
--
```

var enumeratorPromise = navigator.mediaDevices.enumerateDevices();
```

### 返回值

返回一个 `Promise` (en-US) 。当完成时，它接收一个 `MediaDeviceInfo` (en-US) 对象的数组。每个对象描述一个可用的媒体输入输出设备。.

如果枚举失败，promise 也会被拒绝（rejected）。

示例
--

这是一个使用 `enumerateDevices()` 的例子。它只是输出一个带有标签（有标签的情况下）的 device ID (en-US) 的列表。


```js
if (!navigator.mediaDevices || !navigator.mediaDevices.enumerateDevices) {
  console.log("不支持 enumerateDevices() .");
  return;
}

// 列出相机和麦克风。

navigator.mediaDevices
  .enumerateDevices()
  .then(function (devices) {
    devices.forEach(function (device) {
      console.log(
        device.kind + ": " + device.label + " id = " + device.deviceId,
      );
    });
  })
  .catch(function (err) {
    console.log(err.name + ": " + err.message);
  });
```


这将会输出类似以下的内容：
```

videoinput: id = csO9c0YpAf274OuCPUA53CNE0YHlIr2yXCi+SqfBZZ8=
audioinput: id = RKxXByjnabbADGQNNZqLVLdmXlS0YkETYCIbg+XxnvM=
audioinput: id = r2/xw1xUPIyZunfV1lGrKOma5wTOvCkWfZ368XCndm0=
```


或者，如果有一个或多个 `MediaStream` 处于活动状态或者获得了持久授权，将会输出以下内容：
```

videoinput: FaceTime HD Camera (Built-in) id=csO9c0YpAf274OuCPUA53CNE0YHlIr2yXCi+SqfBZZ8=
audioinput: default (Built-in Microphone) id=RKxXByjnabbADGQNNZqLVLdmXlS0YkETYCIbg+XxnvM=
audioinput: Built-in Microphone id=r2/xw1xUPIyZunfV1lGrKOma5wTOvCkWfZ368XCndm0=
```

规范
--

| Specification |
| --- |
| Media Capture and Streams # dom-mediadevices-enumeratedevices |

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

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

See also
--------

* `navigator.mediaDevices.getUserMedia()` (en-US)
* WebRTC (en-US) - the introductory page to the API
* MediaStream API (en-US) - the API for the media stream objects
* Taking webcam photos (en-US) - a tutorial on using `getUserMedia()` for taking photos rather than video.
MediaDevices.getSupportedConstraints()
======================================

`MediaDevices` 接口的 **`getSupportedConstraints()`** 方法返回一个基于 `MediaTrackSupportedConstraints` (en-US) 的对象，其成员字段都是客户端（user agent）所支持的约束属性（如帧率，窗口大小）。

语法
--
```

var supportedConstraints = navigator.mediaDevices.getSupportedConstraints();
```

### 参数

无

### 返回值

一个新的基于`MediaTrackSupportedConstraints` (en-US) 的对象用来监视客户端所支持的约束属性。因为只有客户端所支持的约束属性才能被展示在这个列表中 , 这些布尔值（Boolean）属性的每一个都为 true。

示例
--

这个示例展示了你的客户端所支持的约束属性的列表。
```

<p>The following media constraints are supported by your browser:</p>

<ul id="constraintList"></ul>
```


```
body {
  font:
    15px Arial,
    sans-serif;
}
```



```js
let constraintList = document.getElementById("constraintList");
let supportedConstraints = navigator.mediaDevices.getSupportedConstraints();

for (let constraint in supportedConstraints) {
  if (supportedConstraints.hasOwnProperty(constraint)) {
    let elem = document.createElement("li");

    elem.innerHTML = "<code>" + constraint + "</code>";
    constraintList.appendChild(elem);
  }
}
```

### 结果

规范
--

| Specification |
| --- |
| Media Capture and Streams # dom-mediadevices-getsupportedconstraints |

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

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

每当媒体设备（例如相机，麦克风或扬声器）连接到系统或从系统中移除时，`devicechange` 事件就会被发送到 `MediaDevices` 实例。这是一个没有附加属性的通用 `Event` 。

一般信息
----

接口

Event

是否冒泡

No

是否可取消

No

对象
`MediaDevices`
默认动作

None

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target`只读  | `EventTarget` | 事件对象 (位于 DOM 树最上面的元素). |
| `type` 只读  | `DOMString` | 事件类型。 |
| `bubbles` 只读  | `Boolean` (en-US) | 是否冒泡 |
| `cancelable` 只读  | `Boolean` (en-US) | 是否可被取消 |

相关事件
----

*无*.

样例
--

TBD

规范
--

| Specification |
| --- |
| Media Capture and Streams # event-mediadevices-devicechange |
| Media Capture and Streams # dom-mediadevices-ondevicechange |

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

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

参见
--

* `MediaDevices.ondevicechange`
TextEncoder.encode()
====================

**`TextEncoder.encode()`** 方法接受一个字符串作为输入，返回一个对参数中给定的文本的编码后的 `Uint8Array`，编码的方法通过 `TextEncoder` 对象指定。

语法
--


```js
encode(string)
```

### 参数

`string`

一个包含了将要编码的文本。

### 返回值

一个 `Uint8Array` (en-US) 对象。

示例
--


```html
<p class="source">This is a sample paragraph.</p>
<p class="result">Encoded result:</p>
```



```js
const sourcePara = document.querySelector(".source");
const resultPara = document.querySelector(".result");
const string = sourcePara.textContent;

const textEncoder = new TextEncoder();

let encoded = textEncoder.encode(string);
resultPara.textContent += encoded;
```

规范
--

| Specification |
| --- |
| Encoding Standard # ref-for-dom-textencoder-encode① |

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

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

参见
--

* 属于 `TextEncoder` 接口。
TextEncoder.encoding
====================

**`TextEncoder.encoding`** 只读属性返回一个字符串，其中包含特定编码器使用的编码算法的名称。

它只能具有以下值：`utf-8`。

值
-

值为 `utf-8` 的字符串。

规范
--

| Specification |
| --- |
| Encoding Standard # dom-textencoder-encoding |

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

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

参见
--

* 属于 `TextEncoder` 接口。
TextEncoder()
=============

**`TextEncoder()`** 构造函数总是返回一个新创建的 `TextEncoder` 对象，该对象将生成具有 UTF-8 编码的字节流。

语法
--


```js
new TextEncoder();
```

### 参数

无。

规范
--

| Specification |
| --- |
| Encoding Standard # ref-for-dom-textencoder① |

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

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

参见
--

* 属于 `TextEncoder` 接口。
PromiseRejectionEvent.promise
=============================

`PromiseRejectionEvent`事件对象的 **`promise`** 属性是只读的，表明 Promise 被 reject 的原因。你可以通过检查`PromiseRejectionEvent.reason` (en-US)来了解 Promise 为什么被 reject。

Syntax
------
```

promise = PromiseRejectionEvent.promise
```

### Value

一个被 reject 的，并且错误未被处理的`Promise`

Examples
--------

下面的例子监听了未被处理的 promise，如果`reason` (en-US) 是一个对象，并且其`code`属性包含了一段文本“Module not read.”，一个空闲的回调函数被声明，当任务执行错误时会进行重试

`event.preventDefault()` 用来表明该 promise 已被处理


```js
window.onunhandledrejection = function (event) {
  if (event.reason.code && event.reason.code == "Module not ready") {
    window.requestIdleCallback(function (deadline) {
      loadModule(event.reason.moduleName).then(performStartup);
    });
    event.preventDefault();
  }
};
```

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

| Specification |
| --- |
| HTML Standard # dom-promiserejectionevent-promise |

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

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

参见
--

* `Promise`
* `PromiseRejectionEvent`
* `rejectionhandled`
* `unhandledrejection`
PromiseRejectionEvent.PromiseRejectionEvent()
=============================================

**`PromiseRejectionEvent()`** 构造器返回一个新创建的 `PromiseRejectionEvent`，代表一个 JavaScript `Promise`被 rejected 时触发的事件。

语法
--
```

new PromiseRejectionEvent(type, {
  promise: somePromise,
  reason : someValue
});
```

### 参数

*`PromiseRejectionEvent()` 构造函数继承了 `Event()`的参数。*

`type`

一个代表 PromiseRejectionEvent 的类型名称的字符串。这是区分大小写的同时必须是 `rejectionhandled` 或者 `unhandledrejection` 其中之一。

`promise`

代表被 rejected 的`Promise`。

`reason`

代表 promise 被 rejected 的原因的值或者对象`Object` 。

例子
--


```js
var myRejectionEvent = new PromiseRejectionEvent("unhandledrejection", {
  promise: myPromise,
  reason: "My house is on fire",
});
```

规范
--

| Specification |
| --- |
| HTML Standard # unhandled-promise-rejections:dom-event-constructor |

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

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

参见
--

* `Promise`
* `PromiseRejectionEvent`
CacheStorage.keys()
===================

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

`CacheStorage` 接口的 **`keys()`** 方法返回一个 `Promise`对象，它使用一个数组 resolve，该数组包含 `CacheStorage` 对象按创建顺序跟踪的所有命名 `Cache` 对象对应的字符串。使用此方法迭代所有 `Cache` 对象。

语法
--
```

caches.keys().then(function(keyList) {
  //对 keyList 做操作
});
```

### 返回

一个使用 `CacheStorage` 对象中 `Cache` 名称数组 resolve 的 `Promise`

### 参数

无。

示例
--

在此代码片段中，我们监听`activate` 事件，然后运行一个 `waitUntil()` 方法，该方法在新的 service worker 被激活之前清除老的、无用的 cache。这里我们设置一个包含缓存名称的白名单。通过使用 `keys()` 方法来返回 `CacheStorage` 对象中的 keys 集合，然后检查缓存 key 是否在白名单中，如果不存在，则使用 `CacheStorage.delete` 方法来删除该缓存。


```js
this.addEventListener('activate', function(event) {
  var cacheWhitelist = ['v2'];

  event.waitUntil(
    caches.keys().then(function(keyList) {
      return Promise.all(keyList.map(function(key) {
        if (cacheWhitelist.indexOf(key) === -1) {
          return caches.delete(key);
        }
      });
    })
  );
});
```

规范
--

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

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

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.match()
====================

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

`CacheStorage` 接口 (可适用于全局性`caches`) 的 **`match()`** 方法检查给定的`Request` 对象或 url 字符串是否是一个已存储的 `Response` 对象的 key. 这个方法针对 `Response` 返回一个 `Promise` ，如果没有匹配则返回 `undefined` 。

cache 对象按创建顺序查询。

**备注：** `caches.match()` 是一个便捷方法。其作用等同于在每个缓存上调用 `cache.match()` 方法（按照`caches.keys()`返回的顺序) 直到返回`Response` 对象。

语法
--
```

caches.match(request, options).then(function(response) {
  // Do something with the response
});
```

### 参数

request

想要匹配的 `Request`。这个参数可以是 `Request` 对象或 URL 字符串。

options 可选

这个对象中的属性控制在匹配操作中如何进行匹配选择。可选择参数如下：

* `ignoreSearch`: `Boolean` (en-US)值，指定匹配过程是否应该忽略 url 中查询参数。举个例子，如果该参数设置为`true`, 那么 `?value=bar` 作为 `http://foo.com/?value=bar` 中的查询参数将会在匹配过程中被忽略。该参数默认 `false`。
* `ignoreMethod`: `Boolean` (en-US) 值，当被设置为 `true` 时，将会阻止在匹配操作中对 `Request`请求的 `http` 方式的验证 (通常只允许 `GET` 和 `HEAD` 两种请求方式)。该参数默认为 `false`.
* `ignoreVary`: `Boolean` (en-US) 值，当该字段被设置为 `true`, 告知在匹配操作中忽略对`VARY`头信息的匹配。换句话说，当请求 URL 匹配上，你将获取匹配的 `Response` 对象，无论请求的 `VARY` 头存在或者没有。该参数默认为 `false`.
* `cacheName`: `DOMString` 值，表示所要搜索的缓存名称。

### 返回值

返回 resolve 为匹配 `Response` 的 `Promise` 对象。如果没有与指定 request 相匹配 response，promise 将使用 `undefined` resolve.

例子
--

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

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


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

规范
--

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

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

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

亦可参考
----

* Using Service Workers (en-US)
* `Cache`
* `self.caches` (en-US)
CacheStorage.delete()
=====================

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

`CacheStorage` 接口的 **`delete()`** 方法查找匹配 `cacheName` 的 `Cache` 对象，如果找到，则删除 `Cache` 对象并返回一个 resolve 为 true 的 `Promise` . 如果未找到 `Cache` 对象，则返回 `false`.

语法
--
```

caches.delete(cacheName).then(function(true) {
  //your cache is now deleted
});
```

### Returns

如果找到 `Cache` 对象，删除它，返回一个 resolve 为 `true` 的 `Promise` ，否则，返回 `false` .

### Parameters

cacheName

想要删除的 cache 对象的名称。

实例
--

在此代码片段中，我们等待一个 activate 事件，然后运行一个 `waitUntil()` 块，其在一个新的 service worker 被激活前清除所有旧的、未使用的 cache. 这里我们有一个白名单，其中包含我们想要保留的 cache 的 name. 我们使用 `CacheStorage.keys` 返回 `CacheStorage` 对象中 cache 的键，然后检查每个键值，以查看它是否在白名单中。如果没有，我们使用 `delete()` 删除它。


```js
this.addEventListener("activate", function (event) {
  var cacheWhitelist = ["v2"];

  event.waitUntil(
    caches.keys().then(function (keyList) {
      return Promise.all(
        keyList.map(function (key) {
          if (cacheWhitelist.indexOf(key) === -1) {
            return caches.delete(key);
          }
        }),
      );
    }),
  );
});
```

规范
--

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

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

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)