recursal/MDN huggingface dataset:
WebGL2RenderingContext.createVertexArray()
==========================================

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

WebGL 2 API 中的 \*\*`WebGL2RenderingContext.createVertexArray()`\*\*方法创建并初始化（creates and initializes）一个 `WebGLVertexArrayObject` 的对象 (object) ，它代表一个指向顶点数组数据的顶点数组对象（vertex array object (VAO) ），并为不同的顶点数据集提供名称。

语法
--


```js
createVertexArray()
```

### 参数

没有参数

### 返回值

一个`WebGLVertexArrayObject`对象 代表 一个顶点数组对象 (VAO) ，该对象指向顶点数据。

示例
--


```js
var vao = gl.createVertexArray();
gl.bindVertexArray(vao);

// ...
// calls to bindBuffer or vertexAttribPointer
// which will be "recorded" in the VAO
// ...
```

规范
--

| Specification |
| --- |
| WebGL 2.0 Specification # 3.7.17 |

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

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

参见
--

* `WebGLVertexArrayObject`
* `bindVertexArray`
WebGL2RenderingContext.beginQuery()
===================================

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

WebGL 2 API 的\*\*`WebGL2RenderingContext.beginQuery()`\*\* 方法启动一个异步查询，`target` 参数表明是哪种类型的查询。

语法
--
```

void gl.beginQuery(target, query);
```

### 参数

target

`GLenum` (en-US) 指定查询个的 target，可能的值有：

* `gl.ANY_SAMPLES_PASSED`: Specifies an occlusion query: these queries detect whether an object is visible (whether the scoped drawing commands pass the depth test and if so, how many samples pass).
* `gl.ANY_SAMPLES_PASSED_CONSERVATIVE`: 和以上一样，但是是一个不精确和更快的版本。
* `gl.TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN`: Number of primitives that are written to transform feedback buffers.

`query`

一个`WebGLQuery` 对象用于查询。

### 返回值

None.

例子
--


```js
var query = gl.createQuery();
gl.beginQuery(gl.ANY\_SAMPLES\_PASSED, query);

// ...
```

规范
--

| Specification |
| --- |
| WebGL 2.0 Specification # 3.7.12 |

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

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

参考
--

* `WebGLQuery`
WebGL2RenderingContext.drawBuffers()
====================================

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

WebGL 2 API的 **`WebGL2RenderingContext.drawBuffers()`** 方法定义了将写入零散数据（fragment colors）的绘制缓存 (draw buffer)。绘制缓存设置了上一次绑定帧缓存状态，如果没有帧缓存可用的话，则用绘制缓存。

语法
--
```

void gl.drawBuffers(buffers);
```

### 参数

`buffers`

一个 `GLenum` (en-US)的`Array` 对碎片颜色的说明将被写入缓冲区。可能的值有：

* `gl.NONE`: 碎片着色器的输出没有被写入到任何颜色缓存中。
* `gl.BACK`: 碎片着色器的输出被写入到返回的颜色缓存中。
* `gl.COLOR_ATTACHMENT{0-15}`: 碎片着色器的输出被写入当前帧缓存的第 n 个颜色缓存中。Fragment shader output is written in the nth color attachment of the current framebuffer.

### 返回值

没有。

### 报错信息

* 如果 `buffers` 包含了不止一个合法值， `gl.INVALID_ENUM`错误会被抛出
示例
--


```js
gl.drawBuffers([gl.NONE, gl.COLOR\_ATTACHMENT1]);
```

规范
--

| Specification |
| --- |
| WebGL 2.0 Specification # 3.7.11 |

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

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

详见
--

* `WebGL2RenderingContext.clearBuffer[fiuv]()` (en-US)
WebGL2RenderingContext.uniform[1234][uif][v]()
==============================================

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

WebGL API的\*\*`WebGL2RenderingContext.uniform[1234][uif][v]()`\*\* 方法提供了 uniform（es）变量的详细值

