FileSystemDirectoryHandle - Web API 接口参考

FileSystemDirectoryHandle
=========================

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

File System API 的 **`FileSystemDirectoryHandle`** 接口提供指向一个文件系统目录的句柄。

这个接口可以通过 `window.showDirectoryPicker()`、`StorageManager.getDirectory()` (en-US)、`DataTransferItem.getAsFileSystemHandle()` (en-US) 和 `FileSystemDirectoryHandle.getDirectoryHandle()` 这些方法访问。

FileSystemHandle

FileSystemDirectoryHandle实例属性
----

*从父接口 `FileSystemHandle` 继承属性。*

实例方法
----

*从父接口 `FileSystemHandle` 继承方法。*

常规方法：

`FileSystemDirectoryHandle.getDirectoryHandle()`

返回一个 `Promise`，会兑现一个调用此方法的目录句柄内指定名称的子目录的 `FileSystemDirectoryHandle`。

`FileSystemDirectoryHandle.getFileHandle()`

返回一个 `Promise`，会兑现一个调用此方法的目录句柄内指定名称的文件的 `FileSystemFileHandle`。

`FileSystemDirectoryHandle.removeEntry()`

如果目录句柄包含一个名为指定名称的文件或目录，则尝试异步将其移除。

`FileSystemDirectoryHandle.resolve()`

返回一个 `Promise` 对象，会兑现一个包含从父目录前往指定子条目中间的目录的名称的数组。数组的最后一项是子条目的名称。

异步迭代器方法：

`FileSystemDirectoryHandle.entries()`

返回一个新的迭代 `FileSystemDirectoryHandle` 对象内每个条目的键值对的异步迭代器。

`FileSystemDirectoryHandle.keys()`

返回一个新的迭代 `FileSystemDirectoryHandle` 对象内每个条目的键的异步迭代器。

`FileSystemDirectoryHandle.values()`

返回一个新的迭代 `FileSystemDirectoryHandle` 对象内每个条目的句柄的异步迭代器。

`FileSystemDirectoryHandle[@@asyncIterator]()`

默认情况下返回 `entries` 函数。

示例
--

### 返回目录句柄

下面的示例返回一个指定名称的目录句柄，如果对应的目录不存在则创建。

```js
const dirName = "directoryToGetName";

// 假设我们有一个目录句柄：'currentDirHandle'
const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true });
```

### 返回文件路径

下面的异步函数使用 `resolve()` 来查找被选择文件相对于指定目录句柄的路径。

```js
async function returnPathDirectories(directoryHandle) {
  // 通过显示文件选择器来获得一个文件句柄
  const [handle] = await self.showOpenFilePicker();
  if (!handle) {
    // 如果用户取消了选择或者打开文件失败
    return;
  }

  // 检查文件句柄是否存在于目录句柄的目录中
  const relativePaths = await directoryHandle.resolve(handle);

  if (relativePaths === null) {
    // 不在目录句柄中
  } else {
    // relativePaths 是一个包含名称的数组，指示相对路径

    for (const name of relativePaths) {
      // 打印数组的每个元素
      console.log(name);
    }
  }
}
```

### 返回目录中所有文件的句柄

下面的示例会递归地扫描一个目录，以返回目录中每个文件的 `FileSystemFileHandle` 对象：

```js
async function\* getFilesRecursively(entry) {
  if (entry.kind === "file") {
    const file = await entry.getFile();
    if (file !== null) {
      file.relativePath = getRelativePath(entry);
      yield file;
    }
  } else if (entry.kind === "directory") {
    for await (const handle of entry.values()) {
      yield\* getFilesRecursively(handle);
    }
  }
}
for await (const fileHandle of getFilesRecursively(directoryHandle)) {
  console.log(fileHandle);
}
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemdirectoryhandle |

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

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

参见
--

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


WebGLRenderingContext - Web API 接口参考

WebGLRenderingContext
=====================

**`WebGLRenderingContext`** 接口提供基于 OpenGL ES 2.0 的绘图上下文，用于在 HTML `<canvas>` 元素内绘图。

要获得这个接口的对象以用于 2D 和 3D 的图形渲染，可以通过在 `<canvas>` 元素上调用 `getContext()` 函数，调用时传入“webgl”参数：

```js
const canvas = document.getElementById("myCanvas");
const gl = canvas.getContext("webgl");
```

当你获取到 canvas 元素的 WebGL 绘图上下文，你便可以在里面绘图。点击 WebGL 教程获取更多资料，例如，关于如何开始 WebGL 编程的知识。

如果你需要一个 WebGL 2.0 的上下文，请参见 `WebGL2RenderingContext`；其提供了对 OpenGL ES 3.0 图形实现的支持。

常量
--

请参考 WebGL 常量页面。

WebGL 上下文
---------

以下的属性和方法提供只读的 WebGL 上下文的信息和特性：

`WebGLRenderingContext.canvas`

只读属性，对 `HTMLCanvasElement` 的向后引用。如果上下文没有相联系的 `<canvas>` 元素，值将会为 `null`。

`WebGLRenderingContext.commit()`
实验性

如果上下文没有指定的 canvas，把帧交给原始的`HTMLCanvasElement`元素。

`WebGLRenderingContext.drawingBufferWidth`

只读属性，当前绘图缓冲区的宽度，等于和该上下文相联系的 canvas 元素的宽度。

`WebGLRenderingContext.drawingBufferHeight`

只读属性，当前绘图缓冲区的高度，等于和该上下文相联系的 canvas 元素的高度。

`WebGLRenderingContext.getContextAttributes()`

返回 `WebGLContextAttributes` 对象，该对象包含真实的上下文参数。如果上下文丢失，将会返回 `null`。

`WebGLRenderingContext.isContextLost()`

如果上下文丢失，返回 `true`；否则，返回 `false`。

`WebGLRenderingContext.makeXRCompatible()` (en-US)

确保上下文与用户的 XR 硬件的兼容性，必要时使用新配置重新创建上下文。这可用于启动使用标准 2D 演示的应用程序，然后过度到使用 VR 或 AR 模式。

视图和裁剪
-----

`WebGLRenderingContext.scissor()`

设置裁剪框。

`WebGLRenderingContext.viewport()`

设置视口。

状态信息
----

`WebGLRenderingContext.activeTexture()`

选择要激活的纹理单元。

`WebGLRenderingContext.blendColor()`

设置源和目标的混和因子。

`WebGLRenderingContext.blendEquation()`

用同一个表达式设置 RGB 混和表达式和 alpha 混和表达式。

`WebGLRenderingContext.blendEquationSeparate()` (en-US)

分开设置 RGB 混和表达式和 alpha 混和表达式。

`WebGLRenderingContext.blendFunc()`

定义用于像素混合算法的函数。

`WebGLRenderingContext.blendFuncSeparate()` (en-US)

分别定义混合像素 RGB 通道和透明通道的函数。

`WebGLRenderingContext.clearColor()`

设置用于清空用的颜色。

`WebGLRenderingContext.clearDepth()`

设置清除深度缓存时的深度值。

`WebGLRenderingContext.clearStencil()` (en-US)

设置清除模板缓冲区时的模板值。

`WebGLRenderingContext.colorMask()` (en-US)

设置在绘制或渲染`WebGLFramebuffer`时要开启或关闭的颜色分量。

`WebGLRenderingContext.cullFace()`

设置多边形的正面和/或反面是否要被排除。

`WebGLRenderingContext.depthFunc()`

设置比较输入像素深度和深度缓存值得函数。

`WebGLRenderingContext.depthMask()`

设置是否写入深度缓存。

`WebGLRenderingContext.depthRange()` (en-US)

设置从规范化设备坐标映射到窗口或视口坐标时的深度范围。

`WebGLRenderingContext.disable()` (en-US)

禁用这个上下文的 WebGL 功能。

`WebGLRenderingContext.enable()`

启用这个上下文的 WebGL 功能。

`WebGLRenderingContext.frontFace()` (en-US)

设置多边形的正面使用顺时针还是逆时针绘制表示。

`WebGLRenderingContext.getParameter()`

返回给入参数名的值。

`WebGLRenderingContext.getError()` (en-US)

返回错误信息。

`WebGLRenderingContext.hint()` (en-US)

给某些行为设置建议使用的模式。具体建议需要看执行的情况。

`WebGLRenderingContext.isEnabled()`

测试这个上下文的 WebGL 功能是否开启。

`WebGLRenderingContext.lineWidth()` (en-US)

设置线宽。

`WebGLRenderingContext.pixelStorei()`

设置像素存储模式。

`WebGLRenderingContext.polygonOffset()`

设置多边形偏移的比例和单位，从而计算深度值。（补充：解决深度冲突）

`WebGLRenderingContext.sampleCoverage()` (en-US)

为抗锯齿效果设置多重取样覆盖参数。

`WebGLRenderingContext.stencilFunc()` (en-US)

同时设置前面和背面的模板测试函数，及其引用值。

`WebGLRenderingContext.stencilFuncSeparate()` (en-US)

可分开设置前面或背面的模板测试函数，及其引用值。

`WebGLRenderingContext.stencilMask()` (en-US)

同时启用或禁用，前面和背面的模板测试掩码。

`WebGLRenderingContext.stencilMaskSeparate()` (en-US)

可分开启用或禁用，前面和背面的模板测试掩码。

`WebGLRenderingContext.stencilOp()` (en-US)

同时设置，在前面和背面的模板缓冲区上执行的操作。

`WebGLRenderingContext.stencilOpSeparate()` (en-US)

可分开设置，在前面和背面的模板缓冲区上执行的操作。

缓冲区
---

`WebGLRenderingContext.bindBuffer()`

把 `WebGLBuffer` 对象绑定到指定目标上。

`WebGLRenderingContext.bufferData()`

更新缓冲数据。

`WebGLRenderingContext.bufferSubData()` (en-US)

更新从给入偏移量开始的缓冲数据。

`WebGLRenderingContext.createBuffer()`

创建 `WebGLBuffer` 对象。

`WebGLRenderingContext.deleteBuffer()`

删除 `WebGLBuffer` 对象。

`WebGLRenderingContext.getBufferParameter()` (en-US)

返回缓冲信息。

`WebGLRenderingContext.isBuffer()`

返回给入的缓冲是否有效。

帧缓冲区
----

`WebGLRenderingContext.bindFramebuffer()`

把 `WebGLFrameBuffer` 对象绑定到指定对象上。

`WebGLRenderingContext.checkFramebufferStatus()` (en-US)

返回帧缓冲区的状态。

`WebGLRenderingContext.createFramebuffer()`

创建 `WebGLFrameBuffer` 对象。

`WebGLRenderingContext.deleteFramebuffer()`

删除 `WebGLFrameBuffer` 对象。

`WebGLRenderingContext.framebufferRenderbuffer()` (en-US)

把 `WebGLRenderingBuffer` 对象附加到 `WebGLFrameBuffer` 对象。

`WebGLRenderingContext.framebufferTexture2D()` (en-US)

把纹理图像附加到 `WebGLFrameBuffer` 对象。

`WebGLRenderingContext.getFramebufferAttachmentParameter()` (en-US)

返回帧缓冲区的信息。

`WebGLRenderingContext.isFramebuffer()` (en-US)

返回布尔值，表示给入的 `WebGLFrameBuffer` 对象是否有效。

`WebGLRenderingContext.readPixels()`

读取 `WebGLFrameBuffer` 的像素。

渲染缓冲区
-----

`WebGLRenderingContext.bindRenderbuffer()`

把 `WebGLRenderBuffer` 对象绑定到指定的对象上。

`WebGLRenderingContext.createRenderbuffer()`

创建 `WebGLRenderBuffer` 对象。

`WebGLRenderingContext.deleteRenderbuffer()`

删除 `WebGLRenderBuffer` 对象。

`WebGLRenderingContext.getRenderbufferParameter()` (en-US)

返回渲染缓冲区的信息。

`WebGLRenderingContext.isBuffer()`

返回布尔值，表示给入的 `WebGLRenderingBuffer` 是否有效。

`WebGLRenderingContext.renderbufferStorage()`

创建渲染缓冲区数据存储。

纹理
--

`WebGLRenderingContext.bindTexture()`

把 `WebGLTexture` 对象绑定到指定对象上。

`WebGLRenderingContext.compressedTexImage2D()` (en-US)

指定一个为压缩格式的 2D 纹理图片。

`WebGLRenderingContext.compressedTexSubImage2D()` (en-US)

指定一个为压缩格式的 2D 纹理子图片。

`WebGLRenderingContext.copyTexImage2D()` (en-US)

复制 2D 纹理图片。

`WebGLRenderingContext.copyTexSubImage2D()` (en-US)

复制 2D 纹理子图片。

`WebGLRenderingContext.createTexture()`

创建 `WebGLTexture` 对象。

`WebGLRenderingContext.deleteTexture()`

删除 `WebGLTexture` 对象。

`WebGLRenderingContext.generateMipmap()` (en-US)

为 `WebGLTexture` 对象生成一组纹理映射。

`WebGLRenderingContext.getTexParameter()`

返回纹理信息。

`WebGLRenderingContext.isTexture()` (en-US)

返回 Boolean 值，表示给入的 `WebGLTexture` 是否有效。

`WebGLRenderingContext.texImage2D()`

指定 2D 纹理图片。

`WebGLRenderingContext.texSubImage2D()` (en-US)

更新当前 `WebGLTexture` 的子矩形。

`WebGLRenderingContext.texParameterf()` (en-US)

设置纹理参数。

`WebGLRenderingContext.texParameteri()` (en-US)

设置纹理参数。

程序对象和着色器对象
----------

`WebGLRenderingContext.attachShader()`

把 `WebGLShader` 添加到 `WebGLProgram`。

`WebGLRenderingContext.bindAttribLocation()`

绑定一个普通顶点索引到一个命名的 attribute 变量

`WebGLRenderingContext.compileShader()`

编译 `WebGLShader`。

`WebGLRenderingContext.createProgram()`

创建 `WebGLProgram`。

`WebGLRenderingContext.createShader()`

创建 `WebGLShader`。

`WebGLRenderingContext.deleteProgram()`

删除 `WebGLProgram`。

`WebGLRenderingContext.deleteShader()`

删除 `WebGLShader`。

`WebGLRenderingContext.detachShader()`

分离 `WebGLShader`。

`WebGLRenderingContext.getAttachedShaders()` (en-US)

返回附加在 `WebGLProgram 上的` `WebGLShader` 对象的列表。

`WebGLRenderingContext.getProgramParameter()` (en-US)

返回程序对象的信息。

`WebGLRenderingContext.getProgramInfoLog()`

返回 `WebGLProgram` 对象的信息日志。

`WebGLRenderingContext.getShaderParameter()`

返回着色器的信息。

`WebGLRenderingContext.getShaderPrecisionFormat()` (en-US)

返回一个描述着色器数字类型精度的`WebGLShaderPrecisionFormat` 对象。

`WebGLRenderingContext.getShaderInfoLog()` (en-US)

返回 `WebGLShader` 对象的信息日志。

`WebGLRenderingContext.getShaderSource()`

以字符串形式返回 `WebGLShader` 的源码。

`WebGLRenderingContext.isProgram()`

返回一个 Boolean 值，表示给入的 `WebGLProgram` 是否有效。

`WebGLRenderingContext.isShader()`

返回一个 Boolean 值，表示给入的 `WebGLShader` 是否有效。

`WebGLRenderingContext.linkProgram()`

链接给入的 `WebGLProgram` 对象。

`WebGLRenderingContext.shaderSource()`

设置一个 `WebGLShader` 的源码。

`WebGLRenderingContext.useProgram()`

使用指定的 `WebGLProgram` 作为当前渲染状态的一部分。

`WebGLRenderingContext.validateProgram()`

使 `WebGLProgram` 生效。

Uniform 和 Attribute
-------------------

`WebGLRenderingContext.disableVertexAttribArray()` (en-US)

在给定的位置，禁用顶点 attribute 数组。

`WebGLRenderingContext.enableVertexAttribArray()`

在给定的位置，启用顶点 attribute 数组。

`WebGLRenderingContext.getActiveAttrib()` (en-US)

返回激活状态的 attribute 变量信息。

`WebGLRenderingContext.getActiveUniform()` (en-US)

返回激活状态的 uniform 变量信息。

`WebGLRenderingContext.getAttribLocation()`

返回 attribute 变量的指针位置。

`WebGLRenderingContext.getUniform()`

返回指定位置的 uniform 变量。

`WebGLRenderingContext.getUniformLocation()` (en-US)

返回 uniform 变量的指针位置。

`WebGLRenderingContext.getVertexAttrib()` (en-US)

返回指定位置的顶点 attribute 变量。

`WebGLRenderingContext.getVertexAttribOffset()` (en-US)

获取给定索引的顶点 attribute 位置。

`WebGLRenderingContext.uniform[1234][fi][v]()`

指定一个 uniform 变量。

`WebGLRenderingContext.uniformMatrix[234]fv()`

指定一个 uniform 矩阵变量。

`WebGLRenderingContext.vertexAttrib[1234]f[v]()`

指定一个普通顶点 attribute 的值。

`WebGLRenderingContext.vertexAttribPointer()`

指定一个顶点 attributes 数组中，顶点 attributes 变量的数据格式和位置。

绘制缓冲区
-----

`WebGLRenderingContext.clear()`

把指定的缓冲区清空为预设的值。

`WebGLRenderingContext.drawArrays()`

渲染数组中的原始数据。

`WebGLRenderingContext.drawElements()`

渲染元素数组中的原始数据。

`WebGLRenderingContext.finish()` (en-US)

阻断执行，直到之前所有的操作都完成。

`WebGLRenderingContext.flush()` (en-US)

清空缓冲的命令，这会导致所有命令尽快执行完。

色彩空间
----

`WebGLRenderingContext.drawingBufferColorSpace` (en-US)
实验性

指定 WebGL 绘制缓冲区的色彩空间。

`WebGLRenderingContext.unpackColorSpace` (en-US)
实验性

指定导入纹理时要转换到的色彩空间。

使用扩展插件
------

这些方法用于管理 WebGL 扩展：

`WebGLRenderingContext.getSupportedExtensions()`

返回一个包含字符串的 `Array`，每个元素都为支持的 WebGL 扩展。

`WebGLRenderingContext.getExtension()`

返回一个扩展对象。

规范
--

| Specification |
| --- |
| WebGL Specification # 5.14 |

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

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

参见
--

* `HTMLCanvasElement`


ReadableStreamDefaultReader - Web API 接口参考

ReadableStreamDefaultReader
===========================

Stream API 的 **ReadableStreamDefaultReader** 接口表示一个用于读取来自网络提供的流数据（例如 fetch 请求）的默认 reader。

`ReadableStreamDefaultReader` 可以用于读取底层为任意类型源的 `ReadableStream`（这与 `ReadableStreamBYOBReader` (en-US) 不同，后者仅可以和*底层为字节源*的可读流一起使用）。

然而，请注意，零拷贝传输仅支持自动分配缓冲区的底层字节源这一种底层源。换句话说，流必须同时指定构造函数中的 `type="bytes"` 和 `autoAllocateChunkSize`。对于任何其他底层源，流将始终使用来自内置队列的数据满足读取请求。

构造函数
----

`ReadableStreamDefaultReader()`

创建和返回一个 `ReadableStreamDefaultReader()` 对象实例。

实例属性
----

`ReadableStreamDefaultReader.closed`

返回一个 promise，该 promise 在流关闭时兑现，如果流抛出错误或 reader 的锁被释放，则拒绝。此属性使你能够编写响应流过程结束时执行的代码。

实例方法
----

`ReadableStreamDefaultReader.cancel()`

返回一个 `Promise`，当流被取消时兑现。调用该方法表示消费者对该流失去兴趣。提供的 `reason` 参数将会传递给底层源，其可能使用它，也可能不使用它。

`ReadableStreamDefaultReader.read()`

返回一个 promise，提供对流内部队列中下一个分块的访问权限。

`ReadableStreamDefaultReader.releaseLock()`

释放读取这个 stream 的锁。

示例
--

在下面的示例中，创建自定义 `Response`，将从其他资源获取的 HTML 片段流式传输到浏览器。

它展示了一个 `ReadableStream` 和一个 `Uint8Array` (en-US) 组合使用的例子。

```js
fetch("https://www.example.org/").then((response) => {
  const reader = response.body.getReader();
  const stream = new ReadableStream({
    start(controller) {
      // The following function handles each data chunk
      function push() {
        // "done" is a Boolean and value a "Uint8Array"
        return reader.read().then(({ done, value }) => {
          // Is there no more data to read?
          if (done) {
            // Tell the browser that we have finished sending data
            controller.close();
            return;
          }

          // Get the data and send it to the browser via the controller
          controller.enqueue(value);
          push();
        });
      }

      push();
    },
  });

  return new Response(stream, { headers: { "Content-Type": "text/html" } });
});
```

规范
--

| Specification |
| --- |
| Streams Standard # default-reader-class |

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

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

参见
--

* Stream API 概念
* 使用可读流
* `ReadableStream`
* WHATWG Stream Visualiser，用于可读、可写和转换流的基本可视化。
* Web-streams-polyfill 或 sd-streams——polyfill


caches - Web API 接口参考

caches
======

全局的 **`caches`** 只读属性返回与当前上下文紧密相关的 `CacheStorage` 对象。此对象激活了诸如存储用于离线使用的资源，并生成对请求的自定义响应等功能。

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

值
-

一个 `CacheStorage` 对象。

示例
--

以下示例展示了你在 service worker 上下文中应该如何运用 cache 对资源进行离线存储。

```js
this.addEventListener("install", function (event) {
  event.waitUntil(
    caches.open("v1").then(function (cache) {
      return cache.addAll([
        "/sw-test/",
        "/sw-test/index.html",
        "/sw-test/style.css",
        "/sw-test/app.js",
        "/sw-test/image-list.js",
        "/sw-test/star-wars-logo.jpg",
        "/sw-test/gallery/",
        "/sw-test/gallery/bountyHunters.jpg",
        "/sw-test/gallery/myLittleVader.jpg",
        "/sw-test/gallery/snowTroopers.jpg",
      ]);
    }),
  );
});
```

规范
--

| Specification |
| --- |
| Service Workers # self-caches |

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

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

参见
--

* Service Worker
* Web Worker
* `CacheStorage`
* `Cache`


GainNode - Web API 接口参考

GainNode
========

**`GainNode`** 接口表示音量的变化。它是一个 `AudioNode` 音频处理模块，在输出前使用给定*增益*应用到输入。一个 `GainNode` 始终只有一个输入和一个输出，两者拥有同样数量的声道。

增益是一个无单位的值，会对所有输入声道的音频进行相应的增加（相乘）。如果进行了修改，则会立即应用新增益，从而在结果音频中产生奇怪的“咔嗒”声。为了防止这种情况发生，请不要直接更改值，而应在 `AudioParam` 接口上使用指数插值方法。

![The GainNode is increasing the gain of the output.](/zh-CN/docs/Web/API/GainNode/webaudiogainnode.png)

EventTarget

AudioNode

GainNode

|  |  |
| --- | --- |
| 输入的数量 | `1` |
| 输出的数量 | `1` |
| 声道计数模式 | `"max"` |
| 声道数 | `2`（在默认计数模式下不生效） |
| 声道混频 | `"speakers"`（扬声器） |

构造函数
----

`GainNode()` (en-US)

创建并返回一个新的 `GainNode` 对象。作为代替的方法，你可以使用工厂方法 `AudioContext.createGain()` (en-US)，参见创建 AudioNode。

属性
--

*从其父类 `AudioNode` 继承属性。*

`GainNode.gain` 只读

是一个 a-rate `AudioParam`，表示应用的增益量。必须设置 `AudioParam.value` (en-US) 或者使用 `AudioParam` 的方法来改变增益效果。

方法
--

*无具体方法；所有方法继承自父类 `AudioNode`*。

示例
--

参见 `BaseAudioContext.createGain()` (en-US) 以获取示例代码，其展示了如何使用 `AudioContext` 来创建一个 `GainNode`。

规范
--

| Specification |
| --- |
| Web Audio API # GainNode |

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

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

参见
--

* 使用 Web Audio API


DOMPoint - Web API 接口参考

DOMPoint
========

DOMPoint 对象表示坐标系中的 2D 或 3D 点;它包括三维度的坐标值以及可选的透视值。DOMPoint 基于 DOMPointReadOnly，但允许更改其属性值。

通常，正 x 分量表示原点右侧的位置，正 y 分量从原点向下，正 z 分量从屏幕向外延伸 (换言之，朝向用户)。

Constructor
-----------

`DOMPoint()`

Creates and returns a new `DOMPoint` object given the values of zero or more of its coordinate components and optionally the `w` perspective value. You can also use an existing `DOMPoint` or `DOMPointReadOnly` or a `DOMPointInit` (en-US) dictionary to create a new point by calling the `DOMPoint.fromPoint()` (en-US) static method.

Methods
-------

*`DOMPoint` inherits methods from its parent, `DOMPointReadOnly` (en-US).*

`fromPoint()` (en-US)

Creates a new mutable `DOMPoint` object given an existing point or a `DOMPointInit` (en-US) dictionary which provides the values for its properties.

Properties
----------

*`DOMPoint` inherits properties from its parent, `DOMPointReadOnly` (en-US).*

`DOMPoint.x` (en-US)

The x coordinate of the `DOMPoint`.

`DOMPoint.y` (en-US)

The y coordinate of the `DOMPoint`.

`DOMPoint.z` (en-US)

The z coordinate of the `DOMPoint`.

`DOMPoint.w` (en-US)

The perspective value of the `DOMPoint`.

Examples
--------

In the WebVR API, `DOMPoint` values are used to represent points in the coordinate space that the user's head mounted display exists in. In the following snippet, the position of the VR HMD can be retrieved by first grabbing a reference to the position sensor's current state using `PositionSensorVRDevice.getState()` (en-US), then accessing the resulting `VRPositionState` (en-US)'s `position` (en-US) property, which returns a `DOMPoint`. Note below the usage of `position.x`, `position.y`, and `position.z`.

```js
function setView() {
  var posState = gPositionSensor.getState();

  if (posState.hasPosition) {
    posPara.textContent =
      "Position: x" +
      roundToTwo(posState.position.x) +
      " y" +
      roundToTwo(posState.position.y) +
      " z" +
      roundToTwo(posState.position.z);
    xPos = -posState.position.x \* WIDTH \* 2;
    yPos = posState.position.y \* HEIGHT \* 2;

    if (-posState.position.z > 0.01) {
      zPos = -posState.position.z;
    } else {
      zPos = 0.01;
    }
  }

  /\* ... \*/
}
```

**备注：** See our positionsensorvrdevice demo for the full code.

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

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # DOMPoint |

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

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

See also
--------

* `DOMRect`
* `DOMMatrix`


MediaSession - Web API 接口参考

MediaSession
============

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

Media Session API (en-US) 的 **`MediaSession`** 接口允许页面为标准媒体交互提供自定义行为。

属性
--

`MediaSession.metadata` (en-US)

指向一个 `MediaMetadata` (en-US) 的实例，其包含富媒体的元数据。该数据将用于平台显示。

`MediaSession.playbackState` (en-US)

展示当前 mediasession 是否处于播放状态。有效值为`"none"`, `"paused"`, `"playing"`.

方法
--

`MediaSession.setActionHandler()`

设置一个监听 mediasession 动作 (如 play 或者 pause) 的事件句柄。浏览方法页以获取所有动作的列表。

例子
--

下面的例子创建了一个新的 media session，并且给其绑定了一些动作句柄：

```js
if ("mediaSession" in navigator) {
  navigator.mediaSession.metadata = new MediaMetadata({
    title: "Podcast Episode Title",
    artist: "Podcast Host",
    album: "Podcast Name",
    artwork: [{ src: "podcast.jpg" }],
  });
  navigator.mediaSession.setActionHandler("play", function () {});
  navigator.mediaSession.setActionHandler("pause", function () {});
  navigator.mediaSession.setActionHandler("seekbackward", function () {});
  navigator.mediaSession.setActionHandler("seekforward", function () {});
  navigator.mediaSession.setActionHandler("previoustrack", function () {});
  navigator.mediaSession.setActionHandler("nexttrack", function () {});
}
```

下面例子为暂停和播放设置了事件句柄：

```js
var audio = document.querySelector("#player");
audio.src = "song.mp3";

navigator.mediaSession.setActionHandler("play", play);
navigator.mediaSession.setActionHandler("pause", pause);

function play() {
  audio.play();
  navigator.mediaSession.playbackState = "playing";
}

function pause() {
  audio.pause();
  navigator.mediaSession.playbackState = "Paused";
}
```

规范
--

| Specification |
| --- |
| Media Session # the-mediasession-interface |

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

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


服务器发送事件 - Web API 接口参考

服务器发送事件
=======

通常来说，一个网页获取新的数据通常需要发送一个请求到服务器，也就是向服务器请求的页面。使用服务器发送事件，服务器可以随时向我们的 Web 页面推送数据和信息。这些被推送进来的信息可以在这个页面上以 *事件 + 数据* 的形式来处理。

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

**备注：** Firefox 不能在 service worker 正常支持服务器发送事件（但支持在 Dedicated Worker 和 Shared Worker 中使用）。参见 Firefox bug 1681218。

概念与使用
-----

要了解如何使用服务器发送事件，请参阅我们的文章使用服务器发送事件。

接口
--

`EventSource`

定义了所有处理与服务器连接、接收事件/数据、处理错误、关闭连接等功能的特性。

示例
--

* 使用 PHP 语言的简单 SSE 示例
规范
--

| Specification |
| --- |
| HTML Standard # server-sent-events |

参见
--

### 工具

* Mercure：一个建立在 SSE 之上的实时通信（发布——订阅）协议
* 用于 Node.js 的 EventSource polyfill
* Remy Sharp 的 EventSource polyfill
* Yaffle 的 EventSource polyfill
* Rick Waldron 的 jquery 插件
* intercooler.js 声明性的 SSE 支持
### 相关主题

* 从服务器获取数据
* JavaScript
* WebSocket
### 其他资源

* 一个使用服务器发送事件的、类似 Twitter 的应用程序，代码存放在这里：Github。
* HTML5 和服务器发送事件


Vibration API - Web API 接口参考

Vibration API
=============

大多数现代移动设备包括振动硬件，其允许软件代码通过使设备摇动来向用户提供物理反馈。Vibration API 为 Web 应用程序提供访问此硬件（如果存在）的功能，如果设备不支持此功能，则不会执行任何操作。

振动描述
----

振动被抽象成【开 - 关】脉冲的模式，且可以具有变化的长度。?参数可以是单个整数，表示持续振动的毫秒数 (ms)；或可由多个整数组成的数组，达到振动和暂停循环的效果。只要单一 `window.navigator.vibrate()` (en-US) 函式即可控制振动。

### 一个单次振动

你可以通过指定单个值或仅由一个值组成的数组来一次振荡振动硬件：

```js
window.navigator.vibrate(200);
window.navigator.vibrate([200]);
```

以上两个例子都可以使设备振动 200 ms.

### 振动模式

一组数值描述了设备振动并且不振动的交替时间段。数组中的每个值都将转换成一个整数，然后交替解释为设备应该振动的毫秒数和不振动的毫秒数。例如：

```js
window.navigator.vibrate([200, 100, 200]);
```

这会使设备振动 200 ms，然后暂停 100 ms，然后再次振动设备 200 ms。

你可以根据需要设定多个振动/暂停对，数组的值可以是偶数或奇数个；值得注意的是，由于振动在每个振动周期结束时自动停止，因此你不必提供最后一个值去暂停，换句话说，数组长度只需要设置奇数个。

### 停止振动

当调用 `Navigator.vibrate()` 的参数为 `0`、空数组，或包含全 0 值的数组时会取消任何正在进行中的振动。

### 持续振动

一些基于 setInterval 和 clearInterval 操作将允许你创建持续的振动：

```js
var vibrateInterval;