**备注：** `ui` *意为无符号整数*, `i` *意为整数，*`f` *意为浮点数*, 并且 `v` *意为矢量。*
 并不是所有的组合都是有效的：`u` 不能是 `f`的组合。详见下方语法表格。用 正则表达式概括语法：`uniform[1234](u?i|f)v?`

语法
--
```

void gl.uniform1ui(location, v0);
void gl.uniform2ui(location, v0, v1);
void gl.uniform3ui(location, v0, v1, v2);
void gl.uniform4ui(location, v0, v1, v2, v3);
void gl.uniform1fv(location, data, optional srcOffset, optional srcLength);
void gl.uniform2fv(location, data, optional srcOffset, optional srcLength);
void gl.uniform3fv(location, data, optional srcOffset, optional srcLength);
void gl.uniform4fv(location, data, optional srcOffset, optional srcLength);
void gl.uniform1iv(location, data, optional srcOffset, optional srcLength);
void gl.uniform2iv(location, data, optional srcOffset, optional srcLength);
void gl.uniform3iv(location, data, optional srcOffset, optional srcLength);
void gl.uniform4iv(location, data, optional srcOffset, optional srcLength);
void gl.uniform1uiv(location, data, optional srcOffset, optional srcLength);
void gl.uniform2uiv(location, data, optional srcOffset, optional srcLength);
void gl.uniform3uiv(location, data, optional srcOffset, optional srcLength);
void gl.uniform4uiv(location, data, optional srcOffset, optional srcLength);
```

### 参数

location

一个 `WebGLUniformLocation` 对象包含了本地 uniform 属性的修改。

`value, v0, v1, v2, v3`

一个新的值被应用到 uniform 变量当中。合理情况：

* `Number` 如果是无符号整数值 (则用 `ui`方法),如果是整数值 (则用 `i`方法), 如果是浮点数 (则用`f`方法).
* `Uint32Array` 用于无符号整数向量（矢量）方法 (则用`uiv`方法).

### 返回值

没有返回值

规范
--

| Specification |
| --- |
| WebGL 2.0 Specification # 3.7.8 |

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

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

详见
--

* `WebGLRenderingContext.uniform()`
WebGL2RenderingContext.bindBufferBase()
=======================================

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

WebGL 2 API 的 **`WebGL2RenderingContext.bindBufferBase()`** 方法将一个 `WebGLBuffer` 绑定到某个点 (`target`) 的特定的 `index`上。

语法
--
```

void gl.bindBufferBase(target, index, buffer);
```

### 参数

`target`

`Glenum` (en-US) 指定绑定操作的目标。可能的值：

* `gl.TRANSFORM_FEEDBACK_BUFFER`
* `gl.UNIFORM_BUFFER`

`index`

`GLuint` (en-US) 指定目标（`target`）的 index。

`buffer`

绑定到目标点（`target`）的 `WebGLBuffer` 。

### 返回值

无。

示例
--


```js
gl.bindBufferBase(gl.TRANSFORM\_FEEDBACK\_BUFFER, 0, buffer);
```

规范
--

| Specification |
| --- |
| WebGL 2.0 Specification # 3.7.16 |

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

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

相关链接
----

* `WebGL2RenderingContext.getIndexedParameter()` (en-US)
WebGL2RenderingContext.beginTransformFeedback()
===============================================

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

WebGL 2 API 的 **`WebGL2RenderingContext.beginTransformFeedback()`** 方法开始一个变换回传（Transform Feedback）操作。

语法
--
```

void gl.beginTransformFeedback(primitiveMode);
```

### 参数

`primitiveMode`

A `GLenum` (en-US) specifying the output type of the primitives that will be recorded into the buffer objects that are bound for transform feedback. 可能的值：

* `gl.POINTS`
* `gl.LINES`
* `gl.TRIANGLES`

### 返回值

无。

示例
--


```js
var transformFeedback = gl.createTransformFeedback();
gl.bindTransformFeedback(gl.TRANSFORM\_FEEDBACK, transformFeedback);
gl.beginTransformFeedback(gl.TRIANGLES);
gl.drawArrays(gl.TRIANGLES, 0, 3);
```

规范
--

| Specification |
| --- |
| WebGL 2.0 Specification # 3.7.15 |

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

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

相关链接
----

* `WebGLTransformFeedback` (en-US)
WebGL2RenderingContext.createSampler()
======================================

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

WebGL 2 API 定义的 **`WebGL2RenderingContext.createSampler()`** 方法用于创建并初始化 `WebGLSampler` 对象。

句法
--
```

WebGLSampler gl.createSampler();
```

### 参数

无。

### 返回值

`WebGLSampler` 对象。

例子
--

`gl` 必须是 `WebGL2RenderingContext` 类型。WebGL 1 不支持 `WebGLSampler` 对象。


```js
var sampler = gl.createSampler();
```

规范
--

| Specification |
| --- |
| WebGL 2.0 Specification # 3.7.13 |

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

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

另见
--

* `WebGLSampler`
WebGL2RenderingContext.uniformMatrix[234]x[234]fv()
===================================================

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

WebGL 2 API 的 **`WebGL2RenderingContext.uniformMatrix[234]x[234]fv()`** 方法向 uniform 变量中传入指定的矩阵值。

**备注：** 这个方法不用 `2x2`, `3x3`, 和 `4x4` 版本 . 他们通常用`2`, `3`, 和`4`, 分别表示，详见下方语法。

语法
--
```

void gl.uniformMatrix2fv(location, transpose, data, optional srcOffset, optional srcLength);
void gl.uniformMatrix3x2fv(location, transpose, data, optional srcOffset, optional srcLength);
void gl.uniformMatrix4x2fv(location, transpose, data, optional srcOffset, optional srcLength);
void gl.uniformMatrix2x3fv(location, transpose, data, optional srcOffset, optional srcLength);
void gl.uniformMatrix3fv(location, transpose, data, optional srcOffset, optional srcLength);
void gl.uniformMatrix4x3fv(location, transpose, data, optional srcOffset, optional srcLength);
void gl.uniformMatrix2x4fv(location, transpose, data, optional srcOffset, optional srcLength);
void gl.uniformMatrix3x4fv(location, transpose, data, optional srcOffset, optional srcLength);
void gl.uniformMatrix4fv(location, transpose, data, optional srcOffset, optional srcLength);
```

### 参数

location

一个包含想要修改的 uniform 变量的`WebGLUniformLocation` 对象

transpose

一个决定是否转置矩阵的布尔值（ `GLboolean` (en-US)。在 webgl 中必须为`false`。

data

一个包含方阵中浮点数的类数组对象 (TypeArray) `Float32Array`。

### 返回值

没有。

例子
--


```js
gl.uniformMatrix2x3fv(loc, false, [1, 2, 3, 4, 5, 6]);
```

规范
--

| Specification |
| --- |
| WebGL Specification # 5.14.10 |

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

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

令见
--

* `WebGLRenderingContext.uniformMatrix()`
FileSystemFileHandle：createWritable() 方法
========================================

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

`FileSystemFileHandle` 接口的 **`createWritable()`** 方法用于创建一个 `FileSystemWritableFileStream` 对象，可用于写入文件。此方法返回一个可兑现这些写入流的 `Promise` 对象。

任何通过写入流造成的更改在写入流被关闭前都不会反映到文件句柄所代表的文件上。这通常是将数据写入到一个临时文件来实现的，然后只有在写入文件流被关闭后才会用临时文件替换掉文件句柄所代表的文件。

语法
--


```js
createWritable()
createWritable(options)
```

### 参数

`options` 可选

一个包含以下属性的对象：

`keepExistingData`

布尔值，默认为 `false`。当设为 `true` 时，如果文件存在，则现将现有文件的内容复制到临时文件，否则临时文件初始时内容为空。