// Starts vibration at passed in level
function startVibrate(duration) {
  navigator.vibrate(duration);
}

// Stops vibration
function stopVibrate() {
  // Clear interval and stop persistent vibrating
  if (vibrateInterval) clearInterval(vibrateInterval);
  navigator.vibrate(0);
}

// Start persistent vibration at given duration and interval
// Assumes a number value is given
function startPeristentVibrate(duration, interval) {
  vibrateInterval = setInterval(function () {
    startVibrate(duration);
  }, interval);
}
```

当然上面的代码片段没有考虑到振动参数为数组情况; 基于阵列的持久性振动将需要计算数组项的和，并基于该数量创建周期（可能具有额外的延迟）。

规范
--

| Specification |
| --- |
| Vibration API (Second Edition) # dom-navigator-vibrate |

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

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

参见
--

* `Navigator.vibrate()`


HTMLTextAreaElement - Web API 接口参考

HTMLTextAreaElement
===================

**`HTMLTextAreaElement`** 接口提供了特殊的属性和方法，用于控制 `<textarea>` 元素的布局和展示。

属性
--

| `form` 只读  | `object:` 返回一个父表单元素的引用。如果这个元素没有被包含在一个表单元素中，则这个值是页面中任意一个 `<form>` 元素的 `id` 属性或者 `null`。 |
| --- | --- |
| `type` 只读  | `string:` 返回字符串 `textarea`。 |
| `value` | `string:` Returns / Sets the raw value contained in the control. |
| `textLength` 只读  | `long:` Returns the codepoint length of the control's `value`. Same as `calling value.length` |
| `defaultValue` | `string:` Returns / Sets the control's default value, which behaves like the `Node.textContent` property. |
| `placeholder` | `string:` 返回/设置元素`placeholder` 属性，用于提示用户在组件中应该输入什么。 |
| `rows` | `unsigned long:` Returns / Sets the element's `rows` attribute, indicating the number of visible text lines for the control. |
| `cols` | `unsigned long:` Returns / Sets the element's `cols` attribute, indicating the visible width of the text area. |
| `autofocus` | `boolean:` Returns / Sets the element's `autofocus` attribute, indicating that the control should have input focus when the page loads |
| `name` | `string:` Returns / Sets the element's `name` attribute, containing the name of the control. |
| `disabled` | `boolean:` Returns / Sets the element's `disabled` attribute, indicating that the control is not available for interaction. |
| `HTMLTextAreaElement.labels` (en-US)只读  | `NodeList`: Returns a list of label elements associated with this select element. |
| `maxLength` | `long:` Returns / Sets the element's `maxlength` attribute, indicating the maximum number of characters the user can enter. This constraint is evaluated only when the value changes. |
| `minLength` | `long:` Returns / Sets the element's `minlength` attribute, indicating the minimum number of characters the user can enter. This constraint is evaluated only when the value changes. |
| `accessKey` | `string:` Returns / Sets the element's `accesskey` attribute. |
| `readOnly` | `boolean:` Returns / Sets the element's `readonly` attribute, indicating that the user cannot modify the value of the control. |
| `required` | `boolean:` Returns / Sets the element's `required` attribute, indicating that the user must specify a value before submitting the form. |
| `tabIndex` | `long:` Returns / Sets the position of the element in the tabbing navigation order for the current document. |
| `selectionStart` | `unsigned long:` Returns / Sets the index of the beginning of selected text. If no text is selected, contains the index of the character that follows the input cursor. On being set, the control behaves as if `setSelectionRange()` had been called with this as the first argument, and `selectionEnd` as the second argument. |
| `selectionEnd` | `unsigned long:` Returns / Sets the index of the end of selected text. If no text is selected, contains the index of the character that follows the input cursor. On being set, the control behaves as if `setSelectionRange()` had been called with this as the second argument, and `selectionStart` as the first argument. |
| `selectionDirection` | `string:` Returns / Sets the direction in which selection occurred. This is `"forward"` if selection was performed in the start-to-end direction of the current locale, or `"backward"` for the opposite direction. This can also be `"none"` if the direction is unknown." |
| `validity` 只读  | ``ValidityState` object:` Returns the validity states that this element is in. |
| `willValidate` 只读  | `boolean:` Returns whether the element is a candidate for constraint validation. `false` if any conditions bar it from constraint validation, including its `readOnly` or `disabled` property is `true`. |
| `validationMessage` 只读  | `string:` Returns a localized message that describes the validation constraints that the control does not satisfy (if any). This is the empty string if the control is not a candidate for constraint validation (`willValidate` is `false`), or it satisfies its constraints. |
| `autocomplete`
实验性
 |  |
| `autocapitalize`
实验性
 | `string:` Returns / Sets the element's capitalization behavior for user input. Valid values are: `none`, `off`, `characters`, `words`, `sentences`. |
| `inputMode`
实验性
 |  |
| `wrap` | `string:` Returns / Sets the `wrap` HTML attribute, indicating how the control wraps text. |

The two properties `tabIndex` and `accessKey` are inherited from `HTMLElement` from HTML5 on, but were defined on `HTMLTextAreaElement` in DOM Level 2 HTML and earlier specifications.

方法
--

| `blur()` (en-US) | Removes focus from the control; keystrokes will subsequently go nowhere. |
| --- | --- |
| `focus()` (en-US) | Gives focus to the control; keystrokes will subsequently go to this element. |
| `select()` | Selects the contents of the control. |
| `setRangeText()` (en-US) | Replaces a range of text in the element with new text. |
| `setSelectionRange()` | Selects a range of text in the element (but does not focus it). |
| `checkValidity()` | Returns `false` if the button is a candidate for constraint validation, and it does not satisfy its constraints. In this case, it also fires a cancelable `invalid` event at the control. It returns `true` if the control is not a candidate for constraint validation, or if it satisfies its constraints. |
| `reportValidity()` | This method reports the problems with the constraints on the element, if any, to the user. If there are problems, it fires a cancelable `invalid` event at the element, and returns `false`; if there are no problems, it returns `true`. |
| `setCustomValidity(DOMstring)` | Sets a custom validity message for the element. If this message is not the empty string, then the element is suffering from a custom validity error, and does not validate. |

The two methods `blur()` and `focus()` are inherited from `HTMLElement` from HTML5 on, but were defined on `HTMLTextAreaElement` in DOM Level 2 HTML and earlier specifications.

事件
--

Listen to these events using `addEventListener()` or by assigning an event listener to the `oneventname` property of this interface:

`input` 事件

Fires when the `value` of an `<input>`, `<select>`, or `<textarea>` element has been changed.

示例
--

### Autogrowing textarea example

Make a textarea autogrow while typing:

JavaScript function:

```js
function autoGrow(oField) {
  if (oField.scrollHeight > oField.clientHeight) {
    oField.style.height = oField.scrollHeight + "px";
  }
}
```

CSS:

```css
textarea.noscrollbars {
  overflow: hidden;
  width: 300px;
  height: 100px;
}
```

HTML:

```html
<form>
  <fieldset>
    <legend>Your comments</legend>
    <p><textarea class="noscrollbars" onkeyup="autoGrow(this);"></textarea></p>
    <p><input type="submit" value="Send" /></p>
  </fieldset>
</form>
```

### Insert HTML tags example

 Insert some HTML tags or *smiles* or any custom text in a textarea.
 JavaScript function:

```js
function insertMetachars(sStartTag, sEndTag) {
  var bDouble = arguments.length > 1,
    oMsgInput = document.myForm.myTxtArea,
    nSelStart = oMsgInput.selectionStart,
    nSelEnd = oMsgInput.selectionEnd,
    sOldText = oMsgInput.value;
  oMsgInput.value =
    sOldText.substring(0, nSelStart) +
    (bDouble
      ? sStartTag + sOldText.substring(nSelStart, nSelEnd) + sEndTag
      : sStartTag) +
    sOldText.substring(nSelEnd);
  oMsgInput.setSelectionRange(
    bDouble || nSelStart === nSelEnd ? nSelStart + sStartTag.length : nSelStart,
    (bDouble ? nSelEnd : nSelStart) + sStartTag.length,
  );
  oMsgInput.focus();
}
```

CSS to decorate the internal span to behave like a link:

```css
.intLink {
  cursor: pointer;
  text-decoration: underline;
  color: #0000ff;
}
```

HTML:

```html
<form name="myForm">
  <p>
    [ <span
 class="intLink"
 onclick="insertMetachars('<strong>','<\/strong>');"
 ><strong>Bold</strong></span
 >
    |
    <span
 class="intLink"
 onclick="insertMetachars('<em>','<\/em>');"
 ><em>Italic</em></span
 >
    |
    <span
 class="intLink"
 onclick="var newURL=prompt('Enter the full URL for the link');if(newURL){insertMetachars('<a href=\u0022'+newURL+'\u0022>','<\/a>');}else{document.myForm.myTxtArea.focus();}"
 >URL</span
 >
    |
    <span
 class="intLink"
 onclick="insertMetachars('\n<code>\n','\n<\/code>\n');"
 >code</span
 >
    | <span class="intLink" onclick="insertMetachars(' :-)');">smile</span> |
    etc. etc. ]
  </p>
  <p>
    <textarea name="myTxtArea" rows="10" cols="50">
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut facilisis, arcu vitae adipiscing placerat, nisl lectus accumsan nisi, vitae iaculis sem neque vel lectus. Praesent tristique commodo lorem quis fringilla. Sed ac tellus eros. Sed consectetur eleifend felis vitae luctus. Praesent sagittis, est eget bibendum tincidunt, ligula diam tincidunt augue, a fermentum odio velit eget mi. Phasellus mattis, elit id fringilla semper, orci magna cursus ligula, non venenatis lacus augue sit amet dui. Pellentesque lacinia odio id nisi pulvinar commodo tempus at odio. Ut consectetur eros porttitor nunc mollis ultrices. Aenean porttitor, purus sollicitudin viverra auctor, neque erat blandit sapien, sit amet tincidunt massa mi ac nibh. Proin nibh sem, bibendum ut placerat nec, cursus et lacus. Phasellus vel augue turpis. Nunc eu mauris eu leo blandit mollis interdum eget lorem. </textarea
 >
  </p>
</form>
```

### Maximum length and number of lines example

Create a textarea with a maximum number of characters per line and a maximum number of lines:

First, create a function that takes the text field and a key event as input and determines if any of the limits have been reached. If the limit has not been reached, it will return the key.

```js
function checkRows(oField, oKeyEvent) {
  var nKey = (
      oKeyEvent ||
      /\* old IE \*/ window.event || /\* check is not supported! \*/ { keyCode: 38 }
    ).keyCode,
    // put here the maximum number of characters per line:
    nCols = 30,
    // put here the maximum number of lines:
    nRows = 5,
    nSelS = oField.selectionStart,
    nSelE = oField.selectionEnd,
    sVal = oField.value,
    nLen = sVal.length,
    nBackward = nSelS >= nCols ? nSelS - nCols : 0,
    nDeltaForw =
      sVal
        .substring(nBackward, nSelS)
        .search(new RegExp("\\n(?!.{0," + String(nCols - 2) + "}\\n)")) + 1,
    nRowStart = nBackward + nDeltaForw,
    aReturns = (
      sVal.substring(0, nSelS) + sVal.substring(nSelE, sVal.length)
    ).match(/\n/g),
    nRowEnd = nSelE + nRowStart + nCols - nSelS,
    sRow =
      sVal.substring(nRowStart, nSelS) +
      sVal.substring(nSelE, nRowEnd > nLen ? nLen : nRowEnd),
    bKeepCols =
      nKey === 13 ||
      nLen + 1 < nCols ||
      /\n/.test(sRow) ||
      ((nRowStart === 0 || nDeltaForw > 0 || nKey > 0) &&
        (sRow.length < nCols ||
          (nKey > 0 && (nLen === nRowEnd || sVal.charAt(nRowEnd) === "\n"))));

  return (
    (nKey !== 13 || (aReturns ? aReturns.length + 1 : 1) < nRows) &&
    ((nKey > 32 && nKey < 41) || bKeepCols)
  );
}
```

In the HTML we just need to hook our function to the `onkeypress` event and specify that our textarea does not accept pasting:

```html
<form>
  <p>
    Textarea with fixed number of characters per line:<br />
    <textarea
 cols="50"
 rows="10"
 onkeypress="return checkRows(this, event);"
 onpaste="return false;"></textarea>
  </p>
</form>
```

规范
--

| Specification |
| --- |
| HTML Standard # htmltextareaelement |

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

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


console - Web API 接口参考

console
=======

**`console`** 对象提供了浏览器控制台调试的接口（如：Firefox 的 Web console）。在不同浏览器上它的工作方式可能不一样，但通常都会提供一套共性的功能。

`console` 对象可以从任何全局对象中访问到，如 浏览器作用域上的 `Window`，以及通过属性控制台作为 worker 中的特定变体的 `WorkerGlobalScope` (en-US)。可以通过 `Window.console` 引用，也可以简单的通过 `console` 引用。例：

```js
console.log("Failed to open the specified link");
```

本页面记录了 `console` 对象上的方法并给出了几个 Usage （用例）。

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

方法
--

`console.assert()`

如果第一个参数为 `false` ，则将消息和堆栈跟踪记录到控制台。

`console.clear()`

清空控制台，并输出 `Console was cleared`。

`console.count()`

以参数为标识记录调用的次数，调用时在控制台打印标识以及调用次数。

`console.countReset()`

重置指定标签的计数器值。

`console.debug()`

在控制台打印一条 `"debug"` 级别的消息。

`console.dir()`

显示一个由特定的 Javascript 对象列表组成的可交互列表。这个列表可以使用三角形隐藏和显示来审查子对象的内容。

`console.dirxml()`

打印 XML/HTML 元素表示的指定对象，否则显示 JavaScript 对象视图。

`console.error()`

打印一条错误信息，使用方法可以参考使用字符串替换。

`console.exception()`
非标准

已弃用

`error()` 方法的别称。

`console.group()`

创建一个新的内联分组, 后续所有打印内容将会以子层级的形式展示。调用 `groupEnd()`来闭合组。

`console.groupCollapsed()`

创建一个新的内联分组。使用方法和 `group()` 相同，不同的是，`groupCollapsed()` 方法打印出来的内容默认是折叠的。调用`groupEnd()`来闭合组。

`console.groupEnd()`

闭合当前内联分组。

`console.info()`

打印资讯类说明信息，使用方法可以参考使用字符串替换。

`console.log()`

打印内容的通用方法，使用方法可以参考使用字符串替换。

`console.profile()`
非标准

Starts the browser's built-in profiler (for example, the Firefox performance tool). You can specify an optional name for the profile.

`console.profileEnd()`
非标准

Stops the profiler. You can see the resulting profile in the browser's performance tool (for example, the Firefox performance tool).

`console.table()`

将列表型的数据打印成表格。

`console.time()`

启动一个以入参作为特定名称的定时器，在显示页面中可同时运行的定时器上限为 10,000.

`console.timeEnd()`

结束特定的定时器并以毫秒打印其从开始到结束所用的时间。

`console.timeLog()`

打印特定定时器所运行的时间。

`console.timeStamp()`
非标准

添加一个标记到浏览器的 Timeline 或 Waterfall 工具。

`console.trace()`

输出堆栈跟踪。

`console.warn()`

打印一个警告信息，可以使用字符串替换和额外的参数。

示例
--

### 输出文本到控制台

console 对象中较多使用的主要有四个方法 `console.log()`、`console.info()`、`console.warn()` 和`console.error()`。每一个结果在日志中都有不同的样式，可以使用浏览器控制台的日志筛选功能筛选出感兴趣的日志信息。

有两种途径使用这些方法，可以简单的传入一组对象，其中的字符串对象会被连接到一起，输出到控制台。或者可以传入包含零个或多个的替换的字符串，后面跟着被替换的对象列表。

#### 打印单个对象

The simplest way to use the logging methods is to output a single object:

```js
var someObject = { str: "Some text", id: 5 };
console.log(someObject);
```

打印结果类似下面：
```

[09:27:13.475] ({str:"Some text", id:5})
```

#### 打印多个对象

可以打印多个对象，就像下面一样：

```js
var car = "Dodge Charger";
var someObject = { str: "Some text", id: 5 };
console.info("My first car was a", car, ". The object is:", someObject);
```

打印结果类似下面：
```

[09:28:22.711] My first car was a Dodge Charger . The object is: ({str:"Some text", id:5})
```

#### 使用字符串替换

可以在传递给 console 的方法的时候使用下面的字符以期进行参数的替换。

| Substitution string | Description |
| --- | --- |
| `%o` or `%O` | 打印 JavaScript 对象。在审阅器点击对象名字可展开更多对象的信息。 |
| `%d` or `%i` | 打印整数。支持数字格式化。例如，`console.log("Foo %.2d", 1.1)` 会输出有先导 0 的两位有效数字：`Foo 01`。 |
| `%s` | 打印字符串。 |
| `%f` | 打印浮点数。支持格式化，比如 `console.log("Foo %.2f", 1.1)` 会输出两位小数：`Foo 1.10` |

**备注：** Chrome 不支持精确格式化。

当要替换的参数类型和预期的打印类型不同时，参数会被转换成预期的打印类型。
```

for (var i=0; i<5; i++) {
  console.log("Hello, %s. You've called me %d times.", "Bob", i+1);
}
```

输出样例如下所示：
```

[13:14:13.481] Hello, Bob. You've called me 1 times.
[13:14:13.483] Hello, Bob. You've called me 2 times.
[13:14:13.485] Hello, Bob. You've called me 3 times.
[13:14:13.487] Hello, Bob. You've called me 4 times.
[13:14:13.488] Hello, Bob. You've called me 5 times.
```

#### 为控制台定义样式

可以使用 `%c` 为打印内容定义样式：

```js
console.log(
  "This is %cMy stylish message",
  "color: yellow; font-style: italic; background-color: blue;padding: 2px",
);
```

指令前的文本不会受到影响，但指令后的文本将会使用参数中声明的 CSS 样式。
 ![](/zh-CN/docs/Web/API/console/css-styling.png)

`%c` 语法可用的属性如下 (至少在 Firefox 中是这样，别的浏览器会有诸多不同）：

* `background` 与其全写版本。
* `border` 与其全写版本。
* `border-radius`
* `box-decoration-break`
* `box-shadow`
* `clear` 和 `float`
* `color`
* `cursor`
* `display`
* `font` 与其全写版本。
* `line-height`
* `margin`
* `outline` 与其全写版本。
* `padding`
* `text-transform` 这类 `text-*` 属性
* `white-space`
* `word-spacing` 和 `word-break`
* `writing-mode`

**注意**：控制台信息的默认行为与行内元素相似。为了应用 `padding`、`margin` 这类效果，你应当这样设置`display: inline-block`。

### 在 console 中使用编组

可以使用嵌套组来把视觉上相关的元素合并，以协助组织你的输出。使用`console.group()`创建新的嵌套块，或者用`console.groupCollapsed()` 创建默认折叠的块，这种块需要点击闭合按钮来展开才能读到。

直接调用 `console.groupEnd()`.就可以退出当前组。比如下面的代码：

```js
console.log("This is the outer level");
console.group();
console.log("Level 2");
console.group();
console.log("Level 3");
console.warn("More of level 3");
console.groupEnd();
console.log("Back to level 2");
console.groupEnd();
console.debug("Back to the outer level");
```

执行结果：

![Demo of nested groups in Firefox console](/zh-CN/docs/Web/API/console/console_groups_demo.png)

### 定时器

你可以使用定时器来计算一段特定操作的周期。使用 `console.time()` 方法以创建一个计时器，其唯一的参数表示了计时器的名字。使用 `console.timeEnd()` 方法以关闭计时器，并获取经过的毫秒数，其同样以计时器的名字作为参数。一个页面最多同时只能有 10,000 个计数器运行。

示例：:

```js
console.time("answer time");
alert("Click to continue");
console.timeLog("answer time");
alert("Do a bunch of other stuff...");
console.timeEnd("answer time");
```

这段代码将会打印需要用户关闭 alert box 的时间，打印时间到控制台上，等用户关闭第二个 alert 后，把结束时间打印到控制台。

![timerresult.png](/zh-CN/docs/Web/API/console/console-timelog.png)

注意无论在开始还是结束的时候都会打印计时器的名字。

**备注：** 如果使用计时器来记录网络时间请求的话下面的内容很重要。计时器将会报告传输过程的整个时间，而网络面板里显示的时间只计算了请求头部所需要的时间。如果启用了响应体日志记录，那么列出的响应头部和响应体组合的时间应该与在控制台输出中看到的时间相符。

### 堆栈跟踪

控制台也支持输出堆栈，其将会显示到调用 `console.trace_static` 的点的调用路径。如下所示：

```js
function foo() {
  function bar() {
    console.trace();
  }
  bar();
}

foo();
```

控制台的输出：

![](/zh-CN/docs/Web/API/console/api-trace2.png)

规范
--

| Specification |
| --- |
| Console Standard # console-namespace |

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

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

注意
--

* 在 Firefox 浏览器中，如果页面中自己定义了 `console` 对象，那么它会覆盖掉浏览器内置的 `console`对象，在其他浏览器可能也是。
相关文档
----

* Tools
* Web Console - Firefox 浏览器控制台如何处理 console API 的调用
* Remote debugging - 如何在调试移动设备时查看控制台输出。
### 其他实现

* Google Chrome DevTools
* Microsoft Edge DevTools
* Safari Web Inspector


MIDIAccess - Web API 接口参考

MIDIAccess
==========

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

Web MIDI API (en-US) 的 **`MIDIAccess`** 接口提供查询 MIDI 输入和输出设备的列表以及获取这些设备的使用权限。

属性
--

`MIDIAccess.inputs` (en-US) 只读

返回 `MIDIInputMap` (en-US) 的实例，以提供对任何可用的 MIDI 输入端口的访问权限。

`MIDIAccess.outputs` (en-US) 只读

返回 `MIDIOutputMap` (en-US) 的实例，以提供任何可用的 MIDI 输出端口的访问权限。

`MIDIAccess.sysexEnabled` (en-US) 只读

一个布尔型的属性，指明系统是否对现有的 MIDIAccess 实例支持。

### 事件处理程序

`MIDIAccess.onstatechange` (en-US)

当添加新的 MIDI 端口或者一个存在的端口状态发生改变时被调用。

例子
--

规范
--

| Specification |
| --- |
| Web MIDI API # midiaccess-interface |

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

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


HTMLStyleElement - Web API 接口参考

HTMLStyleElement
================

**`HTMLStyleElement`** 接口表示 `<style>` 元素。它从 `HTMLElement` 和 `LinkStyle` (en-US) 中继承属性和方法。

这个接口不允许修改包含其中的 CSS（大多数情况下）。如果需要修改 CSS，前往关于使用动态样式的信息查看在 DOM 中用于修改特定 CSS 属性的对象。

属性
--

*Inherits properties from its parent, `HTMLElement`**, and implements `LinkStyle` (en-US)**.*

`HTMLStyleElement.media` (en-US)

Is a `DOMString` representing the intended destination medium for style information.

`HTMLStyleElement.type` (en-US)

Is a `DOMString` representing the type of style being applied by this statement.

`HTMLStyleElement.disabled` (en-US)

Is a `Boolean` (en-US) value representing whether or not the stylesheet is disabled (true) or not (false).

`LinkStyle.sheet` (en-US) 只读

Returns the `StyleSheet` object associated with the given element, or `null` if there is none

`HTMLStyleElement.scoped` (en-US)
非标准

已弃用

Is a `Boolean` (en-US) value indicating if the element applies to the whole document (`false`) or only to the parent's sub-tree (`true`).

方法
--

*No specific method; inherits properties from its parent, `HTMLElement`**, and `LinkStyle` (en-US)**.*

规范
--

| Specification |
| --- |
| HTML Standard # htmlstyleelement |

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

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

参见
--

* The HTML element implementing this interface: `<style>`.
* Using dynamic styling information (en-US) to see how to manipulate CSS.


MediaRecorder - Web API 接口参考

MediaRecorder
=============

**`MediaRecorder`** 是 MediaStream Recording API 提供的用来进行媒体轻松录制的接口，他需要通过调用 `MediaRecorder()` 构造方法进行实例化。

构造函数
----

`MediaRecorder.MediaRecorder()`

创建一个新的`MediaRecorder`对象，对指定的`MediaStream` 对象进行录制，支持的配置项包括设置容器的 MIME 类型 (例如`"video/webm"` 或者 `"video/mp4"`) 和音频及视频的码率或者二者同用一个码率

配置项
---

`MediaRecorder.mimeType` (en-US) 只读

返回 `MediaRecorder` 对象创建时选择器选择的录制容器的 MIME type

`MediaRecorder.state` (en-US) 只读

返回录制对象`MediaRecorder` 的当前状态 (闲置中，录制中或者暂停 ) (`inactive`, `recording`, or `paused`.)

`MediaRecorder.stream` (en-US) 只读

返回录制器对象 `MediaRecorder` 创建时构造函数传入的 stream 对象

`MediaRecorder.ignoreMutedMedia`

用以指定 `MediaRecorder`是否录制无声的输入源。如果这个属性是 false. 录制器对象`MediaRecorder` 会录制无声的音频或者黑屏的视频，默认值是 false

`MediaRecorder.videoBitsPerSecond` (en-US) 只读

返回视频采用的编码比率。它可能和构造函数的设置比率不同。(if it was provided).

`MediaRecorder.audioBitsPerSecond` 只读

返回音频采用的编码比率，它可能和构造函数中设置的比率不同。(if it was provided).

方法
--

`MediaRecorder.isTypeSupported()` (en-US)

返回一个`Boolean` (en-US) 值，来表示设置的 MIME type 是否被当前用户的设备支持。

`MediaRecorder.pause()` (en-US)

暂停媒体录制

`MediaRecorder.requestData()` (en-US)

请求一个从开始到当前接收到的，存储为`Blob`类型的录制内容。(或者是返回从上一次调用`requestData()` 方法之后到现在的内容). 调用这个方法后，录制将会继续进行，但是会创建一个新的`Blob`对象

`MediaRecorder.resume()` (en-US)

继续录制之前被暂停的录制动作。

`MediaRecorder.start()` (en-US)

开始录制媒体，这个方法调用时可以通过给`timeslice`参数设置一个毫秒值，如果设置这个毫秒值，那么录制的媒体会按照你设置的值进行分割成一个个单独的区块，而不是以默认的方式录制一个非常大的整块内容。

`MediaRecorder.stop()` (en-US)

停止录制。同时触发 `dataavailable` 事件，返回一个存储`Blob`内容的录制数据。之后不再记录

静态方法
----

`MediaRecorder.isTypeSupported()`

静态方法，判断给定的 MIME 类型是否支持。返回`Boolean` (en-US)类型的值。

事件处理
----

`MediaRecorder.ondataavailable`

调用它用来处理 `dataavailable` 事件，该事件可用于获取录制的媒体资源 (在事件的 `data` 属性中会提供一个可用的 `Blob` 对象.)

`MediaRecorder.onerror` (en-US)

An event handler called to handle the `recordingerror` event, including reporting errors that arise with media recording. These are fatal errors that stop recording.

`MediaRecorder.onpause` (en-US)

用来处理 `pause` 事件，该事件在媒体暂停录制时触发（`MediaRecorder.pause()` (en-US)）.

`MediaRecorder.onresume` (en-US)

用来处理 `resume` 事件，该事件在暂停后回复录制视频时触发（`MediaRecorder.resume()` (en-US)）.

`MediaRecorder.onstart` (en-US)

用来处理 `start` 事件，该事件在媒体开始录制时触发（`MediaRecorder.start()` (en-US)）.

`MediaRecorder.onstop` (en-US)

用来处理 `stop` 事件，该事件会在媒体录制结束时、媒体流（`MediaStream`）结束时、或者调用 `MediaRecorder.stop()` (en-US) 方法后触发。

事件
--

Listen to these events using `addEventListener()` or by assigning an event listener to the `oneventname` property of this interface.

`error` (en-US)

 Fired when an error occurs: for example because recording wasn't allowed or was attempted using an unsupported codec.
 Also available via the `onerror` (en-US) property.

例子
--
```