### 返回值

一个 `Promise` 对象，可兑现一个 `FileSystemWritableFileStream` 对象。

### 异常

NotAllowedError

如果句柄 `readwrite` 模式的 `PermissionStatus.state` (en-US) 不为 `'granted'`，则抛出此异常。

示例
--

以下异步函数用于将给定内容写入文件句柄，从而写入磁盘。


```js
async function writeFile(fileHandle, contents) {
  // 创建一个 FileSystemWritableFileStream 用来写入。
  const writable = await fileHandle.createWritable();

  // 将文件内容写入到流中。
  await writable.write(contents);

  // 关闭文件并将内容写入磁盘。
  await writable.close();
}
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemfilehandle-createwritable |

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

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

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemFileHandle：getFile() 方法
=================================

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

`FileSystemFileHandle` 接口的 **`getFile()`** 方法返回一个 `Promise` 对象，可兑现一个 `File` 对象，其表示磁盘上句柄所代表的条目的状态。

如果磁盘上的文件在调用了此方法后发生了更改或是被移除，那么返回的 `File` 对象可能会不再可读。

语法
--


```js
getFile()
```

### 参数

无。

### 返回值

一个 `Promise` 对象，可兑现一个 `File` 对象。

### 异常

NotAllowedError

如果只读模式的 `PermissionStatus.state` (en-US) 不是 `granted` ，则抛出此异常。

示例
--

下面的异步函数可以显示一个文件选择器，并在选择了文件时使用 `getFile()` 方法取得内容。


```js
async function getTheFile() {
  // 打开文件选择器
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // 获取文件内容
  const fileData = await fileHandle.getFile();
}
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemfilehandle-getfile |

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

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

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
FileSystemFileHandle：createSyncAccessHandle() 方法
================================================

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

`FileSystemFileHandle` 接口的 **`createSyncAccessHandle()`** 方法返回一个 `Promise` 对象，可兑现一个用于同步读写文件的 `FileSystemSyncAccessHandle` 对象。此方法的同步特性带来了性能优势，但是只能在专用于操作源私有文件系统上的文件的 Web Worker 中使用。

创建 `FileSystemSyncAccessHandle` 会对与文件句柄关联的文件进行独占锁定。这用于在文件已有的访问句柄被关闭前，阻止对文件创建更多的 `FileSystemSyncAccessHandle` 或 `FileSystemWritableFileStream`。

语法
--


```js
createSyncAccessHandle()
```

### 参数

无。

### 返回值

一个 `Promise` 对象，可兑现一个 `FileSystemSyncAccessHandle` 对象。

### 异常

`InvalidStateError` `DOMException`

如果 `FileSystemSyncAccessHandle` 对象代表的不是源私有文件系统上的文件，抛出此异常。

`NoModificationAllowedError` `DOMException`

如果浏览器无法获得文件句柄所关联的文件的锁定，抛出此异常。

`NotAllowedError` `DOMException`

如果在 API 层面上没有被授予权限（也就是需要调用 `FileSystemHandle.requestPermission`），抛出此异常。

示例
--

以下异步事件处理函数处于 Web Worker 上下文。其中的代码片段创建了一个同步文件访问句柄。


```js
onmessage = async (e) => {
  // 获取从主线程发往 worker 的消息
  const message = e.data;

  // 获取草稿文件的句柄
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // 获取同步访问句柄
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // ……

  // 用完 FileSystemSyncAccessHandle 记得把它关闭
  accessHandle.close();
};
```

规范
--

| Specification |
| --- |
| File System Standard # api-filesystemfilehandle-createsyncaccesshandle |

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

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

参见
--

* 文件系统 API
* 文件系统访问 API：简化本地文件访问
File drag and drop
==================

HTML 拖放接口使得 web 应用能够在网页中拖放文件。这篇文档介绍了 web 应用如何接受从底层平台的文件管理器拖动一个或多个文件到网页的操作。