if (navigator.mediaDevices) {
  console.log('getUserMedia supported.');

  var constraints = { audio: true };
  var chunks = [];

  navigator.mediaDevices.getUserMedia(constraints)
  .then(function(stream) {

    var mediaRecorder = new MediaRecorder(stream);

    visualize(stream);

    record.onclick = function() {
      mediaRecorder.start();
      console.log(mediaRecorder.state);
      console.log("recorder started");
      record.style.background = "red";
      record.style.color = "black";
    }

    stop.onclick = function() {
      mediaRecorder.stop();
      console.log(mediaRecorder.state);
      console.log("recorder stopped");
      record.style.background = "";
      record.style.color = "";
    }

    mediaRecorder.onstop = function(e) {
      console.log("data available after MediaRecorder.stop() called.");

      var clipName = prompt('Enter a name for your sound clip');

      var clipContainer = document.createElement('article');
      var clipLabel = document.createElement('p');
      var audio = document.createElement('audio');
      var deleteButton = document.createElement('button');

      clipContainer.classList.add('clip');
      audio.setAttribute('controls', '');
      deleteButton.innerHTML = "Delete";
      clipLabel.innerHTML = clipName;

      clipContainer.appendChild(audio);
      clipContainer.appendChild(clipLabel);
      clipContainer.appendChild(deleteButton);
      soundClips.appendChild(clipContainer);

      audio.controls = true;
      var blob = new Blob(chunks, { 'type' : 'audio/ogg; codecs=opus' });
      chunks = [];
      var audioURL = URL.createObjectURL(blob);
      audio.src = audioURL;
      console.log("recorder stopped");

      deleteButton.onclick = function(e) {
        evtTgt = e.target;
        evtTgt.parentNode.parentNode.removeChild(evtTgt.parentNode);
      }
    }

    mediaRecorder.ondataavailable = function(e) {
      chunks.push(e.data);
    }
  })
  .catch(function(err) {
    console.log('The following error occured: ' + err);
  })
}
```

**备注：** This code sample is inspired by the Web Dictaphone demo. Some lines have been omitted for brevity; refer to the source for the complete code.

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

| Specification |
| --- |
| MediaStream Recording # mediarecorder-api |

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

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

See also
--------

* Using the MediaRecorder API (en-US)
* Web Dictaphone: MediaRecorder + getUserMedia + Web Audio API visualization demo, by Chris Mills (source on Github.)
* Recording a media element (en-US)
* simpl.info MediaStream Recording demo, by Sam Dutton.
* `navigator.mediaDevices.getUserMedia` (en-US)
* FingerSpell: Sign Language Fingerspelling practice using MediaDevices and the MediaStream Recording API to create and download recordings, MediaRecorder API supported desktop browsers only (source on GitHub)


CSSValueList - Web API 接口参考

CSSValueList
============

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

The **`CSSValueList`** 接口继承自 `CSSValue` 接口，提供一个经过排序的 CSS 值的抽象集合。

一些属性允许在它们的语法中使用空的列表。这时，these properties take the `none` identifier. So, an empty list means that the property has the value `none`.

The items in the `CSSValueList` are accessible via an integral index, starting from 0.

属性
--

*从它的父接口 `CSSValue` 继承属性。*

`CSSValueList.length` 只读

一个 `unsigned long` 数值，表示此列表中 `CSSValues` 的个数。

方法
--

`CSSValueList.item()` (en-US)

This method is used to retrieve a `CSSValue` by ordinal index. The order in this collection represents the order of the values in the CSS style property. If index is greater than or equal to the number of values in the list, this returns `null`.

规范
--

该特性最初在 DOM Style Level 2 中定义，但从那时起已从标准化工作中移除。

它已被现代、不兼容的 CSS 类型对象模型 API (en-US) 取代，该 API 已被标准化。

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

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

参见
--

* `CSSPrimitiveValue` (en-US)
* `CSSValue`


AnalyserNode - Web API 接口参考

AnalyserNode
============

**`AnalyserNode`** 接口表示了一个可以提供实时频域和时域分析信息的节点。它是一个不对音频流作任何改动的 `AudioNode`，同时允许你获取和处理它生成的数据，从而创建音频可视化。

`AnalyzerNode` 只有一个输入和输出，即使未连接到输出它也能正常工作。

![Without modifying the audio stream, the node allows to get the frequency and time-domain data associated to it, using a FFT.](/zh-CN/docs/Web/API/AnalyserNode/webaudiofft.png)

|  |  |
| --- | --- |
| 输入数 | `1` |
| 输出数 | `1` (但可能是未连接的) |
| 通道计数模式 | `"explicit"` |
| 通道数 | `1` |
| 通道解释 | `"speakers"` |

继承
--

继承自以下父接口：

EventTarget

AudioNode

AnalyserNode构造函数
----

`AnalyserNode()`

创建一个新的 `AnalyserNode` 对象实例。

属性
--

*继承属性自* *`AudioNode`。*

`AnalyserNode.fftSize`

一个无符号长整形 (unsigned long) 的值，代表了用于计算频域信号时使用的 FFT (快速傅里叶变换) 的窗口大小。

`AnalyserNode.frequencyBinCount` 只读

一个无符号长整形 (unsigned long) 的值，值为 fftSize 的一半。这通常等于将要用于可视化的数据值的数量。

`AnalyserNode.minDecibels` (en-US)

是一个双精度值，表示 FFT 分析频域数据并转换为无符号字节值时，对输入的功率数据的最小阈值 - 基本上，它限定了调用`getByteFrequencyData()`时结果范围的最小值

`AnalyserNode.maxDecibels` (en-US)

是一个双精度值，表示 FFT 分析频域数据并转换为无符号字节值时，对输入的功率数据的最大阈值 - 基本上，它限定了调用`getByteFrequencyData()`时结果范围的最大值

`AnalyserNode.smoothingTimeConstant`

是一个双精度浮点型 (double) 的值，表示最后一个分析帧的平均常数 — 基本上，它随时间使值之间的过渡更平滑。

方法
--

*继承方法自* *`AudioNode`*.

`AnalyserNode.getFloatFrequencyData()`

将当前频域数据拷贝进`Float32Array` (en-US)数组。

`AnalyserNode.getByteFrequencyData()`

将当前频域数据拷贝进`Uint8Array` (en-US)数组（无符号字节数组）。

`AnalyserNode.getFloatTimeDomainData()` (en-US)

将当前波形，或者时域数据拷贝进`Float32Array` (en-US)数组。

`AnalyserNode.getByteTimeDomainData()`

将当前波形，或者时域数据拷贝进 `Uint8Array` (en-US)数组（无符号字节数组）。

例子
--

**备注：** 查看 Visualizations with Web Audio API 指南以获得更多关于创建音频可视化效果的信息。

### 基础用法

下面的例子展示了 `AudioContext` 创建一个 `AnalyserNode`, 然后用 `requestAnimationFrame` 和 `<canvas>` 去反复收集当前音频的时域数据，并绘制为一个示波器风格的输出 (频谱).

更多的例子/信息，查看 Voice-change-O-matic 演示 (相关代码在 app.js 的 128 行~205 行).

```js
var audioCtx = new (window.AudioContext || window.webkitAudioContext)();
var analyser = audioCtx.createAnalyser();

// ...

analyser.fftSize = 2048;
var bufferLength = analyser.frequencyBinCount;
var dataArray = new Uint8Array(bufferLength);
analyser.getByteTimeDomainData(dataArray);

// 获取 ID 为 "oscilloscope" 的画布
var canvas = document.getElementById("oscilloscope");
var canvasCtx = canvas.getContext("2d");

// 绘制一个当前音频源的示波器

function draw() {
  drawVisual = requestAnimationFrame(draw);

  analyser.getByteTimeDomainData(dataArray);

  canvasCtx.fillStyle = "rgb(200, 200, 200)";
  canvasCtx.fillRect(0, 0, canvas.width, canvas.height);

  canvasCtx.lineWidth = 2;
  canvasCtx.strokeStyle = "rgb(0, 0, 0)";

  canvasCtx.beginPath();

  var sliceWidth = (canvas.width \* 1.0) / bufferLength;
  var x = 0;

  for (var i = 0; i < bufferLength; i++) {
    var v = dataArray[i] / 128.0;
    var y = (v \* canvas.height) / 2;

    if (i === 0) {
      canvasCtx.moveTo(x, y);
    } else {
      canvasCtx.lineTo(x, y);
    }

    x += sliceWidth;
  }

  canvasCtx.lineTo(canvas.width, canvas.height / 2);
  canvasCtx.stroke();
}

draw();
```

规范
--

| Specification |
| --- |
| Web Audio API # AnalyserNode |

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

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

相关内容
----

* Web Audio API 的运用 (en-US)


支付请求接口 - Web API 接口参考

支付请求接口
======

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

支付请求 API 为商家和支付者提供了统一的用户体验。它并非提供一种新的支付方式，而是让用户可以在原有的支付方式中进行选择，并使商家可以获悉用户的支付情况。

支付请求的概念和使用
----------

在网上购物时，使许多用户中止购物车结算的原因都可以被归结为填写支付信息表单时的步骤繁多导致的费时费力。**支付请求 API**正是被用以减少支付步骤，逐步彻底消除表单的填写。它的目的是简化结算流程，而实现此目的的方式是通过保存用户相关信息并传送给商家。在理想的情况下，用户将不需要填写 HTML 表单。

使用支付请求 API 中“保存卡信息并自动扣款”（使用银行卡支付时）的优点：

* **快捷的购买体验**：用户在浏览器上只需输入一次银行卡信息，之后便可一键对网络上提供的商品和服务进行支付。即使在不同的站点购物，他们也不需要反复填写相同的支付信息。
* **跨站点的统一用户体验（仅指支持此 API 的站点）**：浏览器统一控制支付页面，使定制化内容得以实现。可以定制的内容包括语言的本地化。
* **无障碍体验**：支付页面中的表单元素由浏览器控制，使得键盘输入和屏幕朗读在跨站点时也能以统一的方式工作，且不需要开发者的额外开发。浏览器也可以对支付页面中的字体大小、颜色对比度进行同一调节，使用户在支付过程中获得更加舒适的体验。
* **认证管理**：用户可以直接通过浏览器管理自己的信用卡和收件地址，且浏览器可以在不同设备间同步这些“认证信息”。这样，用户就能在购物时灵活地在电脑和移动设备间来回切换。
* **统一的异常信息处理**：浏览器可以检查信用卡卡号的有效性，并在卡片已经（或即将）过期时告知用户。浏览器可以通过用户过去的使用习惯和商家的支付规则（例如，“我们只支持 Visa 或 Mastercard”）自动对此次交易使用卡片的选择提出建议。用户还可以自行设置默认/最偏好的卡片。

当用户在页面上进行操作发起一次支付，比如点击“购买”按钮时，网页会相应地创建一个`PaymentRequest` (en-US)对象。`PaymentRequest`对象允许网页与用户代理交互，传送用户输入的用以交易的信息。

你可以在Using the Payment Request API (en-US)中查看完整指南。

**备注：** 此 API 只有在设置了`allowpaymentrequest`属性时才支持`<iframe>`元素的跨域使用。

接口
--

`PaymentAddress` (en-US)

一个包含地址信息的对象；例如，可以包含账单地址和收货地址。

`PaymentRequest` (en-US)

一个提供了创建和管理 user agent's支付接口的对象。

`PaymentRequestEvent` (en-US)

当`PaymentRequest` (en-US)发生时，被传送给支付回调函数的事件。

`PaymentRequestUpdateEvent` (en-US)

当用户进行操作时，使网页可以更新相应的支付信息的事件。

`PaymentMethodChangeEvent` (en-US)

代表支付凭证改变（例如，用户将支付方式从信用卡改为了借记卡）的事件。

`PaymentResponse` (en-US)

一个对象，当用户选择了一种支付方式并同意发起交易请求后被返回。

`MerchantValidationEvent` (en-US)

代表浏览器要求商家（网站）证实自身被允许使用某种特定的支付回调函数（例如，注册了对 Apply Pay 支付方式的使用）的事件。

词典
--

`AddressErrors`

一个由字符串组成的词典，包含用以描述任何`PaymentAddress` (en-US)条目中可能出现的报错的相应描述。

`PayerErrors`

一个由字符串组成的词典，包含了`PaymentResponse` (en-US)中出现的有关邮件地址、电话号码及姓名的报错的相应描述。

`PaymentDetailsUpdate` (en-US)

一个对象，用于描述当服务器在发起支付请求后且在用户与之交互前，需要更新支付信息的事件。

### “保存卡信息并自动扣款”规范的相关词典

`BasicCardChangeDetails`

一个对象，提供了当用户更改支付信息时，`methodDetails` (en-US) 中传送通过 `paymentmethodchange` (en-US) 事件传送给 `PaymentRequest` (en-US) 的*删节的*地址信息。

`BasicCardErrors`

一个对象，提供了`BasicCardResponse`中无效信息的相关错误提示。错误发生时，该对象被传送给`PaymentRequest` (en-US)，作为`PaymentValidationErrors` (en-US)对象中`paymentMethod`属性的值。

`BasicCardRequest`

定义了支付请求信息（例如“卡类型”）对象的结构。

`BasicCardResponse`

定义了支付请求响应（例如被使用的银行卡的“卡号”、“有效期”和“账单地址”）对象的结构。

规范
--

| Specification |
| --- |
| Payment Request API 1.1 # paymentrequest-interface |

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

### 支付请求接口

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

相关文档
----

* Using the Payment Request API (en-US)
* Payment processing concepts
* Introducing the Payment Request API for Apple Pay
* Google Pay API PaymentRequest Tutorial
* W3C Payment Request API FAQ


Battery Status API - Web API 接口参考

Battery Status API
==================

**Battery Status API**，更多时候被称之为 **Battery API**, 提供了有关系统充电级别的信息并提供了通过电池等级或者充电状态的改变提醒用户的事件。这个可以在设备电量低的时候调整应用的资源使用状态，或者在电池用尽前保存应用中的修改以防数据丢失。

Battery Status API 向 `window.navigator` 扩展了一个 `navigator.getBattery` 方法，其返回了一个 battery promise, 完成后传递一个 `BatteryManager` 对象，并提供了一些新的可以操作电池状态的事件。

示例
--

在这个例子中，我们同时监听放电状态和电池等级和剩余事件的事件（不论是否正在充电还是在使用电池）。这可以通过监听 `chargingchange` (en-US)、`levelchange` (en-US)、`chargingtimechange` (en-US)、`dischargingtimechange` (en-US) 事件完成。

```js
navigator.getBattery().then((battery) => {
  function updateAllBatteryInfo() {
    updateChargeInfo();
    updateLevelInfo();
    updateChargingInfo();
    updateDischargingInfo();
  }
  updateAllBatteryInfo();

  battery.addEventListener("chargingchange", () => {
    updateChargeInfo();
  });
  function updateChargeInfo() {
    console.log(`Battery charging? ${battery.charging ? "Yes" : "No"}`);
  }

  battery.addEventListener("levelchange", () => {
    updateLevelInfo();
  });
  function updateLevelInfo() {
    console.log(`Battery level: ${battery.level \* 100}%`);
  }

  battery.addEventListener("chargingtimechange", () => {
    updateChargingInfo();
  });
  function updateChargingInfo() {
    console.log(`Battery charging time: ${battery.chargingTime} seconds`);
  }

  battery.addEventListener("dischargingtimechange", () => {
    updateDischargingInfo();
  });
  function updateDischargingInfo() {
    console.log(`Battery discharging time: ${battery.dischargingTime} seconds`);
  }
});
```

另见 标准中的例子.

规范
--

| Specification |
| --- |
| Battery Status API  |

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

### api.BatteryManager

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

### api.Navigator.getBattery

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

另见
--

* Retrieving battery status information - demo & article
* Hacks blog post - Using the Battery API


CSSMediaRule - Web API 接口参考

CSSMediaRule
============

**`CSSMediaRule`** 是一个表示单个 CSS `@media` 规则的接口。它实现了 `CSSConditionRule` 接口，因此也是 `CSSGroupingRule`，也相当于`CSSRule`中类型值为 `4` 的规则类型（即`CSSRule.MEDIA_RULE`）。

语法
--

下列语法是使用 WebIDL 格式描述的。
```