拖放的主要步骤是为 `drop` 事件定义一个*释放区*(释放文件的目标元素) 和为`dragover`事件定义一个事件处理程序。下面描述了这些步骤，包括示例程序片段。完整的源码在MDN's drag-and-drop repository (欢迎提交 pull requests 和/或 issues).

注意：`HTML drag and drop`定义了两套不同的 API 来支持拖放文件。一个`DataTransfer`接口和另一个`DataTransferItem`与`DataTransferItemList`接口。这个示例介绍了这两种 API 的用法 (没有使用任何 Gecko 专用的接口)。

定义拖放区域
------

触发 `drop` 事件的目标元素需要一个`ondrop` 事件处理函数。下面这一段代码以一个 `<div>` 元素为例展示了这些工作是如何完成的：


```html
<div id="drop\_zone" ondrop="dropHandler(event);">
  <p>Drag one or more files to this Drop Zone ...</p>
</div>
```


一般来说，在实际应用中需要定义一个 `dragover` 事件的处理函数并在其中加入关闭浏览器默认拖放行为的代码。你需要定义一个 `ondragover` (en-US) 事件处理函数：


```html
<div
 id="drop\_zone"
 ondrop="dropHandler(event);"
 ondragover="dragOverHandler(event);">
  <p>Drag one or more files to this Drop Zone ...</p>
</div>
```


最后，在实际应用中可能需要给实现释放文件的元素加些样式来从视觉上向使用者说明这是一个有效释放区域。在这个示例中，实现释放文件的元素将使用如下样式：


```css
#drop\_zone {
  border: 5px solid blue;
  width: 200px;
  height: 100px;
}
```


**备注：** 注意当执行将文件拖入浏览器的操作时操作系统并不会触发 `dragstart` 和 `dragend` 事件。

执行释放事件
------

当用户释放文件时 `drop` 事件将会被触发。在下面的 drop 处理函数中，如果浏览器支持 `DataTransferItemList` 接口，则可以使用 `getAsFile()` 来获取每个文件；否则使用 `DataTransfer` 接口的 `files` 属性来获取每个文件。

这个示例展示了如何讲每个被拖动的文件的名字输出到控制台。在实际应用中可能会用到 `File API` 来处理一个文件。

注意在这个例子中，任何被拖动的非文件内容都会被忽略。


```js
function dropHandler(ev) {
  console.log("File(s) dropped");

  // Prevent default behavior (Prevent file from being opened)
  ev.preventDefault();

  if (ev.dataTransfer.items) {
    // Use DataTransferItemList interface to access the file(s)
    for (var i = 0; i < ev.dataTransfer.items.length; i++) {
      // If dropped items aren't files, reject them
      if (ev.dataTransfer.items[i].kind === "file") {
        var file = ev.dataTransfer.items[i].getAsFile();
        console.log("... file[" + i + "].name = " + file.name);
      }
    }
  } else {
    // Use DataTransfer interface to access the file(s)
    for (var i = 0; i < ev.dataTransfer.files.length; i++) {
      console.log(
        "... file[" + i + "].name = " + ev.dataTransfer.files[i].name,
      );
    }
  }
}
```

阻止浏览器的默认释放行为
------------

下面的 `dragover` 事件处理函数调用 `preventDefault()` 来关闭浏览器的默认拖动和释放行为。


```js
function dragOverHandler(ev) {
  console.log("File(s) in drop zone");

  // Prevent default behavior (Prevent file from being opened)
  ev.preventDefault();
}
```

参见
--

* HTML Drag and Drop API
* Drag Operations (en-US)
* HTML5 Living Standard: Drag and Drop
HTMLImageElement.referrerPolicy
===============================

**`HTMLImageElement.referrerPolicy`** 反映了 `<img>` 元素的 HTML 属性 `referrerpolicy` 的定义，这个属性定义了`<img>` 元素在获取资源时的引用方式。