interface CSSMediaRule : CSSConditionRule {
    readonly attribute MediaList media;
}
```

属性
--

作为一个 `CSSConditionRule`，同时也是 `CSSGroupingRule` 和 `CSSRule`，`CSSMediaRule` 也实现（继承）了来自这些接口的属性。它还有如下属性：

`CSSMediaRule.media` (en-US) 只读

声明了一个 `MediaList`，表示指定目标媒体中的样式信息。

方法
--

作为一个 `CSSConditionRule`，同时也是 `CSSGroupingRule` 和 `CSSRule`，`CSSMediaRule` 也实现（继承）了来自这些接口的方法。除此之外，没有其他方法。

规范
--

| Specification |
| --- |
| CSS Conditional Rules Module Level 3 # the-cssmediarule-interface |

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

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


GPUAdapterInfo - Web API 接口参考

GPUAdapterInfo
==============

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

WebGPU API 的 **`GPUAdapterInfo`** 接口包含关于 `GPUAdapter` 的标识信息。

使用 `GPUAdapter.requestAdapterInfo()` (en-US) 方法去请求 `GPUAdapterInfo` 对象。

实例属性
----

`architecture` (en-US)
实验性
 只读

适配器所属的 GPU 家族或类别的名称。如果不能获得，则返回空字符串。

`description` (en-US)
实验性
 只读

描述适配器的人类可读字符串。如果不能获得，则返回空字符串。

`device` (en-US)
实验性
 只读

适配器供应商的标识符。如果不能获得，则返回空字符串。

`vendor` (en-US)
实验性
 只读

适配器供应商的名称。如果不能获得，则返回空字符串。

示例
--

```js
async function init() {
  if (!navigator.gpu) {
    throw Error("WebGPU not supported.");
  }

  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) {
    throw Error("Couldn't request WebGPU adapter.");
  }

  const adapterInfo = await adapter.requestAdapterInfo();
  console.log(adapterInfo.architecture);
  console.log(adapterInfo.vendor);

  // ...
}
```

规范
--

| Specification |
| --- |
| WebGPU # gpu-adapterinfo |

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

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

参见
--

* WebGPU API


ResizeObserverEntry - Web API 接口参考

ResizeObserverEntry
===================

**`ResizeObserverEntry`** 接口是传递给 `ResizeObserver()` 构造函数中的回调函数参数的对象，它允许你获取真正在观察的 `Element` 或 `SVGElement` 最新的大小。

属性
--

`ResizeObserverEntry.borderBoxSize` 只读

一个对象，当运行回调时，该对象包含着正在观察元素的新边框盒的大小。

`ResizeObserverEntry.contentBoxSize` 只读

一个对象，当运行回调时，该对象包含着正在观察元素的新内容盒的大小。

`ResizeObserverEntry.devicePixelContentBoxSize` 只读

一个对象，当运行回调时，该对象包含着正在观察元素的新内容盒的大小（以设备像素为单位）。

`ResizeObserverEntry.contentRect` 只读

一个对象，当运行回调时，该对象包含着正在观察元素新大小的 `DOMRectReadOnly` 对象。请注意，这比以上两个属性有着更好的支持，但是它是 Resize Observer API 早期实现遗留下来的，出于对浏览器的兼容性原因，仍然被保留在规范中，并且在未来的版本中可能被弃用。

`ResizeObserverEntry.target` 只读

对正在观察 `Element` 或 `SVGElement` 的引用。

**备注：** 内容盒是放置内容的盒子，即边框盒减去内边距和边框宽度。边框盒包含内容、内边距和边框。更多解释参见盒模型。

方法
--

无。

示例
--

以下片段取自 resize-observer-text.html（参见源代码）示例。这使用了一个简单的特征检查去查看是否浏览器支持较新的 `contentBoxSize` 属性——如果支持，它将使用它获取需要的尺寸数据。如果不支持，它将使用一个较旧的 `contentRect` 属性。

```js
const resizeObserver = new ResizeObserver((entries) => {
  for (let entry of entries) {
    if (entry.contentBoxSize) {
      h1Elem.style.fontSize = `${Math.max(
 1.5,
 entry.contentBoxSize.inlineSize / 200,
 )}rem`;
      pElem.style.fontSize = `${Math.max(
 1,
 entry.contentBoxSize.inlineSize / 600,
 )}rem`;
    } else {
      h1Elem.style.fontSize = `${Math.max(
 1.5,
 entry.contentRect.width / 200,
 )}rem`;
      pElem.style.fontSize = `${Math.max(1, entry.contentRect.width / 600)}rem`;
    }
  }
});
resizeObserver.observe(divElem);
```

规范
--

| Specification |
| --- |
| Resize Observer # resize-observer-entry-interface |

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

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


Local Font Access API - Web API 接口参考

Local Font Access API
=====================

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

**Local Font Access API** 提供了一种访问用户本地安装的字体数据的机制——这包括更高层次的详细信息，例如名称、样式和系列，以及底层字体文件的原始字节内容。

概念和用法
-----

Web 字体允许 Web 设计人员提供在 Web 文档上使用的自定义字体，因而在实现 Web 排版方面具有革命性意义。通过 `@font-face` at 规则，Web 字体可以通过 `url()` 函数中提供的 URL 加载。

`@font-face` 还有其他几个有用的特性。特别是，你还可以在 `local()` 函数中指定字体的完整名称或 Postscript 名称，以告诉浏览器在用户计算机上安装了该字体时使用本地副本。这并非没有问题——`local()` 作为指纹向量已经变得臭名昭著。

此外，由于准确的字体枚举和访问底层字体数据（例如，应用过滤器和转换）方面的挑战，高端设计工具历来难以在 Web 上提供。当前的应用程序通常依赖于变通办法，例如要求用户将字体上传到服务器，在服务器上处理字体以获取原始字节数据，或者安装单独的本地程序以提供附加功能。

Local Font Access API 的创建就是为了解决这些问题。

`Window.queryLocalFonts()` 方法提供对本地安装的字体的数组的访问，每个字体都由一个 `FontData` 对象实例表示。`FontData` 有多个属性，提供对名称、样式和字体族的访问，并且它还有一个 `blob()` 方法，提供对包含底层字体文件的原始字节内容的 `Blob` 的访问。

在隐私和安全方面：

* 本地字体访问 API 旨在仅提供对解决上述问题所需的数据的访问。它既不要求浏览器提供可用本地字体的完整列表，也不要求按照磁盘上出现的顺序提供数据。
* 当调用 `Window.queryLocalFonts()` 时，系统会请求用户授予访问其本地字体的权限。此权限的状态可以通过 `Permissions API` (en-US)（`local-fonts` 权限）查询。
* 你可以使用 `local-fonts` (en-US) 权限策略控制对此特性的访问。
接口
--

`FontData`

代表单个本地字体。

其他接口的扩展
-------

`Window.queryLocalFonts()`

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

示例
--

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

### 特性检测

```js
if ("queryLocalFonts" in window) {
  // 支持本地字体访问 API
}
```

### 字体枚举

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

```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);
  }
}
```

### 访问底层数据

`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  |

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

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

参见
--

* 使用带有本地字体的高级排版
* `@font-face`
* `local-fonts` (en-US) 权限策略指令


MediaElementAudioSourceNode - Web API 接口参考

MediaElementAudioSourceNode
===========================

`MediaElementAudioSourceNode` 接口代表着某个由 HTML `<audio>` 或 `<video>` 元素所组成的音频源。该接口作为 `AudioNode` 音源节点。

`MediaElementSourceNode` 没有输入，且只有一个输出，其由 `AudioContext.createMediaElementSource` 方法创建。输出的频道数目与节点创建时引用音频 `HTMLMediaElement` 的频道数目一致，或当 `HTMLMediaElement` 无音频时，频道数目为 1。

EventTarget

AudioNode

MediaElementAudioSourceNode

|  |  |
| --- | --- |
| 输入数目 | `0` |
| 输出数目 | `1` |
| 通道数 | 2（但请注意 `AudioNode.channelCount` (en-US) 仅用于 `AudioNode` 输入的上混和下混，而 `MediaElementAudioSourceNode` 则没有任何输入） |

构造函数
----

`MediaElementAudioSourceNode.MediaElementAudioSourceNode()` (en-US)

创建一个新的 `MediaElementAudioSourceNode` 实例。

实例属性
----

*继承其父接口 `AudioNode` 的属性*。

实例方法
----

*继承其父接口 `AudioNode` 的方法*。

示例
--

参见 `AudioContext.createMediaElementSource()` 以获取示例代码。

规范
--

| Specification |
| --- |
| Web Audio API # MediaElementAudioSourceNode |

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

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

参见
--

* 使用 Web Audio API


WebRTC API - Web API 接口参考

WebRTC API
==========

**WebRTC**（Web Real-Time Communications）是一项实时通讯技术，它允许网络应用或者站点，在不借助中间媒介的情况下，建立浏览器之间点对点（Peer-to-Peer）的连接，实现视频流和（或）音频流或者其他任意数据的传输。WebRTC 包含的这些标准使用户在无需安装任何插件或者第三方的软件的情况下，创建点对点（Peer-to-Peer）的数据分享和电话会议成为可能。

WebRTC 包含了若干相互关联的 API 和协议以达到这个目标。你在这里看到的文档将会帮助你理解 WebRTC 的基本概念，还会教你如何去建立和使用可以传输媒体数据和其他任意数据的连接。当然你还会学到更多其他的东西。

参考
--

* `RTCPeerConnection`
* `RTCSessionDescription`
* `RTCIceCandidate` (en-US)
* `RTCPeerConnectionIceEvent` (en-US)
* `MessageEvent`
* `MediaStream`
* `RTCStatsReport`
* `RTCIdentityEvent`
* `RTCIdentityErrorEvent`
* `MediaStreamEvent`
* `MediaStreamTrack`
* `MediaDevices`
指南
--

WebRTC 架构概述 (en-US)

用来创建 WebRTC 连接的 API 底层使用了一系列的网络协议和连接标准。这篇文章涵盖了这些标准。

WebRTC 基础 (en-US)

这篇文章将带你贯穿一个跨浏览器 RTC 应用的整个创建过程。结束的时候，你将拥有一个可以运行的点对点（peer-to-peer）数据通道（data channel）和媒体通道（media channel）。

WebRTC 协议

这篇文章介绍了一系列的协议，WebRTC API 就是建立于他们之上。

WebRTC 连接

这篇文章将向你介绍为创建点对点的连接并且实现数据或/和媒体的传输，各个 WebRTC 相关的协议是如何相互协作的。

WebRTC API 概览 (en-US)

WebRTC 包含了一些关联的 API 和协议，它们相互协作以支持数据或媒体在两个或多个点之间传输。这篇文章将向你展示这些 API 的简要介绍以及它们的用途。

WebRTC 会话的生命周期

WebRTC 让你可以在基于浏览器应用中实现任意点对点（peer-to-peer）的数据、音频、视频 或它们的任意组合的通信。在这篇文章中我们一起来看一下 WebRTC 的生命周期。从建立连接开始，一直到不再需要的时候将它关闭掉。

教程
--

使用 WebRTC 拍摄静止的照片

这篇文章介绍了如何在 WebRTC 的支持下可以访问到电脑或者手机的摄像头并且使用它来拍摄照片。

一个简易 RTCDataChannel 的例子

`RTCDataChannel` 接口是一个特性，使用它你可以在两个点之间发送和接收任意数据。它的 API 和WebSocket API (en-US)非常相似，所以同样的代码对他们来说都可以使用。

资源
--

### 协议

#### WebRTC-proper protocols

* Application Layer Protocol Negotiation for Web Real-Time Communications
* WebRTC Audio Codec and Processing Requirements
* RTCWeb Data Channels
* RTCWeb Data Channel Protocol
* Web Real-Time Communication (WebRTC): Media Transport and Use of RTP
* WebRTC Security Architecture
* Transports for RTCWEB

#### 相关的支持协议

* Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocol
* Session Traversal Utilities for NAT (STUN)
* URI Scheme for the Session Traversal Utilities for NAT (STUN) Protocol
* Traversal Using Relays around NAT (TURN) Uniform Resource Identifiers
* An Offer/Answer Model with Session Description Protocol (SDP)
* Session Traversal Utilities for NAT (STUN) Extension for Third Party Authorization
规范
--

| Specification |
| --- |
| WebRTC: Real-Time Communication in Browsers  |
| Media Capture and Streams  |
| Media Capture from DOM Elements  |

除了这些定义 WebRTC 需要的 API 的标准之外，还有其他的一些协议，在资源中列了出来。

相关链接
----

* Firefox multistream and renegotiation for Jitsi Videobridge
* Peering Through the WebRTC Fog with SocketPeer
* Inside the Party Bus: Building a Web App with Multiple Live Video Streams + Interactive Graphics


WebGLRenderbuffer - Web API 接口参考

WebGLRenderbuffer
=================

**WebGLRenderbuffer** 接口是 WebGL API 的一部分，它提供了一个用于保存一个图像的缓存，并且可以用于渲染操作的源或者目标。

摘要
--

`WebGLRenderbuffer` 对象保存的内容不能被直接访问，因此这个对象没有提供任何用于操作其自身内容的方法和属性。当需要使用 `WebGLRenderbuffer` 对象的功能时，需要使用 `WebGLRenderingContext` 对象的以下方法：

* `WebGLRenderingContext.bindRenderbuffer()`
* `WebGLRenderingContext.createRenderbuffer()`
* `WebGLRenderingContext.deleteRenderbuffer()`
* `WebGLRenderingContext.isRenderbuffer()` (en-US)
示例
--

### 创建一个 render buffer 对象

```js
var canvas = document.getElementById("canvas");
var gl = canvas.getContext("webgl");
var buffer = gl.createRenderbuffer();
```

规范
--

| Specification |
| --- |
| WebGL Specification # 5.7 |

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

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

参见
--

* `WebGLRenderingContext.bindRenderbuffer()`
* `WebGLRenderingContext.createRenderbuffer()`
* `WebGLRenderingContext.deleteRenderbuffer()`
* `WebGLRenderingContext.isRenderbuffer()` (en-US)
* 其他缓冲：`WebGLBuffer`, `WebGLFramebuffer`


DOMQuad - Web API 接口参考

DOMQuad
=======

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

DOMQuad 是四 DOMPoints 的集合，用于定义任意四边形的角。返回 DOMQuads 允许 getBoxQuads () 即使存在任意 2D 或 3D 转换，也可以返回准确的信息。它有一个方便的边界属性返回 DOMRectReadOnly 的那些情况下，你只需要一个轴对齐的边框。

`DOMQuad.DOMQuad()`

Creates a new `DOMQuad` object.

Properties
----------

p1,p2,p3,p4 只读

are `DOMPoint` objects for each of the `DOMQuad` object's four corners.

Methods
-------

`DOMQuad.fromRect()`

Returns a new `DOMQuad` object based on the passed set of coordinates.

`DOMQuad.fromQuad()`

Returns a new `DOMQuad` object based on the passed set of coordinates.

`DOMQuad.getBounds()`

Returns a `DOMRect` object with the coordinates and dimensions of the `DOMQuad` object.

`DOMQuad.toJSON()`

Returns a JSON representation of the `DOMQuad` object.

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

| Specification |
| --- |
| Geometry Interfaces Module Level 1 # DOMQuad |

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

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


NotificationEvent - Web API 接口参考

NotificationEvent
=================

传递给 `onnotificationclick` 处理程序的参数的`NotificationEvent`接口，该接口表示通知单击事件，该事件在 `ServiceWorkerGlobalScope` ，`ServiceWorker` 。

该接口继承自`ExtendableEvent`接口。

建设者
---

`NotificationEvent()` (en-US)

创建一个新`NotificationEvent`对象。

物产
--

*从其祖先`Event`继承属性*。

`NotificationEvent.notification` (en-US) 只读

返回一个`Notification`对象，该对象表示单击以触发事件的通知。

`NotificationEvent.action` (en-US) 只读

返回用户单击的通知按钮的字符串 ID。如果用户在除操作按钮之外的其他位置单击了通知，或者该通知没有按钮，则此值返回一个空字符串。

方法
--

*从其父项\*\*`ExtendableEvent`\*\*继承方法*。

`ExtendableEvent.waitUntil()`

延长事件的寿命。告诉浏览器工作正在进行中。

例
-

```js
self.addEventListener("notificationclick", function (event) {
  console.log("On notification click: ", event.notification.tag);
  event.notification.close();

  // This looks to see if the current is already open and
  // focuses if it is
  event.waitUntil(
    clients
      .matchAll({
        type: "window",
      })
      .then(function (clientList) {
        for (var i = 0; i < clientList.length; i++) {
          var client = clientList[i];
          if (client.url == "/" && "focus" in client) return client.focus();
        }
        if (clients.openWindow) return clients.openWindow("/");
      }),
  );
});
```

规范
--

| Specification |
| --- |
| Notifications API Standard # notificationevent |

**备注：** 此接口在Notifications API 中指定，但是可以通过 `ServiceWorkerGlobalScope`访问。

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

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


URLSearchParams - Web API 接口参考

URLSearchParams
===============

**`URLSearchParams`** 接口定义了一些实用的方法来处理 URL 的查询字符串。

一个实现了 `URLSearchParams` 的对象可以直接用在 `for...of` 结构中，例如下面两行是相等的：

```js
for (const [key, value] of mySearchParams) {
}
for (const [key, value] of mySearchParams.entries()) {
}
```

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

构造函数
----

`URLSearchParams()`

返回一个 `URLSearchParams` 对象。

方法
--

该接口不继承任何属性。

`URLSearchParams.append()`

插入一个指定的键/值对作为新的搜索参数。