语法
--
```

refStr = imgElt.referrerPolicy;
imgElt.referrerPolicy = refStr;
```

### 值

* `"no-referrer"` 表示 HTTP 头部信息将不会发送 `referrer` 。
* `"origin"` 表示 referrer 只包含策略、主机名、端口等页面源的信息。
* `"unsafe-url"` 这意味着引用者将包括源站和路径（但不包括片段、密码或用户名）。这种情况是不安全的，因为它可能会泄漏路径信息，这些信息已被使用 TLS 隐藏到第三方。
示例
--


```js
var img = new Image();
img.src = "img/logo.png";
img.referrerPolicy = "origin";

var div = document.getElementById("divAround");
div.appendChild(img); // Fetch the image using the origin as the referrer
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-img-referrerpolicy |

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

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

参见
--

* `HTMLAnchorElement.referrerPolicy`、`HTMLAreaElement.referrerPolicy` (en-US) 和 `HTMLIFrameElement.referrerPolicy` (en-US)
HTMLImageElement.naturalHeight
==============================

`HTMLImageElement` 接口的 **`naturalHeight`** 属性是一个只读值，它返回图像固有的（自然的）、修正高度后的 CSS 像素。

这是图像在没有限制其高度的情况下绘制的高度；如果你没有为图像指定高度，或者将图像放置在限制或明确指定图像高度的容器中，它将被渲染为如此高。

**备注：** 大多数时候自然高度是服务器发送的图像的实际高度。不过，浏览器可以在将图像推送到渲染器之前对其进行修改。例如，Chrome 会降低低端设备上图像的分辨率。在这种情况下，`naturalHeight` 会将浏览器干预修改的图像高度视为自然高度，并返回该值。

值
-

一个整数值，指示图像的固有高度（以 CSS 像素为单位）。这是在没有为图像建立约束或特定值时自然绘制图像的高度。与 `height` (en-US) 不同，此自然高度已针对显示它的设备的像素密度进行了校正。

如果固有高度不可用——要么是因为图像没有指定固有高度，要么是因为图像数据不可用于获取此信息，“naturalHeight”返回 0。

示例
--

此示例显示图像的自然、密度调整大小以及由页面的 CSS 和其他因素更改的渲染大小。

### HTML


```html
<div class="box">
  <img
 src="/zh-CN/docs/Web/HTML/Element/img/clock-demo-400px.png"
 class="image" />
</div>
<div class="output"></div>
```


HTML 具有一个 400x398 像素的图像，该图像放置在一个 `<div>` 元素中。

### CSS


```css
.box {
  width: 200px;
  height: 200px;
}

.image {
  width: 100%;
}

.output {
  padding-top: 2em;
}
```


在上面的 CSS 中主要需要注意的是，用于绘制图像的容器的样式是 200px 宽，并且图像将被绘制以填充其宽度（100%）。

### JavaScript


```js
let output = document.querySelector(".output");
let image = document.querySelector("img");

window.addEventListener("load", (event) => {
  output.innerHTML +=
    `Natural size: ${image.naturalWidth} x ` +
    `${image.naturalHeight} pixels<br>`;
  output.innerHTML +=
    `Displayed size: ${image.width} x ` + `${image.height} pixels`;
});
```


JavaScript 代码将自然尺寸和显示尺寸转储到带有 `output` 类的 `<div>` 中。这是为了响应窗口的 `load` 事件处理程序，以确保在尝试检查其宽度和高度之前，确保图像可用。

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-img-naturalheight-dev |

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

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

\*\*`Image()`\*\*函数将会创建一个新的`HTMLImageElement`实例。

它的功能等价于 `document.createElement('img')`

语法
--
```

Image(width, height)
```

### 参数

width

图片的宽度 (即 `width` 属性).

height

图片的高度 (即 `height` 属性).

示例
--


```js
var myImage = new Image(100, 200);
myImage.src = "picture.jpg";
document.body.appendChild(myImage);
```


上面的代码相当于在 `<body>`中定义了下面的 HTML:


```html
<img width="100" height="200" src="picture.jpg" />
```


**备注：** 无论构造函数中指定的大小是多少，都会加载整个位图。如果在构造时指定了尺寸信息，那么将会反应在实例的 `HTMLImageElement.width` (en-US) 和 `HTMLImageElement.height` (en-US) 属性上。图像自身的 CSS 像素值将会反应在`HTMLImageElement.naturalWidth` (en-US) 和 `HTMLImageElement.naturalHeight`属性。如果没有指定值，那么两个属性的值相同

规范
--

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

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

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

`HTMLImageElement` 接口的 **`decoding`** 属性用于告诉浏览器使用何种方式解析图像数据。Syntax
------
```

refStr = imgElem.decoding;
imgElem.decoding = refStr;
```

### Values

使用 `DOMString` 表示解码方式。可使用以下值：

* **`sync`**: 同步解码图像，保证与其他内容一起显示。
* **`async`**: 异步解码图像，加快显示其他内容。
* **`auto`**: 默认模式，表示不偏好解码模式。由浏览器决定哪种方式更适合用户。
Usage notes
-----------

`decoding` 属性使你可以控制是否允许浏览器尝试异步加载图像。如果这样做会引起问题，你可指定值为 `sync` 禁止异步加载。异步加载对 `<img>` 元素很有用，对屏幕外的图像对象可能会更有用。

Examples
--------


```js
var img = new Image();
img.decoding = "sync";
img.src = "img/logo.png";
```

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

| Specification |
| --- |
| HTML Standard # dom-img-decoding |

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

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

`HTMLImageElement` 接口的 **`decode()`** 方法返回一个当图片解码后可安全用于附加到 DOM 上时 resolves 的 `Promise` 对象。这可用于在将图片附加到一个 DOM 中的元素（或作为一个新元素加入 DOM 中）之前启动加载，所以在将图像添加到 DOM 时可以立即渲染图像。这反过来，防止了将图像加入 DOM 后图像的加载造成下一帧渲染的延迟。

语法
--
```

var promise = HTMLImageElement.decode();
```

### 参数

无。

### 返回

一个一旦数据准备好可供使用时 resolve 的 promise 对象。

### 异常

`DOMException` 表示解码图像时出错。

使用提示
----

一个 `decode()` 的潜在用例：当在加载一个非常大的图片时（例如，一个在线相册），你可以在加载初期提供一个低分辨率的缩略图，之后通过实例化一个 `HTMLImageElement` 将该图像替换为一个全分辨率图像，设置其 source 为全分辨率图像 URL，使用 `decode()` 获取一旦全分辨率图像准备好被使用时 resolved 的 promise 对象。这时你可以使用当前可用的全分辨率图像替换之前的低分辨率图像。

例子
--

以下例子展示了如何使用 `decode()` 方法来控制一个图像插入 DOM 的时机。若不使用 `Promise` (en-US) 返回方法，你将在图像的 `load` 事件处理函数中将图像加入 DOM 中，通过 `error` 事件处理函数处理错误。


```js
const img = new Image();
img.src = "nebula.jpg";
img
  .decode()
  .then(() => {
    document.body.appendChild(img);
  })
  .catch((encodingError) => {
    // Do something with the error.
  });
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-img-decode-dev |

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

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

`HTMLImageElement` 的 **`loading`** 属性为一个字符串，它的值会提示 用户代理 告诉浏览器不在可视视口内的图片该如何加载。这样一来，通过推迟图片加载仅让其在需要的时候加载而非页面初始载入时立刻加载，优化了页面的载入。

语法
--
```

let imageLoadScheduling = htmlImageElement.loading;
htmlImageElement.loading = eagerOrLazy;
```

### 值

`DOMString` 提示用户代理该如何最佳规划图片加载来优化页面性能。可能的值有：

`eager`

默认行为， `eager` 告诉浏览器当处理 `<img>` 标签时立即加载图片。