`URLSearchParams.delete()`

从搜索参数列表里删除指定的搜索参数及其对应的值。

`URLSearchParams.entries()`

返回一个`iterator`可以遍历所有键/值对的对象。

`URLSearchParams.get()`

获取指定搜索参数的第一个值。

`URLSearchParams.getAll()`

获取指定搜索参数的所有值，返回是一个数组。

`URLSearchParams.has()`

返回 `Boolean` 判断是否存在此搜索参数。

`URLSearchParams.keys()`

返回`iterator` 此对象包含了键/值对的所有键名。

`URLSearchParams.set()`

设置一个搜索参数的新值，假如原来有多个值将删除其他所有的值。

`URLSearchParams.sort()`

按键名排序。

`URLSearchParams.toString()`

返回搜索参数组成的字符串，可直接使用在 URL 上。

`URLSearchParams.values()`

返回`iterator` 此对象包含了键/值对的所有值。

示例
--

```js
var paramsString = "q=URLUtils.searchParams&topic=api";
var searchParams = new URLSearchParams(paramsString);

for (let p of searchParams) {
  console.log(p);
}

searchParams.has("topic") === true; // true
searchParams.get("topic") === "api"; // true
searchParams.getAll("topic"); // ["api"]
searchParams.get("foo") === null; // true
searchParams.append("topic", "webdev");
searchParams.toString(); // "q=URLUtils.searchParams&topic=api&topic=webdev"
searchParams.set("topic", "More webdev");
searchParams.toString(); // "q=URLUtils.searchParams&topic=More+webdev"
searchParams.delete("topic");
searchParams.toString(); // "q=URLUtils.searchParams"
```

### Gotchas

`URLSearchParams` 构造函数*不会*解析完整 URL，但是如果字符串起始位置有 `?` 的话会被去除。

```js
var paramsString1 = "http://example.com/search?query=%40";
var searchParams1 = new URLSearchParams(paramsString1);

searchParams1.has("query"); // false
searchParams1.has("http://example.com/search?query"); // true

searchParams1.get("query"); // null
searchParams1.get("http://example.com/search?query"); // "@" (equivalent to decodeURIComponent('%40'))

var paramsString2 = "?query=value";
var searchParams2 = new URLSearchParams(paramsString2);
searchParams2.has("query"); // true

var url = new URL("http://example.com/search?query=%40");
var searchParams3 = new URLSearchParams(url.search);
searchParams3.has("query"); // true
```

规范
--

| Specification |
| --- |
| URL Standard # urlsearchparams |

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

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

参见
--

* The `URL` interface.
* Google Developers: Easy URL manipulation with URLSearchParams


WebVR API - Web API 接口参考

WebVR API
=========

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

WebVR API 能为虚拟现实设备的渲染提供支持——例如像 Oculus Rift 或者 HTC Vive 这样的头戴式设备与 Web 应用的连接。它能让开发者将位置和动作信息转换成 3D 场景中的运动。基于这项技术能产生很多有趣的应用，比如虚拟的产品展示，可交互的培训课程，以及超强沉浸感的第一人称游戏。

概念及使用方法
-------

![Sketch of a person in a chair with wearing goggles labelled "Head mounted display (HMD)" facing a monitor with a webcam labelled "Position sensor"](/zh-CN/docs/Web/API/WebVR_API/hw-setup.png)

连接到电脑的所有 VR 设备都将由 `Navigator.getVRDevices()` (en-US) 方法返回。这个方法将返回一个包含了所有已连接设备的对象数组，每个设备对应一个对象，该对象继承自 `VRDevice` (en-US)——通常一个头显将包含两个设备——头显自身由 `HMDVRDevice` (en-US) 表示，和一个跟踪头部位置的位置捕捉传感器，由 `PositionSensorVRDevice` (en-US) 表示。

`PositionSensorVRDevice` (en-US) 对象有一个 `getState()` (en-US) 方法，该方法返回一个`VRPositionState` (en-US) 对象——这个对象代表位置传感器在指定时刻的状态，包含了一些十分有用的信息，例如速度、加速度以及运动方向，可用于根据头部运动刷新画面显示。

`HMDVRDevice.getEyeParameters()` (en-US) 方法返回一个 `VREyeParameters` (en-US) 对象，可用于获取显示区域的信息——头显可以看到多少画面。 `VREyeParameters.currentFieldOfView` (en-US) 返回一个 `VRFieldOfView` (en-US) 对象，该对象包含了 4 个角度信息来描述当前的显示区域。你可以用 `HMDVRDevice.setFieldOfView()` (en-US) 来改变当前的显示区域。

**备注：** 要了解更多关于如何在你的应用程序中使用这些接口，请阅读文章使用 WebVR API。要学习更多关于 VR 技术背后的基础概念，请阅读文章 WebVR 概念。

### 使用控制器：将 WebVR 与 Gamepad API 相结合

Many WebVR hardware setups feature controllers that go along with the headset. These can be used in WebVR apps via the Gamepad API, and specifically the Gamepad Extensions API that adds API features for accessing controller pose, haptic actuators (en-US), and more.

**备注：** Our Using VR controllers with WebVR (en-US) article explains the basics of how to use VR controllers with WebVR apps.

WebVR 接口
--------

`Navigator.getVRDevices` (en-US)

返回一个会兑现连接到电脑的 VR 设备数组的 promise。

`VRDevice` (en-US)

返回一个包括了 VR 设备 IDs，描述等信息的类。由 `HMDVRDevice` 和 `PositionSensorVRDevice` 继承。

`HMDVRDevice` (en-US)

头戴设备。提供设备双眼、当前视野（FOV）信息。

`PositionSensorVRDevice` (en-US)

VR 设备的位置传感器。获取位置、方向信息。

`VRPose`

根据一个时间戳返回包括（方向、位置、速度、加速度）的状态。

`VREyeParameters` (en-US)

给双眼提供正确渲染场景的所有信息，包括 FOV。

`VRFieldOfView` (en-US)

返回以视窗的中心点为基点的，表示 FOV 的 4 个角度值（downDegrees, leftDegrees, rightDegrees, upDegrees）。

`VRFieldOfViewReadOnly`

定义一个 FOV 必须的角度属性。由 `VRFieldOfView` 继承。

示例
--

你可以在 Github 的协议中找到一系列的案例：

* mdn/webvr-tests：简单构建的演示用于阐明基本的使用方法。
* MozVR team：更多复杂的演示，关于 WebVR 特别的资源，以及更多的内容！
规范
--

该 API 在旧的 WebVR API（已被 WebXR Device API 取代）中定义。它不再有望成为标准。

在所有浏览器都实现新的 WebXR API (en-US) 之前，建议使用框架（如：A-Frame、Babylon.js 或 Three.js）或 polyfill 来开发适用于所有浏览器的 WebXR 应用程序。

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

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

参见
--

* 建立 WebVR 的运行环境
* WebVR 的相关概念
* 怎样使用 WebVR API
* Console Game on Web——一系列有趣的概念游戏演示的集合，其中有些包括了 WebVR。
* threejs-vr-boilerplate——一个当你编写 WebVR APP 时，非常有用的用于开始编程的模板。
* Oculus Rift 主页


StyleSheet - Web API 接口参考

StyleSheet
==========

表示一个实现`StyleSheet`接口的对象样式表。CSS 样式表将进一步实现更专业的 `CSSStyleSheet` 接口。

属性
--

`StyleSheet.disabled`

返回`Boolean` (en-US)表示当前样式表是否可用。

`StyleSheet.href` 只读

返回 `DOMString` 表示样式表的位置。

`StyleSheet.media` 只读

返回 `MediaList` 表示样式的预期目标媒体

`StyleSheet.ownerNode` (en-US) 只读

返回 `Node` 将此样式表与当前文档相关联。

`StyleSheet.parentStyleSheet` (en-US) 只读

返回 `StyleSheet` 如果有的话; 返回 `null` 如果没有。

`StyleSheet.title` 只读

返回 `DOMString` 表示当前样式表的顾问标题。

`StyleSheet.type` (en-US)只读

返回 `DOMString` 表示当前样式表的语言

规范
--

| Specification |
| --- |
| CSS Object Model (CSSOM) # the-stylesheet-interface |

参见
--

* `CSSStyleSheet`


AudioParam - Web API 接口参考

AudioParam
==========

Web Audio API 的 `AudioParam` 接口代表音频相关的参数，通常是 `AudioNode`（例如 `GainNode.gain`）的参数。

`AudioParam` 可以用于安排在特定时间并遵循特定模式设置一个具体的值或者数值的变化过程。

每个 `AudioParam` 都有一个初始化为空的事件列表，用于定义值在何时发生的具体变化。当该列表不为空时，将忽略使用 `AudioParam.value` 属性进行的更改。该事件列表使我们能够使用任意基于时间线的自动化曲线来安排必须在非常精确的时间发生的更改。使用的时间定义于 `AudioContext.currentTime` 中。

AudioParam 类型
-------------

有两种类型的 `AudioParam`：*a-rate* 和 *k-rate* 参数。规范中为每个 `AudioNode` 都定义了其参数为 *a-rate* 还是 *k-rate*。

### a-rate

*a-rate* `AudioParam` 获取音频信号的每个采样帧的当前音频参数值。

### k-rate

*k-rate* `AudioParam` 对待处理的整个块使用相同的初始音频参数值，即 128 个采样帧。换句话说，其将相同的值应用于节点处理的音频中的每一帧。

实例属性
----

`AudioParam.defaultValue` (en-US) 只读

代表被具体的 `AudioNode` 创建的 `AudioParam` 的属性的初始值。

`AudioParam.maxValue` (en-US) 只读

代表参数有效范围的最大可能值。

`AudioParam.minValue` (en-US) 只读

代表参数有效范围的最小可能值。

`AudioParam.value` (en-US)

代表参数的当前浮点数音量值；初始化设定为 `defaultValue` (en-US) 的值。

实例方法
----

`AudioParam.setValueAtTime()` (en-US)

参照 `AudioContext.currentTime`，安排在一个确切的时间，立即更改 `AudioParam` 的值。新的值由 `value` 参数给定。

`AudioParam.linearRampToValueAtTime()` (en-US)

调整 `AudioParam` 的值，使其逐渐按线性变化。这个变化会从*上一个*事件指定的事件开始，跟随一个线性变化到参数给定的新值，并在 `endTime` 参数给定的时间到达新值。

`AudioParam.exponentialRampToValueAtTime()` (en-US)

调整 `AudioParam` 的值，使其逐渐按指数变化。这个变化会从*上一个*事件指定的事件开始，跟随一个指数变化到参数给定的新值，并在 `endTime` 参数给定的时间到达新值。

`AudioParam.setTargetAtTime()` (en-US)

安排逐渐改变 `AudioParam` 的值的开始时间。这个变化将从 `startTime` 指定的时间开始，并且以指定的方式向目标参数给定的值改变。指数衰减速率由 `timeConstant` 参数定义，以秒为单位。

`AudioParam.setValueCurveAtTime()` (en-US)

调整 `AudioParam` 的值以跟随一组缩放到适应给定间隔的浮点数值，该间隔从给定的起始时间开始，持续一段给定的时长。

`AudioParam.cancelScheduledValues()` (en-US)

取消所有安排的对 `AudioParam` 的未来的改变。

`AudioParam.cancelAndHoldAtTime()` (en-US)

取消所有安排的对 `AudioParam` 的未来的改变，但是保持给定时间的值，直到将来的使用其他方法产生改变。

示例
--

首先，基础示例展示了如何设置 `GainNode` 的 `gain` 值。`gain` 是 *a-rate* `AudioParam` 的一个示例，因为该值可以针对音频的每个样本帧进行不同的设置。

```js
const audioCtx = new AudioContext();

const gainNode = audioCtx.createGain();
gainNode.gain.value = 0;
```

下一个示例展示了如何修改 `DynamicsCompressorNode` 的一些参数值。这是 *k-rate* `AudioParam` 的一个示例，因为它是一次可以为整个音频块设置的值。

```js
const compressor = audioCtx.createDynamicsCompressor();
compressor.threshold.setValueAtTime(-50, audioCtx.currentTime);
compressor.knee.setValueAtTime(40, audioCtx.currentTime);
compressor.ratio.setValueAtTime(12, audioCtx.currentTime);
compressor.attack.setValueAtTime(0, audioCtx.currentTime);
compressor.release.setValueAtTime(0.25, audioCtx.currentTime);
```

规范
--

| Specification |
| --- |
| Web Audio API # AudioParam |

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

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

参见
--

* 使用 Web Audio API


TextDecoderStream - Web API 接口参考

TextDecoderStream
=================

Encoding API 接口的 **`TextDecoderStream`** 方法将二进制编码（如 UTF-8 等）的文本流转换为字符串流。它与 `TextDecoder` 的流形式等价。

构造函数
----

`TextDecoderStream()`

创建一个新的 `TextDecoderStream` 对象。

属性
--

`TextDecoderStream.encoding`只读

一种编码。

`TextDecoderStream.fatal`只读

一个 `boolean`，表示错误是否是致命的。

`TextDecoderStream.ignoreBOM`只读

一个 `boolean`，表示是否忽略字节顺序标记。

`TextDecoderStream.readable`只读

返回此对象控制的 `ReadableStream` 实例。

`TextDecoderStream.writable`只读

返回此对象控制的 `WritableStream` 实例。

示例
--

* 流式传输结构化数据和 HTML 示例
* 一个使用 `TextDecoderStream` 流式处理 fetch 请求的示例。
规范
--

| Specification |
| --- |
| Encoding Standard # interface-textdecoderstream |

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

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

参见
--

* `TextEncoderStream`
* Streams API 概念
* Experimenting with the Streams API


HTMLAreaElement - Web API 接口参考

HTMLAreaElement
===============

**`HTMLAreaElement`** 接口提供了一些属性和方法 (除了常见的对象`HTMLElement` 接口提供的属性和方法通过继承也能获取到) 用来控制一个 area 元素的布局和展现。

属性
--

*从它的父对象`HTMLElement`继承的，还有从`URLUtils`继承的。*

`HTMLAreaElement.accessKey`

值为一个 `DOMString` 类型，包含了一个简单的字符代表键盘上的一个按键，相当于快捷键。

`HTMLAreaElement.alt`

值为一个`DOMString` 类型，代表了 `alt` HTML 属性，包含一个 area 对象显示异常的情况下显示的备用文本字符串。

`HTMLAreaElement.coords`

值为一个 `DOMString` 类型，代表了 `coords` HTML 属性，包含了定义热区相关的坐标。

`HTMLAreaElement.download`
实验性

值为一个 `DOMString` 类型，表明此资源是将要被下载的资源而不是显示在浏览器页面中。值为下载保存文件的推荐文件名。如果名字在操作系统里不是一个合格的文件名格式，浏览器将会做相应的修改。

`URLUtils.hash`

Is a `DOMString` containing the fragment identifier (including the leading hash mark (#)), if any, in the referenced URL.

`URLUtils.host`

Is a `DOMString` containing the hostname and port (if it's not the default port) in the referenced URL.

`URLUtils.hostname`

Is a `DOMString` containing the hostname in the referenced URL.

`URLUtils.href`

Is a `DOMString` containing that reflects the `href` HTML attribute, containing a valid URL of a linked resource.

`HTMLAreaElement.hreflang`

Is a `DOMString` containing that reflects the `hreflang` HTML attribute, indicating the language of the linked resource.

`HTMLAreaElement.media`

Is a `DOMString` containing that reflects the `media` HTML attribute, indicating target media of the linked resource.

`HTMLAreaElement.noHref`
已弃用

Is a `Boolean` (en-US) flag indicating if the area is inactive (`true`) or active (`false`).

`URLUtils.password`

Is a `DOMString` containing the password specified before the domain name.

`URLUtils.origin` 只读

Returns a `DOMString` containing the origin of the URL, that is its scheme, its domain and its port.

`URLUtils.pathname`

Is a `DOMString` containing the path name component, if any, of the referenced URL.

`URLUtils.port`

Is a `DOMString` containing the port component, if any, of the referenced URL.

`URLUtils.protocol`

Is a `DOMString` containing the protocol component (including trailing colon `':'`), of the referenced URL.

`HTMLAreaElement.rel` (en-US)

Is a `DOMString` that reflects the `rel` HTML attribute, indicating relationships of the current document to the linked resource.

`HTMLAreaElement.relList` (en-US) 只读

Returns a `DOMTokenList` that reflects the `rel` HTML attribute, indicating relationships of the current document to the linked resource, as a list of tokens.

`HTMLAreaElement.search` (en-US)

Is a `DOMString` containing the search element (including leading question mark `'?'`), if any, of the referenced URL.

`HTMLAreaElement.shape`

Is a `DOMString` that reflects the `shape` HTML attribute, indicating the shape of the hot-spot, limited to known values.

`HTMLAreaElement.tabIndex`

Is a `long` containing the element's position in the tabbing order.

`HTMLAreaElement.target` (en-US)

Is a `DOMString` that reflects the `target` HTML attribute, indicating the browsing context in which to open the linked resource.

`HTMLAreaElement.type`

Is a `DOMString` that reflects the `type` HTML attribute, indicating the MIME type of the linked resource.

`URLUtils.username`

Is a `DOMString` containing the username specified before the domain name.

Methods
-------

*Inherits methods from its parent, `HTMLElement` and implement those from `URLUtils`.*

`URLUtils.toString()`

Returns a `DOMString` containing the whole URL of the script executed in the `Worker`. It is a synonym for `URLUtils.href`.

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

| Specification |
| --- |
| HTML Standard # htmlareaelement |

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

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

See also
--------

* HTML element implementing this interface: `<area>`.


页面可见性 API - Web API 接口参考

页面可见性 API
=========

页面可见性 API 提供了一些事件，你可以通过查看这些事件来了解文档何时变为可见或隐藏，还提供了一些功能来查看页面的当前可见性状态。

通过让页面在文档不可见时避免执行不必要的任务，这对于节省资源和提高性能特别有用。

概念与用途
-----

当用户最小化窗口或切换到另一个标签页时，API 会发送 `visibilitychange` 事件，让监听者知道页面的状态已发生变化。你可以检测到该事件并执行某些操作或采取不同的行为。例如，如果你的 web 应用正在播放视频，当用户将标签页放到后台时，它可以暂停视频，当用户返回标签页时，它又可以恢复播放。用户不会失去在视频中的位置，视频的配乐也不会干扰新的前台标签页中的音频，用户在此期间也不会错过任何视频。

`<iframe>` 的可见性状态与父文档相同。使用 CSS 属性（如 `display: none;`）隐藏 `<iframe>` 不会触发可见性事件，也不会改变框架内文档的状态。

### 使用情景

让我们来看看页面可见性 API 的几个使用案例。

* 网站有图片轮播效果，只有在用户观看轮播的时候，才会自动展示下一张幻灯片。
* 显示信息仪表盘的应用程序不希望在页面不可见时轮询服务器进行更新。
* 页面想要检测何时正在预渲染，以便可以准确的计算页面浏览量。
* 当设备进入待机模式（用户按下电源键关闭屏幕）时，网站想要关闭设备声音。

开发人员在过去使用不完善的代理来检测这一点。例如，通过观察 window 上的 `blur` 和 `focus` 事件，可以帮助你了解页面何时不是活动页面，但这并不能告诉你，页面实际上已被用户隐藏。页面可见性 API 可解决这一问题。

**备注：** 虽然 `onblur` 和 `onfocus` 会告诉你用户是否切换了窗口，但这并不一定意味着它被隐藏了。只有当用户切换标签页或最小化包含标签页的浏览器窗口时，页面才会被隐藏。

### 制定有助于后台页面性能的策略

在页面可见性 API 之外，用户代理会采取许多策略来减轻后台或隐藏选项卡对性能的影响。这些可能包括：

* 大多数浏览器会停止向后台标签页或隐藏的 `<iframe>` 发送 `requestAnimationFrame()` 回调，以提高性能和电池寿命。
* 在后台或不活动标签页中，`setTimeout()` 等计时器会被节流，以帮助提高性能。详情请参阅延迟时间超过指定时间的原因。
* 浏览器实施基于预算的后台超时节流。现代浏览器的操作方式大同小异，具体细节如下：
    + 在 Firefox 中，后台标签页中的每个窗口都有自己的时间预算（以毫秒为单位），最大值和最小值分别为 +50 毫秒和 -150 毫秒。Chrome 浏览器与之非常相似，只是预算以秒为单位。
    + 窗口在 30 秒后会受到节流，节流延迟规则与为窗口定时器指定的规则相同（请再次参阅延迟时间超过指定时间的原因）。在 Chrome 浏览器中，该值为 10 秒。
    + 只有当预算为非负数时，才允许执行定时器任务。
    + 定时器代码一旦运行完毕，其执行时间就会从窗口的超时预算中扣除。
    + 在 Firefox 和 Chrome 浏览器中，预算以每秒 10 毫秒的速度重新生成。

某些进程不受这种节流行为的影响。在这种情况下，可以使用页面可见性 API 来减少标签页隐藏时对性能的影响。

* 正在播放音频的标签页被视为前台进程，不会被节流。
* 运行使用实时网络连接（WebSocket 和 WebRTC）的代码的标签页不会被节流，以避免关闭这些连接时超时和意外关闭。
* 为了避免超时，IndexedDB 进程也没有节流。
对其他接口的扩展
--------

### 实例属性

页面可见性 API 为 `Document` 接口添加了以下属性：

`Document.hidden`
已弃用
 只读

如果页面处于隐藏状态，则返回 `true`，否则返回 `false`。

`Document.visibilityState` 只读

说明文档当前可见性状态的字符串。可能的值有：

`visible`

页面内容至少部分可见。在实践中，这意味着页面是非最小化窗口的前景选项卡。

`hidden`

页面内容对用户不可见，原因可能是文档标签页在后台或属于最小化窗口的一部分，也可能是设备屏幕关闭。

### 事件

页面可见性 API 为 `Document` 接口添加了以下事件：

`visibilitychange`

当标签页的内容变为可见或被隐藏时触发。

示例
--

### 在页面隐藏时暂停音频

该示例会在用户切换到不同标签页时暂停音频，并在用户切换回标签页时播放音频。

#### HTML

```html
<audio
 controls
 src="https://mdn.github.io/webaudio-examples/audio-basics/outfoxing.mp3"></audio>
```

#### JavaScript

```js
const audio = document.querySelector("audio");

// 处理页面可见性变化：
// - 如果页面隐藏，暂停音频
// - 如果页面显示，播放音频
document.addEventListener("visibilitychange", () => {
  if (document.hidden) {
    audio.pause();
  } else {
    audio.play();
  }
});
```

#### 结果

试着播放音频，然后切换到不同的标签页，然后再返回。

规范
--

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

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

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


地理位置 API - Web API 接口参考

地理位置 API
========

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

**地理位置 API**（Geolocation API）允许用户向 web 应用程序提供他们的位置。出于隐私考虑，报告地理位置前会先请求用户许可。

Web 扩展若期望使用 `Geolocation` 对象，则必须将 `"geolocation"` 权限添加到其清单（manifest）中。在第一次请求地理位置访问时，用户的操作系统将提示用户提供相应的权限。

概念和用法
-----

通常，要在地图上标出用户的位置或显示与用户地理位置相关的个性化信息时，我们需要在 web 应用程序中检索用户的位置信息。

地理位置 API 是通过调用 `navigator.geolocation` 来访问的；这将使得用户的浏览器请求获得用户位置数据相关的权限。如果用户授予了权限，则浏览器将使用设备上可用的最佳方式来获取此信息（例如 GPS）。

开发人员现在可用通过不同的方式访问位置信息：

* `Geolocation.getCurrentPosition()`：检索设备的当前位置。
* `Geolocation.watchPosition()`：注册一个处理函数，在设备位置发生改变时都会自动调用，并返回改变后的位置信息。

对于上述的几种方法，其回调函数最多有三个参数：

* 一个必须的成功的回调函数：如果位置检索成功，则调用该回调函数，并以 `GeolocationPosition` 对象（用于提供位置数据）作为其唯一的参数。
* 一个可选的错误回调函数：如果位置检索失败，则调用该回调函数，并以 `GeolocationPositionError` 对象（用于提供访问出错的信息）作为其唯一的参数。
* 一个可选的对象：用于提供检索位置数据的选项。

有关地理位置使用的信息，请参阅使用地理位置 API。

接口
--

`Geolocation`

该 API 的主类——包含检索用户当前的位置、监听位置变化以及清除先前设置的监听器的方法。

`GeolocationPosition`

表示用户的位置。`GeolocationPosition` 实例会在成功调用 `Geolocation` 中的方法时返回。包含了一个时间戳和一个 `GeolocationCoordinates` 对象实例。

`GeolocationCoordinates`

表示用户位置的坐标。`GeolocationCoordinates` 实例包含经纬度和其他相关的重要信息。

`GeolocationPositionError`

`GeolocationPositionError` 实例会在未能成功调用 `Geolocation` 中的方法时返回。包含了错误代码和错误消息。

`Navigator.geolocation`

API 的入口点。返回一个 `Geolocation` 对象实例，从中可以访问所有其他的功能。

示例
--

参见使用地理位置 API 以获取示例代码。

规范
--

| Specification |
| --- |
| Geolocation API # geolocation\_interface |

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

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

### 可用性

基于 Wi-Fi 的位置信息通常由 Google 提供，但该原生的地理位置 API 可能无法在中国使用。你可用使用如百度、高德或腾讯等本地的第三方提供商。这些服务使用用户的 IP 地址或本地应用来提供增强的位置信息。

参见
--

* 使用地理位置 API
* w3.org 上的地理位置 API
* Who moved my geolocation? (Hacks blog)


ImageBitmap - Web API 接口参考

ImageBitmap
===========

**`ImageBitmap`** 接口表示能够被绘制到 `<canvas>` 上的位图图像，具有低延迟的特性。运用 `createImageBitmap()` (en-US) 工厂方法模式，它可以从多种源中生成。 `ImageBitmap`提供了一种异步且高资源利用率的方式来为 WebGL 的渲染准备基础结构。

属性
--

`ImageBitmap.height` 只读

无符号长整型数值，表示 ImageData 的 CSS 像素单位的高度。

`ImageBitmap.width` 只读

无符号长整型数值，表示 ImageData 的 CSS 像素单位的宽度。

方法
--

`ImageBitmap.close()` (en-US)

释放 ImageBitmap 所相关联的所有图形资源。

规范
--

| Specification |
| --- |
| HTML Standard # imagebitmap |

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

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

另见
--

* `ImageBitmapFactories.createImageBitmap()` (en-US)
* `CanvasRenderingContext2D.drawImage()`
* `WebGLRenderingContext.texImage2D()`
* `OffScreenCanvas.transferToImageBitmap()`


NodeIterator - Web API 接口参考

NodeIterator
============

**`NodeIterator`** 接口表示一个遍历 DOM 子树中节点列表的成员的迭代器。节点将按照文档顺序返回。

NodeIterator 可以使用 `Document.createNodeIterator()` 方法创建，如下所示：

```js
var nodeIterator = document.createNodeIterator(root, whatToShow, filter);
```

属性
--

*这个接口不继承任何属性。*

`NodeIterator.root` (en-US) 只读

返回一个 `Node`，它代表创建 NodeIterator 时指定的根节点。

`NodeIterator.whatToShow` (en-US) 只读

返回一个无符号长整型，它是一个由描述必须呈现的 `Node` 类型的常量构成的位掩码。不匹配的节点被跳过，但是如果相关，他们的子节点可能被包括在内。可能的值是：

| Constant | Numerical value | Description |
| --- | --- | --- |
| `NodeFilter.SHOW_ALL` | `-1` (that is the max value of `unsigned long`) | 显示所有节点。 |
| `NodeFilter.SHOW_ATTRIBUTE`
已弃用
 | `2` | 显示属性 `Attr` 节点。只有当用一个 `Attr` 节点作为根节点来创建 `NodeIterator` 时才有意义; 在这种情况下，这意味着属性节点会出现在迭代或遍历的首位。因为属性永远不会是其他节点的子节点，当遍历整个文档树时它们不会出现。 |
| `NodeFilter.SHOW_CDATA_SECTION`
已弃用
 | `8` | 显示`CDATASection` 节点。 |
| `NodeFilter.SHOW_COMMENT` | `128` | 显示`Comment` 节点。 |
| `NodeFilter.SHOW_DOCUMENT` | `256` | 显示`Document` 节点。 |
| `NodeFilter.SHOW_DOCUMENT_FRAGMENT` | `1024` | 显示`DocumentFragment`节点。 |
| `NodeFilter.SHOW_DOCUMENT_TYPE` | `512` | 显示`DocumentType` 节点。 |
| `NodeFilter.SHOW_ELEMENT` | `1` | 显示`Element` 节点。 |
| `NodeFilter.SHOW_ENTITY`
已弃用
 | `32` | 显示 `Entity` 节点。只有当用一个 `Entity` 节点作为它的根节点来创建一个 `NodeIterator` 时才有意义; 在这种情况下， `Entity` 节点会出现在迭代或遍历的首位。因为 `Entity` 永远不会是其他节点的子节点，当遍历整个文档树时它们不会出现。 |
| `NodeFilter.SHOW_ENTITY_REFERENCE`
已弃用
 | `16` | 显示`EntityReference` 节点。 |
| `NodeFilter.SHOW_NOTATION`
已弃用
 | `2048` | 显示 `Notation` 节点。只有当用一个 `Notation` 节点作为它的根节点时来创建一个 `NodeIterator` 才有意义; 在这种情况下， `Notation` 节点会出现在迭代或遍历的首位。因为 `Notation` 永远不会是其他节点的子节点，当遍历整个文档树时它们不会出现。 |
| `NodeFilter.SHOW_PROCESSING_INSTRUCTION` | `64` | 显示`ProcessingInstruction` (en-US) 节点。 |
| `NodeFilter.SHOW_TEXT` | `4` | 显示`Text` (en-US) 节点。 |

`NodeIterator.filter` (en-US) 只读

返回一个用来选择相关节点的 `NodeFilter` .

`NodeIterator.expandEntityReferences` 只读
已弃用

Is a `Boolean` (en-US) indicating if, when discarding an `EntityReference` its whole sub-tree must be discarded at the same time.

`NodeIterator.referenceNode` (en-US) 只读
实验性

返回当前遍历到的 `Node` .

`NodeIterator.pointerBeforeReferenceNode` (en-US) 只读
实验性

Returns a `Boolean` (en-US) flag that indicates whether the `NodeIterator` is anchored before, the flag being `true`, or after, the flag being `false`, the anchor node.

方法
--

*这个接口不会继承任何属性。*

`NodeIterator.detach()` (en-US)
已弃用

这个方法不是必需的。它现在什么也不做。之前用来告诉引擎，`NodeIterator` 已经不会再使用，现在已经不做任何事情。

`NodeIterator.previousNode()` (en-US)

返回前一个 `Node`，如果不存在则返回 `null`.

`NodeIterator.nextNode()` (en-US)

返回下一个 `Node`, 如果不存在则返回`null` .

规范
--

| Specification |
| --- |
| DOM Standard # interface-nodeiterator |

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

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

参见
--

* The creator method: `Document.createNodeIterator()`.
* Related interfaces: `NodeFilter`, `TreeWalker`.