`lazy`

告诉用户代理推迟图片加载直到浏览器认为其需要立即加载时才去加载。例如，如果用户正在往下滚动页面，值为 `lazy` 会导致图片仅在马上要出现在 可视视口中时开始加载。

使用说明
----

### load 事件的时机

`load` 事件在文档被完整的处理完成时触发。当图片使用立即加载 (默认值) 时，文档中的所有图片都会在 `load` 事件触发前载入。

当 `loading` 值设为 `lazy` 时，图片不再会在请求，下载，处理的时间内推迟 `load` 事件触发。

`loading` 属性值设为 `lazy` 但是在页面初次加载时就在可视视口内的图片会立即加载但它们也不会推迟 `load` 事件。换句话说，这些图片不会在处理 `<img>` 元素时立即加载，但仍会作为页面初始加载的一部分而加载。他们只是不会影响 `load` 事件。

这表明当 `load` 触发时，可视区域内懒加载的图片可能不可见。

### 防止元素在图片懒加载时出现移位

当一个加载被 `loading` 属性设为 `lazy` 的图片最后加载时，浏览器会根据`<img>` 元素的尺寸和图片自身大小重排文档，更新被图片影响的元素的位置。

为了防止重排发生，你需要使用 `width` 和 `height` 属性明确设置图片大小。通过这样建立固有长宽比，你防止了元素的移位。取决于实际的加载时间和重排，移位造成的最小的影响可能只是使用户困惑和不适，最坏的影响则是导致用户点错目标。

示例
--

下面展示的 `addImageToList()` 函数将一个照片缩略图添加到一个物品列表中，使用懒加载防止请求图片，直到其真正需要显示。


```js
function addImageToList(url) {
  const list = document.querySelector("div.photo-list");

  let newItem = document.createElement("div");
  newItem.className = "photo-item";

  let newImg = document.createElement("img");
  newImg.loading = "lazy";
  newImg.width = 320;
  newImg.height = 240;
  newImg.src = url;

  newItem.appendChild(newImg);
  list.appendChild(newItem);
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-img-loading |

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

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

参见
--

* `<img>` 元素
* MDN 学习专区中的 Web 性能
* MDN web 性能指南中的懒加载
AudioScheduledSourceNode.stop()
===============================

`AudioScheduledSourceNode` 上的`stop()`方法将声音安排在指定的时间停止播放。如果没有指定时间，声音将立即停止播放。

每次在同一个节点上调用 `stop()` 时，指定的时间将替换任何未发生的计划停止时间。如果节点已经停止，则此方法无效。

**备注：** 如果计划的停止时间发生在节点计划的开始时间之前，则节点永远不会开始运行。

语法
--
```

AudioScheduledSourceNode.stop([when]);
```

### 参数

`when` 可选

声音停止播放的时间，单位为秒。这个值在 `AudioContext` 用于其 `currentTime` 属性的同一时间坐标系统中指定。省略这个参数，设置为 0 或者负值都会立即停止播放。

### Return value

`undefined`### Exceptions

`InvalidStateNode`

节点还没有通过调用`start()` (en-US)方法被播放。

`RangeError`

当 `when` 指定为负值时。

Example
-------

This example demonstrates starting an oscillator node, scheduled to begin playing at once and to stop playing in one second. The stop time is determined by taking the audio context's current time from `AudioContext.currentTime` and adding 1 second.


```js
context = new AudioContext();
osc = context.createOscillator();
osc.connect(context.destination);

/\* Let's play a sine wave for one second. \*/

osc.start();
osc.stop(context.currentTime + 1);
```

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

| Specification |
| --- |
| Web Audio API # dom-audioscheduledsourcenode-stop |

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

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

See also
--------

* Using the Web Audio API (en-US)
* `start()` (en-US)
* `AudioScheduledSourceNode`
* `AudioBufferSourceNode`
* `ConstantSourceNode` (en-US)
* `OscillatorNode`