CanvasRenderingContext2D.strokeStyle - Web API 接口参考

CanvasRenderingContext2D.strokeStyle
====================================

**`CanvasRenderingContext2D.strokeStyle`** 是 Canvas 2D API 描述画笔（绘制图形）颜色或者样式的属性。默认值是 `#000` (black)。

参见 Canvas Tutorial 中的 Applying styles and color 章节。

语法
--
```

ctx.strokeStyle = color;
ctx.strokeStyle = gradient;
ctx.strokeStyle = pattern;
```

### 选项

`color`

`DOMString` 字符串，可以转换成 CSS `<color>` 值。

`gradient`

`CanvasGradient` 对象（线性渐变或放射性渐变）。

`pattern`

`CanvasPattern` 对象（可重复的图片）。

示例
--

### 更改形状的轮廓线颜色

这是一段简单的代码片段，使用 `strokeStyle` 属性设置不同的颜色。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

ctx.strokeStyle = "blue";
ctx.strokeRect(10, 10, 100, 100);
```

#### 结果

### 使用循环创建多种轮廓线颜色

这个例子使用 `strokeStyle` 属性改变图形轮廓线的颜色。我们使用 `arc()` 绘制圆形来代替正方形。
```

<canvas id="canvas" width="150" height="150"></canvas>
```

```js
const ctx = document.getElementById("canvas").getContext("2d");

for (let i = 0; i < 6; i++) {
  for (let j = 0; j < 6; j++) {
    ctx.strokeStyle = `rgb(
 0,
 ${Math.floor(255 - 42.5 \* i)},
 ${Math.floor(255 - 42.5 \* j)})`;
    ctx.beginPath();
    ctx.arc(12.5 + j \* 25, 12.5 + i \* 25, 10, 0, Math.PI \* 2, true);
    ctx.stroke();
  }
}
```

结果如下显示：

| Screenshot | Live sample |
| --- | --- |
|  |  |

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-strokestyle-dev |

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

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

### WebKit/Blink-specific 注解

* 在基于 WebKit- 和 Blink- 的浏览器中，除了此属性外，还实现了一个不标准的并且不赞成使用的方法 `ctx.setStrokeColor()` 。

```js
setStrokeColor(color, optional alpha);
setStrokeColor(grayLevel, optional alpha);
setStrokeColor(r, g, b, a);
setStrokeColor(c, m, y, k, a);
```

参见
--

* 接口定义， `CanvasRenderingContext2D`
* `CanvasGradient`
* `CanvasPattern`


CanvasRenderingContext2D.font - Web API 接口参考

CanvasRenderingContext2D.font
=============================

**`CanvasRenderingContext2D.font`** 是 Canvas 2D API 描述绘制文字时，当前字体样式的属性。使用和 CSS font 规范相同的字符串值。

语法
--
```

ctx.font = value;
```

### 选项

`value`

符合 CSS `font` 语法的`DOMString` 字符串。默认字体是 10px sans-serif。

示例
--

### 使用自定义字体

这个例子使用 `font` 属性设置了不同的字体大小和字体种类。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

ctx.font = "bold 48px serif";
ctx.strokeText("Hello world", 50, 100);
```

#### 结果

### 使用 CSS 字体加载 API 加载字体

借助`FontFace` API 的帮助，你可以在画布中使用字体之前显式加载字体。
```

let f = new FontFace('test', 'url(x)');

f.load().then(function() {
  // Ready to use the font in a canvas context
});
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-font-dev |

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

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

### Gecko-specific 注解

* 基于 Gecko 的浏览器，例如 Firefox，实现了一个非标准的并且不赞成使用的属性 `ctx.mozTextStyle` 。不要使用此属性。
* 在 Gecko 中，当将系统字体设置为 canvas 2D 上下文的`font`（例如菜单）的值时，获取用于无法返回期望字体的字体值（不返回任何内容）。这已在 Firefox 57（Firefox bug 1374885）中发布的 Firefox 的Quantum/Stylo并行 CSS 引擎中修复。
参见
--

* 接口定义，`CanvasRenderingContext2D`


CanvasRenderingContext2D.lineJoin - Web API 接口参考

CanvasRenderingContext2D.lineJoin
=================================

**`CanvasRenderingContext2D.lineJoin`** 是 Canvas 2D API 用来设置 2 个长度不为 0 的相连部分（线段、圆弧、曲线）如何连接在一起的属性（长度为 0 的变形部分，其指定的末端和控制点在同一位置，会被忽略）。

参见 Canvas Tutorial 中的 Applying styles and color 章节。

语法
--
```

ctx.lineJoin = "bevel";
ctx.lineJoin = "round";
ctx.lineJoin = "miter";
```

### 选项

此属性有 3 个值： `round`, `bevel` and `miter`。默认值是 `miter`。注意：如果 2 个相连部分在同一方向，那么 lineJoin 不会产生任何效果，因为在那种情况下不会出现连接区域。

![](/zh-CN/docs/Web/API/CanvasRenderingContext2D/lineJoin/canvas_linejoin.png)

`round`

通过填充一个额外的，圆心在相连部分末端的扇形，绘制拐角的形状。圆角的半径是线段的宽度。

`bevel`

在相连部分的末端填充一个额外的以三角形为底的区域，每个部分都有各自独立的矩形拐角。

`miter`

通过延伸相连部分的外边缘，使其相交于一点，形成一个额外的菱形区域。这个设置可以通过 `miterLimit` 属性看到效果。

示例
--

### 改变路径中的相连部分

这是一段使用 `lineJoin` 属性的简单的代码片段。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

ctx.lineWidth = 20;
ctx.lineJoin = "round";
ctx.beginPath();
ctx.moveTo(20, 20);
ctx.lineTo(190, 100);
ctx.lineTo(280, 20);
ctx.lineTo(280, 150);
ctx.stroke();
```

#### 结果

### 相连部分对比

下面的例子绘制了 3 条不同的路径，演示 `lineJoin` 属性 3 种不同的设置。
```

<canvas id="canvas" width="150" height="150"></canvas>
```

```js
const ctx = document.getElementById("canvas").getContext("2d");
ctx.lineWidth = 10;

["round", "bevel", "miter"].forEach((join, i) => {
  ctx.lineJoin = join;
  ctx.beginPath();
  ctx.moveTo(-5, 5 + i \* 40);
  ctx.lineTo(35, 45 + i \* 40);
  ctx.lineTo(75, 5 + i \* 40);
  ctx.lineTo(115, 45 + i \* 40);
  ctx.lineTo(155, 5 + i \* 40);
  ctx.stroke();
});
```

| Screenshot | Live sample |
| --- | --- |
|  |  |

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-linejoin-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`
* `CanvasRenderingContext2D.lineCap`
* `CanvasRenderingContext2D.lineWidth`


CanvasRenderingContext2D.drawImage() - Web API 接口参考

CanvasRenderingContext2D.drawImage()
====================================

Canvas 2D API 中的 **`CanvasRenderingContext2D.drawImage()`** 方法提供了多种在画布（Canvas）上绘制图像的方式。

语法
--

```js
drawImage(image, dx, dy);
drawImage(image, dx, dy, dWidth, dHeight);
drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight);
```

![drawImage](/zh-CN/docs/Web/API/CanvasRenderingContext2D/drawImage/canvas_drawimage.jpg)

### 参数

`image`

 绘制到上下文的元素。允许任何的画布图像源，例如：`HTMLImageElement`、`SVGImageElement` (en-US)、`HTMLVideoElement`、`HTMLCanvasElement`、`ImageBitmap`、`OffscreenCanvas`
 或 `VideoFrame` (en-US)。

`sx` 可选

需要绘制到目标上下文中的，`image` 的矩形（裁剪）选择框的左上角 X 轴坐标。可以使用 3 参数或 5 参数语法来省略这个参数。

`sy` 可选

需要绘制到目标上下文中的，`image` 的矩形（裁剪）选择框的左上角 Y 轴坐标。可以使用 3 参数或 5 参数语法来省略这个参数。

`sWidth` 可选

需要绘制到目标上下文中的，`image` 的矩形（裁剪）选择框的宽度。如果不说明，整个矩形（裁剪）从坐标的 `sx` 和 `sy` 开始，到 `image` 的右下角结束。可以使用 3 参数或 5 参数语法来省略这个参数。使用负值将翻转这个图像。

`sHeight` 可选

需要绘制到目标上下文中的，`image`的矩形（裁剪）选择框的高度。使用负值将翻转这个图像。

`dx`

`image` 的左上角在目标画布上 X 轴坐标。

`dy`

`image` 的左上角在目标画布上 Y 轴坐标。

`dWidth`

`image` 在目标画布上绘制的宽度。允许对绘制的 `image` 进行缩放。如果不说明，在绘制时 `image` 宽度不会缩放。注意，这个参数不包含在 3 参数语法中。

`dHeight`

`image` 在目标画布上绘制的高度。允许对绘制的 `image` 进行缩放。如果不说明，在绘制时 `image` 高度不会缩放。注意，这个参数不包含在 3 参数语法中。

### 返回值

无（`undefined`）。

### 异常

`InvalidStateError` `DOMException`

当图像没有数据或者画布或源矩形宽度/高度为零时抛出该异常。

`TypeMismatchError` `DOMException`

当将 `null` 或 `undefined` 值作为图像的参数传入时抛出该异常。

示例
--

### 在画布上绘制图像

此示例在画布中使用 `drawImage()` 方法绘制一张图像。

#### HTML

```html
<canvas id="canvas"></canvas>
<div style="display:none;">
  <img id="source" src="rhino.jpg" width="300" height="227" />
</div>
```

#### JavaScript

原图像从坐标 (33,71) 处截取一个宽度为 104 高度为 124 的图像。并将其绘制到画布的 (21, 20) 坐标处，并将其缩放为宽 87、高 104 的图像。

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
const image = document.getElementById("source");

image.addEventListener("load", (e) => {
  ctx.drawImage(image, 33, 71, 104, 124, 21, 20, 87, 104);
});
```

#### 结果

### 理解源元素大小

`drawImage()` 方法在绘制时使用源元素的*固有尺寸*（以 CSS 像素为单位）。

例如，如果加载图像并在其构造函数中指定可选的大小参数，则必须使用所创建实例的 `naturalWidth` 和 `naturalHeight` 属性来正确计算裁剪和缩放区域等内容，而不是 `element.width` 和 `element.height`。如果元素是 `<video>` 元素，则 `videoWidth` 和 `videoHeight` 也是如此，依此类推。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

const image = new Image(60, 45); // Using optional size for image
image.onload = drawImageActualSize; // Draw when image has loaded

// Load an image of intrinsic size 300x227 in CSS pixels
image.src = "rhino.jpg";

function drawImageActualSize() {
  // Use the intrinsic size of image in CSS pixels for the canvas element
  canvas.width = this.naturalWidth;
  canvas.height = this.naturalHeight;

  // Will draw the image as 300x227, ignoring the custom size of 60x45
  // given in the constructor
  ctx.drawImage(this, 0, 0);

  // To use the custom size we'll have to specify the scale parameters
  // using the element's width and height properties - lets draw one
  // on top in the corner:
  ctx.drawImage(this, 0, 0, this.width, this.height);
}
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-drawimage-dev |

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

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

备注
--

* 当 `drawImage()` 需要在 `HTMLVideoElement` 工作时，仅当 `HTMLMediaElement.readyState` 大于 1 时 `drawImage()` 才能正常工作。
* 在绘制，裁剪和/或缩放时，`drawImage()` 将始终使用源元素的固有尺寸（以 CSS 像素为单位）。
* 在某些旧版本浏览器中，`drawImage()` 将忽略图像中的所有 EXIF 元数据，包括方向。此行为在 iOS 设备上尤其麻烦。你应该自己检测方向并使用 `rotate()` 使其正确。
参见
--

* 定义该方法的接口：`CanvasRenderingContext2D`


CanvasRenderingContext2D.lineDashOffset - Web API 接口参考

CanvasRenderingContext2D.lineDashOffset
=======================================

**`CanvasRenderingContext2D.lineDashOffset`** 是 Canvas 2D API 设置虚线偏移量的属性，例如可以实现“蚂蚁线“的效果。

语法
--
```

ctx.lineDashOffset = value;
```

`value`

偏移量是 float 精度的数字。初始值为 `0.0`。

示例
--

### 偏移虚线

这是一段简单的代码片段，使用 `lineDashOffset` 属性绘制虚线。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

ctx.setLineDash([4, 16]);

// Dashed line with no offset
ctx.beginPath();
ctx.moveTo(0, 50);
ctx.lineTo(300, 50);
ctx.stroke();

// Dashed line with offset of 4
ctx.beginPath();
ctx.strokeStyle = "red";
ctx.lineDashOffset = 4;
ctx.moveTo(0, 100);
ctx.lineTo(300, 100);
ctx.stroke();
```

#### 结果

带有偏移的虚线用红色绘制。

### 蚂蚁线

“蚂蚁线”效果是一种动画技巧，经常出现在计算机绘图程序的套索工具中。它能帮助用户根据图片背景动态变化的边界来区分选择的边界。
```

<canvas id="canvas" class="playable-canvas"></canvas>
```

```js
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");
var offset = 0;

function draw() {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.setLineDash([4, 2]);
  ctx.lineDashOffset = -offset;
  ctx.strokeRect(10, 10, 100, 100);
}

function march() {
  offset++;
  if (offset > 16) {
    offset = 0;
  }
  draw();
  setTimeout(march, 20);
}

march();
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-linedashoffset-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`
* `CanvasRenderingContext2D.getLineDash()`
* `CanvasRenderingContext2D.setLineDash()`
* Applying styles and color


CanvasRenderingContext2D.bezierCurveTo() - Web API 接口参考

CanvasRenderingContext2D.bezierCurveTo()
========================================

**`CanvasRenderingContext2D.bezierCurveTo()`** 是 Canvas 2D API 绘制三次贝赛尔曲线路径的方法。该方法需要三个点。第一、第二个点是控制点，第三个点是结束点。起始点是当前路径的最后一个点，绘制贝赛尔曲线前，可以通过调用 `moveTo()` 进行修改。

语法
--
```

void ctx.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, x, y);
```

### 参数

`cp1x`

第一个控制点的 x 轴坐标。

`cp1y`

第一个控制点的 y 轴坐标。

`cp2x`

第二个控制点的 x 轴坐标。

`cp2y`

第二个控制点的 y 轴坐标。

`x`

结束点的 x 轴坐标。

`y`

结束点的 y 轴坐标。

示例
--

### 使用 `bezierCurveTo` 方法

这是一段绘制贝赛尔曲线的简单的代码片段。控制点是红色的，开始和结束点是蓝色的。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

ctx.beginPath();
ctx.moveTo(50, 20);
ctx.bezierCurveTo(230, 30, 150, 60, 50, 100);
ctx.stroke();

ctx.fillStyle = "blue";
// start point
ctx.fillRect(50, 20, 10, 10);
// end point
ctx.fillRect(50, 100, 10, 10);

ctx.fillStyle = "red";
// control point one
ctx.fillRect(230, 30, 10, 10);
// control point two
ctx.fillRect(150, 70, 10, 10);
```

### 尝试 `bezierCurveTo` 参数

修改下面的代码并在线查看 canvas 的变化：
```

<canvas id="canvas" width="400" height="200" class="playable-canvas"></canvas>
<div class="playable-buttons">
  <input id="edit" type="button" value="Edit" />
  <input id="reset" type="button" value="Reset" />
</div>
<textarea id="code" class="playable-code">
ctx.beginPath();
ctx.bezierCurveTo(50, 100, 180, 10, 20, 10);
ctx.stroke();</textarea
>
```

```
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");
var textarea = document.getElementById("code");
var reset = document.getElementById("reset");
var edit = document.getElementById("edit");
var code = textarea.value;

function drawCanvas() {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  eval(textarea.value);
}

reset.addEventListener("click", function () {
  textarea.value = code;
  drawCanvas();
});

edit.addEventListener("click", function () {
  textarea.focus();
});

textarea.addEventListener("input", drawCanvas);
window.addEventListener("load", drawCanvas);
```

规范描述
----

| Specification |
| --- |
| HTML Standard # dom-context-2d-beziercurveto-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`
* 维基百科关于贝赛尔曲线。


CanvasRenderingContext2D.isPointInStroke() - Web API 接口参考

CanvasRenderingContext2D.isPointInStroke()
==========================================

**`CanvasRenderingContext2D.isPointInStroke()`** 是 Canvas 2D API 用于检测某点是否在路径的描边线上的方法。

语法
--
```

boolean ctx.isPointInStroke(x, y);
boolean ctx.isPointInStroke(path, x, y);
```

### 参数

x

检测点的 X 坐标。

y

检测点的 Y 坐标。

`path`

`Path2D` 路径。

### 返回值

`Boolean`

一个布尔值，当这个点在路径的描边线上，则返回 true，否则返回 false。

示例
--

### 检查当前路径中的点

这只是一个使用 **`isPointInStroke`** 方法的简单的代码片段，用于检测一个点是否在路径的描边线上。

#### HTML

```html
<canvas id="canvas"></canvas>
<p>In stroke: <code id="result">false</code></p>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
const result = document.getElementById("result");

ctx.rect(10, 10, 100, 100);
ctx.stroke();
result.innerText = ctx.isPointInStroke(50, 10);
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-ispointinstroke-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`.


CanvasRenderingContext2D.putImageData() - Web API 接口参考

CanvasRenderingContext2D.putImageData()
=======================================

**`CanvasRenderingContext2D.putImageData()`** 是 Canvas 2D API 将数据从已有的 `ImageData` 对象绘制到位图的方法。如果提供了一个绘制过的矩形，则只绘制该矩形的像素。此方法不受画布转换矩阵的影响。

语法
--
```

void ctx.putImageData(imagedata, dx, dy);
void ctx.putImageData(imagedata, dx, dy, dirtyX, dirtyY, dirtyWidth, dirtyHeight);
```

### 参数

`imageData`

`ImageData`，包含像素值的数组对象。

`dx`

源图像数据在目标画布中的位置偏移量（x 轴方向的偏移量）。

`dy`

源图像数据在目标画布中的位置偏移量（y 轴方向的偏移量）。

`dirtyX` 可选

在源图像数据中，矩形区域左上角的位置。默认是整个图像数据的左上角（x 坐标）。

`dirtyY` 可选

在源图像数据中，矩形区域左上角的位置。默认是整个图像数据的左上角（y 坐标）。

`dirtyWidth` 可选

在源图像数据中，矩形区域的宽度。默认是图像数据的宽度。

`dirtyHeight` 可选

在源图像数据中，矩形区域的高度。默认是图像数据的高度。

### 抛出错误

`NotSupportedError`

如果任何一个变量被设置成无穷大，则会抛出此错误。

`InvalidStateError`

如果过图像数据对象的数据被分离，会抛出此错误。

示例
--

### 理解 `putImageData`

通过`CanvasRenderingContext2D.fillRect()`方法实现，更好地理解 putImageData 的执行算法。获取更多信息，参见 使用 Canvas 控制像素 和 `ImageData` 对象。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

function putImageData(
  ctx,
 imageData,
 dx,
 dy,
 dirtyX,
 dirtyY,
 dirtyWidth,
 dirtyHeight,
) {
  const data = imageData.data;
  const height = imageData.height;
  const width = imageData.width;
  dirtyX = dirtyX || 0;
  dirtyY = dirtyY || 0;
  dirtyWidth = dirtyWidth !== undefined ? dirtyWidth : width;
  dirtyHeight = dirtyHeight !== undefined ? dirtyHeight : height;
  const limitBottom = dirtyY + dirtyHeight;
  const limitRight = dirtyX + dirtyWidth;
  for (let y = dirtyY; y < limitBottom; y++) {
    for (let x = dirtyX; x < limitRight; x++) {
      const pos = y \* width + x;
      ctx.fillStyle = `rgba(${data[pos \* 4 + 0]}, ${data[pos \* 4 + 1]}, ${
 data[pos \* 4 + 2]
 }, ${data[pos \* 4 + 3] / 255})`;
      ctx.fillRect(x + dx, y + dy, 1, 1);
    }
  }
}

// Draw content onto the canvas
ctx.fillRect(0, 0, 100, 100);
// Create an ImageData object from it
const imagedata = ctx.getImageData(0, 0, 100, 100);
// use the putImageData function that illustrates how putImageData works
putImageData(ctx, imagedata, 150, 0, 50, 50, 25, 25);
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-putimagedata-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`.
* `ImageData`
* Pixel manipulation with canvas


CanvasRenderingContext2D.arc() - Web API 接口参考

CanvasRenderingContext2D.arc()
==============================

**`CanvasRenderingContext2D.arc()`** 是 Canvas 2D API 绘制圆弧路径的方法。圆弧路径的圆心在 *(x, y)* 位置，半径为 *r*，根据*anticlockwise* （默认为顺时针）指定的方向从 *startAngle* 开始绘制，到 *endAngle* 结束。

语法
--
```

void ctx.arc(x, y, radius, startAngle, endAngle, anticlockwise);
```

### Parameters

`x`

圆弧中心（圆心）的 x 轴坐标。

`y`

圆弧中心（圆心）的 y 轴坐标。

`radius`

圆弧的半径。

`startAngle`

圆弧的起始点，x 轴方向开始计算，单位以弧度表示。

`endAngle`

圆弧的终点，单位以弧度表示。

`anticlockwise` 可选

可选的`Boolean`值，如果为 `true`，逆时针绘制圆弧，反之，顺时针绘制。

示例
--

### 绘制一个完整的圆

这是一段绘制圆的简单的代码片段。

#### HTML

```html
<canvas></canvas>
```

#### JavaScript

```js
const canvas = document.querySelector("canvas");
const ctx = canvas.getContext("2d");

ctx.beginPath();
ctx.arc(100, 75, 50, 0, 2 \* Math.PI);
ctx.stroke();
```

#### 结果

### 不同的形状演示

在此例中，使用 arc() 尽可能地绘制不同的形状。
```

<canvas id="canvas" width="150" height="200"></canvas>
```

```js
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

// Draw shapes
for (i = 0; i < 4; i++) {
  for (j = 0; j < 3; j++) {
    ctx.beginPath();
    var x = 25 + j \* 50; // x coordinate
    var y = 25 + i \* 50; // y coordinate
    var radius = 20; // Arc radius
    var startAngle = 0; // Starting point on circle
    var endAngle = Math.PI + (Math.PI \* j) / 2; // End point on circle
    var clockwise = i % 2 == 0 ? false : true; // clockwise or anticlockwise

    ctx.arc(x, y, radius, startAngle, endAngle, clockwise);

    if (i > 1) {
      ctx.fill();
    } else {
      ctx.stroke();
    }
  }
}
```

| Screenshot | Live sample |
| --- | --- |
|  |  |

规范描述
----

| Specification |
| --- |
| HTML Standard # dom-context-2d-arc-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`


CanvasRenderingContext2D.clip() - Web API 接口参考

CanvasRenderingContext2D.clip()
===============================

**`CanvasRenderingContext2D.clip()`** 是 Canvas 2D API 将当前创建的路径设置为当前剪切路径的方法。

语法
--
```

void ctx.clip();
void ctx.clip(fillRule);
void ctx.clip(path, fillRule);
```

### 参数

![](/zh-CN/docs/Web/API/CanvasRenderingContext2D/clip/canvas_clipping_path.png)

`fillRule`

 这个算法判断一个点是在路径内还是在路径外。
 允许的值：

`nonzero`

非零环绕原则，默认的原则。

`evenodd`

奇偶环绕原则。

`path`

需要剪切的 `Path2D` 路径。

示例
--

### 一个简单的裁剪区域

这是一段简单的代码片段，使用 `clip` 方法创建剪切区域。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

// Create circular clipping region
ctx.beginPath();
ctx.arc(100, 75, 50, 0, Math.PI \* 2);
ctx.clip();

// Draw stuff that gets clipped
ctx.fillStyle = "blue";
ctx.fillRect(0, 0, canvas.width, canvas.height);
ctx.fillStyle = "orange";
ctx.fillRect(0, 0, 100, 100);
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-clip-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`.


CanvasRenderingContext2D.filter - Web API 接口参考

CanvasRenderingContext2D.filter
===============================

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

**`CanvasRenderingContext2D.filter`** 是 Canvas 2D API 提供模糊、灰度等过滤效果的属性。它类似于 CSS `filter` 属性，并且接受相同的函数。

语法
--
```

ctx.filter = "<filter-function1> [<filter-function2] [<filter-functionN]";
ctx.filter = "none";
```

### Filter 函数

filter 属性接受`DOMString`字符串，可以包含一个或多个 filter 函数。

`url(<url>)`

`url()` 函数接受一个描述 SVG 过滤器的 XML 文件的位置，并且可以包含一个针对特殊过滤元素的锚点。

`blur(<length>)`

length：CSS 长度。给绘图提供一个高斯模糊。

`brightness(<percentage>)`

Percentage：百分比。给绘图提供一个线性乘法，调节亮度的高低。

`contrast(<percentage>)`

Percentage：百分比。调节图像的对比度。当数值为 `0%` 时，图像会完全变黑。当数值为 `100%` 时，图像没有任何变化。

`drop-shadow(<offset-x>, <offset-y>, <blur-radius>, <spread-radius>, <color>)`

给绘图提供阴影。阴影事实上是在图像下面呈现出模糊的，通过对图像的透明遮罩进行偏移绘制出一种特殊的颜色，组合而成的效果。这个函数接受 5 个参数：

* `<offset-x>`: 查看 `<length>` 允许的单位。描述阴影的水平距离。
* `<offset-y>`: 查看 `<length>` 允许的单位。描述阴影的垂直距离。
* `<blur-radius>`: 数值越大，模糊就越大，从而使阴影范围变得更大颜色变得更浅。不允许为负数。
* `<spread-radius>`: 正数会使阴影扩张变大，负数会使阴影收缩。
* `<color>`: 查看 `<color>` 允许的关键字和标识符。

`grayscale(<percentage>)`

Percentage：百分比。将图像转换成灰色的图片。当值为 100% 时，图像会完全变成灰色。当值为 0% 时，图像没有任何变化。

`hue-rotate(<degree>)`

Degree：度数。对图像进行色彩旋转的处理。当值为 0 度时，图像没有任何变化。

`invert(<percentage>)`

Percentage：百分比。反色图像（呈现出照片底片的效果）。当值为 100% 时，图像会完全反色处理。当值为 0% 时，图像没有任何变化。

`opacity(<percentage>)`

Percentage：百分比。对图像进行透明度的处理。当值为 0% 时，图像完全透明。当值为 100% 时，图像没有任何变化。

`saturate(<percentage>)`

对图像进行饱和度的处理。当值为 0% 时，图像完全不饱和。当值为 100% 时，图像没有任何变化。

`sepia(<percentage>)`

对图像进行深褐色处理（怀旧风格）。当值为 100% 时，图像完全变成深褐色。当值为 0% 时，图像没有任何变化。

`none`

没有使用 filter。

示例
--

### 应用模糊

这是一段使用 `filter` 属性的简单的代码片段。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

ctx.filter = "blur(4px)";
ctx.font = "48px serif";
ctx.fillText("Hello world", 50, 100);
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-filter-dev |

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

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

参见
--

* 接口定义，`CanvasRenderingContext2D`
* CSS `filter`


CanvasRenderingContext2D.canvas - Web API 接口参考

CanvasRenderingContext2D.canvas
===============================

**`CanvasRenderingContext2D.canvas`** 属性是 Canvas API 的一部分，是对与给定上下文关联的`HTMLCanvasElement`对象的只读引用。如果没有 `<canvas>` 元素与之对应，对象值为`null` 。

语法
--
```

ctx.canvas;
```

示例
--

给出 `<canvas>` 元素：

```html
<canvas id="canvas"></canvas>
```

你可以通过 CanvasRenderingContext2D 调用内部的 canvas 属性，获取 canvas 的一个反向引用：

```js
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");
ctx.canvas; // HTMLCanvasElement
```

规范描述
----

| Specification |
| --- |
| HTML Standard # dom-context-2d-canvas-dev |

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

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

参见
--

* `CanvasRenderingContext2D` 接口
* Canvas API


CanvasRenderingContext2D.clearRect() - Web API 接口参考

CanvasRenderingContext2D.clearRect()
====================================

**`CanvasRenderingContext2D.clearRect()`** 是 Canvas 2D API 的方法，这个方法通过把像素设置为透明以达到擦除一个矩形区域的目的。

**备注：** 如果没有依照 绘制路径 的步骤，使用 `clearRect()` 会导致意想之外的结果。请确保在调用 `clearRect()`之后绘制新内容前调用`beginPath()` 。

语法
--
```

void ctx.clearRect(x, y, width, height);
```

`clearRect()` 方法在一个矩形区域内设置所有像素都是透明的 (`rgba(0,0,0,0)`)。这个矩形范围的左上角在 `(x, y)`，宽度和高度分别由 `width` 和`height`确定。

### 参数

`x`

矩形起点的 x 轴坐标。

`y`

矩形起点的 y 轴坐标。

`width`

矩形的宽度。

`height`

矩形的高度。

示例
--

### 清除整个画布

这段代码清除整个画布。这段代码通常在动画的每一帧开始被执行。清除的范围涵覆盖了整个 `<canvas>` 元素。

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
ctx.clearRect(0, 0, canvas.width, canvas.height);
```

### 清除一部分画布

这仅是一段简单地使用 `clearRect` 方法的代码片段。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

下面代码中被清除的区域是一个矩形，它的左上点坐标在 (10, 10)，宽度和高度分别是 120 和 100 像素。

```js
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

// 绘制黄色背景
ctx.beginPath();
ctx.fillStyle = "#ff6";
ctx.fillRect(0, 0, canvas.width, canvas.height);

// 绘制蓝色三角形
ctx.beginPath();
ctx.fillStyle = "blue";
ctx.moveTo(20, 20);
ctx.lineTo(180, 20);
ctx.lineTo(130, 130);
ctx.closePath();
ctx.fill();

// 清除一部分画布
ctx.clearRect(10, 10, 120, 100);
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-clearrect-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`
* `CanvasRenderingContext2D.fillRect()`
* `CanvasRenderingContext2D.strokeRect()`


CanvasRenderingContext2D.strokeRect() - Web API 接口参考

CanvasRenderingContext2D.strokeRect()
=====================================

**`CanvasRenderingContext2D.strokeRect()`** 是 Canvas 2D API 在 canvas 中，使用当前的绘画样式，描绘一个起点在 *(x, y)*、宽度为 *w*、高度为 *h* 的矩形的方法。

此方法直接绘制到画布而不修改当前路径，因此任何后续`fill()` 或`stroke()`调用对它没有影响。

语法
--
```

void ctx.strokeRect(x, y, width, height);
```

`strokeRect()`方法绘制一个描边矩形，其起点为`(x, y)` ，其大小由宽度和高度指定。

### 参数

`x`

矩形起点的 x 轴坐标。

`y`

矩形起点的 y 轴坐标。

`width`

矩形的宽度。正值在右侧，负值在左侧。

`height`

矩形的高度。正值在下，负值在上。

示例
--

### 一个简单的填充矩形

这是一段使用 `strokeRect` 方法的简单的代码片段。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

矩形的左上角是（20,10）。它的宽度为 160，高度为 100。

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
ctx.strokeStyle = "green";
ctx.strokeRect(20, 10, 160, 100);
```

#### 结果

### 应用多种上下文设置

此示例绘制一个带有阴影和粗斜面轮廓的矩形。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
ctx.shadowColor = "#d53";
ctx.shadowBlur = 20;
ctx.lineJoin = "bevel";
ctx.lineWidth = 15;
ctx.strokeStyle = "#38f";
ctx.strokeRect(30, 30, 160, 90);
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-strokerect-dev |

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

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

参见
--

* 接口定义，`CanvasRenderingContext2D`
* `CanvasRenderingContext2D.strokeStyle`
* `CanvasRenderingContext2D.clearRect()`
* `CanvasRenderingContext2D.fillRect()`


CanvasRenderingContext2D.scale() - Web API 接口参考

CanvasRenderingContext2D.scale()
================================

**`CanvasRenderingContext2D.scale()`** 是 Canvas 2D API 根据 x 水平方向和 y 垂直方向，为 canvas 单位添加缩放变换的方法。

默认的，在 canvas 中一个单位实际上就是一个像素。例如，如果我们将 0.5 作为缩放因子，最终的单位会变成 0.5 像素，并且形状的尺寸会变成原来的一半。相似的方式，我们将 2.0 作为缩放因子，将会增大单位尺寸变成两个像素。形状的尺寸将会变成原来的两倍。

语法
--
```

void ctx.scale(x, y);
```

### 参数

`x`

水平方向的缩放因子。A negative value flips pixels across the vertical axis. A value of `1` results in no horizontal scaling.

y

垂直方向的缩放因子。A negative value flips pixels across the horizontal axis. A value of `1` results in no vertical scaling.

示例
--

### 使用 `scale` 方法

这是一段使用 `scale` 方法的简单的代码片段。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

The rectangle has a specified width of 8 and a height of 20. The transformation matrix scales it by 9x horizontally and by 3x vertically. Thus, its final size is a width of 72 and a height of 60.

Notice that its position on the canvas also changes. Since its specified corner is (10, 10), its rendered corner becomes (90, 30).

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

// Scaled rectangle
ctx.scale(9, 3);
ctx.fillStyle = "red";
ctx.fillRect(10, 10, 8, 20);

// Reset current transformation matrix to the identity matrix
ctx.setTransform(1, 0, 0, 1, 0, 0);

// Non-scaled rectangle
ctx.fillStyle = "gray";
ctx.fillRect(10, 10, 8, 20);
```

#### 结果

The scaled rectangle is red, and the non-scaled rectangle is gray.

### 使用 scale 水平或竖直翻转

你可以使用 `ctx.scale(-1, 1)` 水平翻转上下文，使用 `ctx.scale(1, -1)` 垂直翻转上下文。在这个例子中，"Hello world!" 被水平翻转。

Note that the call to `fillText()` specifies a negative x coordinate. This is to adjust for the negative scaling factor: `-280 * -1` becomes `280`, and text is drawn leftwards from that point.

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

ctx.scale(-1, 1);
ctx.font = "48px serif";
ctx.fillText("Hello world!", -280, 90);
ctx.setTransform(1, 0, 0, 1, 0, 0);
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-scale-dev |

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

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

参见
--

* 接口定义，`CanvasRenderingContext2D`


CanvasRenderingContext2D.measureText() - Web API 接口参考

CanvasRenderingContext2D.measureText()
======================================

**`CanvasRenderingContext2D.measureText()`** 方法返回一个关于被测量文本`TextMetrics` 对象包含的信息（例如它的宽度）。

语法
--
```

ctx.measureText(text);
```

### 参数

text

需要测量的`String` 。

### 返回值

`TextMetrics` 对象。

示例
--

给出 `<canvas>` 元素：

```html
<canvas id="canvas"></canvas>
```

使用下面的代码，你能得到 `TextMetrics` 对象：

```js
var canvas = document.getElementById("canvas");
var ctx = canvas.getContext("2d");

var text = ctx.measureText("foo"); // TextMetrics object
text.width; // 16;
```

规范描述
----

| Specification |
| --- |
| HTML Standard # dom-context-2d-measuretext-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`.
* `TextMetrics`


CanvasRenderingContext2D.textAlign - Web API 接口参考

CanvasRenderingContext2D.textAlign
==================================

**`CanvasRenderingContext2D.textAlign`** 是 Canvas 2D API 描述绘制文本时，文本的对齐方式的属性。注意，该对齐是基于 CanvasRenderingContext2D.fillText 方法的 x 的值。所以如果 textAlign="center"，那么该文本将画在 x-50%\*width。

>
> 译者注：这里的 textAlign="center"比较特殊。textAlign 的值为 center 时候文本的居中是基于你在 fillText 的时候所给的 x 的值，也就是说文本一半在 x 的左边，一半在 x 的右边（可以理解为计算 x 的位置时从默认文字的左端，改为文字的中心，因此你只需要考虑 x 的位置即可）。所以，如果你想让文本在整个 canvas 居中，就需要将 fillText 的 x 值设置成 canvas 的宽度的一半。
>
>
>

语法
--
```

ctx.textAlign = "left" || "right" || "center" || "start" || "end";
```

### 选项

有效值：

left

文本左对齐。

right

文本右对齐。

center

文本居中对齐。

start

文本对齐界线开始的地方（左对齐指本地从左向右，右对齐指本地从右向左）。

end

文本对齐界线结束的地方（左对齐指本地从左向右，右对齐指本地从右向左）。

默认值是 `start`。

>
> 译者注：`direction` 属性会对此属性产生影响。如果 `direction` 属性设置为 `ltr`，则 left 和 `start` 的效果相同，`right` 和 end 的效果相同；如果 direction 属性设置为 `rtl`，则 `left` 和 `end` 的效果相同，`right` 和 `start` 的效果相同。
>
>
>

示例
--

### 简单文本对齐

这是一段简单的代码片段，使用 `textAlign` 属性设置文本的不同对齐方式。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
canvas.width = 350;
const ctx = canvas.getContext("2d");
const x = canvas.width / 2;

ctx.beginPath();
ctx.moveTo(x, 0);
ctx.lineTo(x, canvas.height);
ctx.stroke();

ctx.font = "30px serif";

ctx.textAlign = "left";
ctx.fillText("left-aligned", x, 40);

ctx.textAlign = "center";
ctx.fillText("center-aligned", x, 85);

ctx.textAlign = "right";
ctx.fillText("right-aligned", x, 130);
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-textalign-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`.


CanvasRenderingContext2D.resetTransform() - Web API 接口参考

CanvasRenderingContext2D.resetTransform()
=========================================

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

**`CanvasRenderingContext2D.resetTransform()`** 是 Canvas 2D API 使用单位矩阵重新设置当前变形的方法。

语法
--
```

void ctx.resetTransform();
```

示例
--

### 重置矩阵

这是一段使用 `resetTransform` 方法的简单的代码片段。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

// Draw a rotated rectangle
ctx.rotate((45 \* Math.PI) / 180);
ctx.fillRect(60, 0, 100, 30);

// Reset transformation matrix to the identity matrix
ctx.resetTransform();
```

#### 结果

综合设置
----

你可以使用 `CanvasRenderingContext2D.setTransform()` 方法重新设置当前变形为单位矩阵，如下：

```js
ctx.setTransform(1, 0, 0, 1, 0, 0);
```

规范描述
----

| Specification |
| --- |
| HTML Standard # dom-context-2d-resettransform-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`


CanvasRenderingContext2D.fill() - Web API 接口参考

CanvasRenderingContext2D.fill()
===============================

**`CanvasRenderingContext2D.fill()`** 是 Canvas 2D API 根据当前的填充样式，填充当前或已存在的路径的方法。采取非零环绕或者奇偶环绕规则。

语法
--
```

void ctx.fill();
void ctx.fill(fillRule);
void ctx.fill(path, fillRule);
```

### 参数

`fillRule`

 一种算法，决定点是在路径内还是在路径外。
 允许的值：

`nonzero`

非零环绕规则，默认的规则。

`evenodd`

奇偶环绕规则。

`path`

需要填充的`Path2D` 路径。

示例
--

### 填充矩形

这是一段简单的代码片段，使用 `fill` 方法填充路径。

#### HTML

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");
ctx.rect(10, 10, 150, 100);
ctx.fill();
```

#### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-fill-dev |

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

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

参见
--

* 接口定义， `CanvasRenderingContext2D`.


CanvasRenderingContext2D.globalAlpha - Web API 接口参考

CanvasRenderingContext2D.globalAlpha
====================================

**`CanvasRenderingContext2D.globalAlpha`** 是 Canvas 2D API 用来描述在 canvas 上绘图之前，设置图形和图片透明度的属性。数值的范围从 0.0（完全透明）到 1.0（完全不透明）。

在 Canvas Tutorial 中参见 Applying styles and color 章节。

语法
--
```

ctx.globalAlpha = value;
```

### 选项

`value`

数字在 0.0（完全透明）和 1.0（完全不透明）之间。默认值是 1.0。如果数值不在范围内，包括`Infinity` 和`NaN` ，无法赋值，并且 `globalAlpha` 会保持原有的数值。

示例
--

### 绘制半透明形状

这是一段使用 `globalAlpha` 属性的简单代码片段，绘制了 2 个半透明的矩形。

```html
<canvas id="canvas"></canvas>
```

#### JavaScript

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

ctx.globalAlpha = 0.5;

ctx.fillStyle = "blue";
ctx.fillRect(10, 10, 100, 100);

ctx.fillStyle = "red";
ctx.fillRect(50, 50, 100, 100);
```

#### 结果

### 叠加透明形状

此例中，绘制了 4 个不同背景色的正方形。在他们上面，绘制半透明的圆形。将那个点绘制的所有图形的 `globalAlpha` 属性值都设置为 0.2。通过 for 循环绘制半径逐渐增大的圆形。最终形成的结果是放射性渐变。通过不停地叠加圆形，使得先前绘制的圆形的透明度越来越暗。通过增加循环数量绘制更多的圆形，图片中心的背景将会变成完全不透明。
```

<canvas id="canvas" width="150" height="150"></canvas>
```

```js
const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

// Draw background
ctx.fillStyle = "#FD0";
ctx.fillRect(0, 0, 75, 75);
ctx.fillStyle = "#6C0";
ctx.fillRect(75, 0, 75, 75);
ctx.fillStyle = "#09F";
ctx.fillRect(0, 75, 75, 75);
ctx.fillStyle = "#F30";
ctx.fillRect(75, 75, 75, 75);
ctx.fillStyle = "#FFF";

// Set transparency value
ctx.globalAlpha = 0.2;

// Draw transparent circles
for (let i = 0; i < 7; i++) {
  ctx.beginPath();
  ctx.arc(75, 75, 10 + 10 \* i, 0, Math.PI \* 2, true);
  ctx.fill();
}
```

| Screenshot | Live sample |
| --- | --- |
|  |  |

规范
--

| Specification |
| --- |
| HTML Standard # dom-context-2d-globalalpha-dev |

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

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

参见
--

* 接口定义，`CanvasRenderingContext2D`
* `CanvasRenderingContext2D.globalCompositeOperation`


IDBDatabase.deleteObjectStore() - Web API 接口参考

IDBDatabase.deleteObjectStore()
===============================

**`deleteObjectStore()`** 方法从 `IDBDatabase` 中销毁指定名称的对象存储，及这个对象存储所包含的任何索引。

与 `IDBDatabase.createObjectStore` 一样，此方法*只能*在`versionchange` (en-US)事务中调用。

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

语法
--
```

dbInstance.deleteObjectStore(name);
```

### 参数

`name`

将要删除的对象存储的名字

### 异常

此方法可能会引发下列 `DOMException` 异常：

| Exception | Description |
| --- | --- |
| `InvalidStateError` | Occurs if the method was not called from a `versionchange` transaction callback. For older WebKit browsers, you must call first. |
| `TransactionInactiveError` | Occurs if a request is made on a source database that doesn't exist (e.g. has been deleted or removed.) In Firefox previous to version 41, an `InvalidStateError` was raised in this case as well, which was misleading; this has now been fixed (see Firefox bug 1176165.) |
| `NotFoundError` | You are trying to delete an object store that does not exist. Names are case sensitive. |

示例
--

```js
var dbName = "sampleDB";
var dbVersion = 2;
var request = indexedDB.open(dbName, dbVersion);

request.onupgradeneeded = function (e) {
  var db = request.result;
  if (e.oldVersion < 1) {
    db.createObjectStore("store1");
  }

  if (e.oldVersion < 2) {
    db.deleteObjectStore("store1");
    db.createObjectStore("store2");
  }

  // etc. for version < 3, 4...
};
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbdatabase-deleteobjectstore① |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (view example live.)


IDBDatabase.createObjectStore() - Web API 接口参考

IDBDatabase.createObjectStore()
===============================

`IDBDatabase` 接口的 **`createObjectStore()`** 方法创建并返回一个新的 object store 或 index。

此方法接受一个参数作为 store 的名称，也接受一个可选的参数对象让你可以定义重要的可选属性。你可以用这个属性唯一的标识此 store 中的每个对象。因为参数是一个标识符，所以 store 中的每一个对象都应有此属性并保证此属性唯一。

此方法只能在 `versionchange` (en-US) 事务中被调用。

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

语法
--
```

var objectStore = IDBDatabase.createObjectStore(name);
var objectStore = IDBDatabase.createObjectStore(name, options);
```

### 参数

name

被创建的 object store 的名称。请注意创建空名称的 object store 是被允许的。

optionalParameters 可选

可选的对象，它的属性是此方法的可选参数，其中包括以下的属性：

| Attribute | Description |
| --- | --- |
| `keyPath` | key path (en-US) 被用在新的 object store 上。如果为空或未指定，object store 创建时将没有 key path，而是使用 out-of-line keys (en-US) 。你也能传一个数组作为 `keyPath` 。 |
| `autoIncrement` | 如果为 `true`, object store 有一个 key generator (en-US). 默认为 `false`。 |

未知参数将被忽略。

### 返回值

`IDBObjectStore`

新创建的 object store 对象。

### 异常

This method may raise a 此方法可能会抛出一个 `DOMException` 带有以下所列其中一种类型的 `DOMError` ：

| Exception | Description |
| --- | --- |
| `InvalidStateError` | 在非`versionchange`事务中调用时发生。在一些旧版本的 Webkit 浏览器，你必须先调用方法。 |
| `TransactionInactiveError` | 如果对不存在的源数据库发出请求（例如，已被删除的）。此外，在 Firefox 版本小于 41 中，会抛出误导性的 `InvalidStateError` 错误，这一问题现已修复（请参阅 Firefox bug 1176165）。 |
| `ConstraintError` | 数据库中已存同名的对象存储（名字区分大小写） |
| `InvalidAccessError` | 如果 `autoIncrement` 设置为 true，并且 keyPath 是空字符串或包含空字符串的数组。 |

Example
-------

```js
// 打开一个数据库
var request = window.indexedDB.open("toDoList", 4);

// This handler is called when a new version of the database
// is created, either when one has not been created before
// or when a new version number is submitted by calling
// window.indexedDB.open().
// This handler is only supported in recent browsers.
request.onupgradeneeded = function (event) {
  var db = event.target.result;

  db.onerror = function (event) {
    note.innerHTML += "<li>Error loading database.</li>";
  };

  // Create an objectStore for this database

  var objectStore = db.createObjectStore("toDoList", { keyPath: "taskTitle" });

  // define what data items the objectStore will contain

  objectStore.createIndex("hours", "hours", { unique: false });
  objectStore.createIndex("minutes", "minutes", { unique: false });
  objectStore.createIndex("day", "day", { unique: false });
  objectStore.createIndex("month", "month", { unique: false });
  objectStore.createIndex("year", "year", { unique: false });

  objectStore.createIndex("notified", "notified", { unique: false });

  note.innerHTML += "<li>Object store created.</li>";
};
```

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

| Specification |
| --- |
| Indexed Database API 3.0 # ref-for-dom-idbdatabase-createobjectstore① |

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

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

See also
--------

* Using IndexedDB
* Starting transactions: `IDBDatabase`
* Using transactions: `IDBTransaction`
* Setting a range of keys: `IDBKeyRange`
* Retrieving and making changes to your data: `IDBObjectStore`
* Using cursors: `IDBCursor`
* Reference example: To-do Notifications (view example live.)


IDBDatabase.onversionchange - Web API 接口参考

IDBDatabase.onversionchange
===========================

`IDBDatabase` 中的 **`onversionchange`** 事件处理器能处理版本更新事件，此事件能在任意地方 (很可能在同一台计算机上的另一个窗口/选项卡中) 导致数据库结构更改（`IDBOpenDBRequest.onupgradeneeded` (en-US) 事件 或 `IDBFactory.deleteDatabase` (en-US) 事件）的时候被触发。

**`onversionchange`** 与 `versionchange` 是不相同的事件（但两者是有关联的）。

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

语法
--
```

IDBDatabase.onversionchange = function(event) { ... }
```

举例
--

本例展示了一个创建新对象仓库的 `IDBOpenDBRequest.onupgradeneeded` (en-US) 代码块；代码中包含用于处理失败操作的 `onerror` 和 `onabort` 函数，以及一个 onversionchange 函数用以在数据库结构被改变时通知用户。

```js
request.onupgradeneeded = function(event) {
  var db = event.target.result;

  db.onerror = function(event) {
    note.innerHTML += '<li>Error opening database.</li>';
  };

  db.onabort = function(event) {
    note.innerHTML += '<li>Database opening aborted!</li>';
  };

  // 给这个数据库创建对象仓库

  var objectStore = db.createObjectStore("toDoList", { keyPath: "taskTitle" });

  // 定义对象仓库中包含的数据项

  objectStore.createIndex("hours", "hours", { unique: false });
  objectStore.createIndex("minutes", "minutes", { unique: false });
  objectStore.createIndex("day", "day", { unique: false });
  objectStore.createIndex("month", "month", { unique: false });
  objectStore.createIndex("year", "year", { unique: false });

  objectStore.createIndex("notified", "notified", { unique: false });

  note.innerHTML += '<li>Object store created.</li>';

  db.onversionchange = function(event) {
    note.innerHTML += '<li>a database change has occurred; you should refresh this
                       browser window, or close it down and use the other open version of
                       this application, wherever it exists.</li>';
  };
};
```

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

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

更多参考
----

* 使用 IndexedDB
* 开始了解事务：`IDBDatabase`
* 使用事务：`IDBTransaction`
* 设置键值范围：`IDBKeyRange`
* 检索与修改数据：`IDBObjectStore`
* 使用游标：`IDBCursor`
* 参考用例：To-do Notifications (view example live.)
* `versionchange` 事件


HTMLInputElement.setSelectionRange() - Web API 接口参考

HTMLInputElement.setSelectionRange()
====================================

**`HTMLInputElement.setSelectionRange`** 方法用于设定`<input>` 或 `<textarea>` 元素中当前选中文本的起始和结束位置。

在较新的浏览器中，你可以通过一个可选的 selectionDirection 来指定文本选中的方向。比如通过点击和拖动从结束位置往起始位置选中一个字符串。

每次调用这个这个方法都会更新 `HTMLInputElement` 的 `selectionStart`, `selectionEnd` 和 `selectionDirection` 属性。

要注意的是，在 WHATWG forms spec 中，`selectionStart`, `selectionEnd` 属性和 `setSelectionRange` 方法只能应用于类型为文本、搜索、链接、电话号码和密码的输入。Chrome 从版本 33 开始会在访问其余类型的这些属性和方法时抛出异常。例如，输入类型为数字时会抛出：“不能从'HTMLInputElement'中读取'selectionStart'属性：输入元素的类型 ('number') 不支持选择（Failed to read the 'selectionStart' property from 'HTMLInputElement': The input element's type ('number') does not support selection）”。

如果你希望**全选**输入元素中的文本，你可以使用 HTMLInputElement.select() 方法。

语法
--
```

element.setSelectionRange(selectionStart, selectionEnd [, selectionDirection]);
```

### 参数

如果 `selectionEnd` 小于 `selectionStart`，则二者都会被看作 `selectionEnd`。

* `selectionStart`
    + : 被选中的第一个字符的位置索引，从 0 开始。如果这个值比元素的 `value` 长度还大，则会被看作 `value` 最后一个位置的索引。
* `selectionEnd`
    + : 被选中的最后一个字符的 *下一个* 位置索引。如果这个值比元素的 value 长度还大，则会被看作 value 最后一个位置的索引。
* `selectionDirection` 可选
    + : 一个表示选择方向的字符串，可能的值有：
* `"forward"`
* `"backward"`
* `"none"` 默认值，表示方向未知或不相关。
示例
--

在这个示例中，按下按钮以选择文本框中第三、四、五个字符（即“Mozilla”中的“zil”）。

### HTML
```

<input type="text" id="text-box" size="20" value="Mozilla">
<button onclick="selectText()">Select text</button>
```

### JavaScript
```

function selectText() {
  const input = document.getElementById('text-box');
  input.focus();
  input.setSelectionRange(2, 5);
}
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # dom-textarea/input-setselectionrange-dev |

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

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

相关内容
----

* `<input>`
* `<textarea>`
* `HTMLInputElement`
* `Selection`


HTMLInputElement.multiple - Web API 接口参考

HTMLInputElement.multiple
=========================

**`HTMLInputElement.multiple`** 属性表示一个 input 是否可以有多个值。目前只有火狐支持 `<input type="file">`存有多个值。

实例
--

```js
// fileInput is a <input type=file multiple>
let fileInput = document.getElementById("myfileinput");

if (fileInput.multiple == true) {
  for (let i = 0; i < fileInput.files.length; i++) {
    // Loop fileInput.files
  }

  // Only one file available
} else {
  let file = fileInput.files.item(0);
}
```

See also
--------

* FileList
* Bug 523771 - Support <input type=file multiple>
Specification
-------------

* The multiple attribute (HTML 5 working draft)
Browser compatibility
---------------------

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


HTMLInputElement.labels - Web API 接口参考

HTMLInputElement.labels
=======================

**`HTMLInputElement.labels`** 为只读属性，它返回一个`NodeList` 实例，绑定当前的`<input>` 节点的`<label>` 元素。

语法
--
```

var labelElements = input.labels;
```

### Return value

`NodeList` 包含 `<label>` 元素和 `<input>` 元素。

示例
--

### HTML

```html
<label id="label1" for="test">Label 1</label>
<input id="test" />
<label id="label2" for="test">Label 2</label>
```

### JavaScript

```js
window.addEventListener("DOMContentLoaded", function () {
  const input = document.getElementById("test");
  for (var i = 0; i < input.labels.length; i++) {
    console.log(input.labels[i].textContent); // "Label 1" and "Label 2"
  }
});
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-lfe-labels-dev |

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

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


GlobalEventHandlers.onselectionchange - Web API 接口参考

GlobalEventHandlers.onselectionchange
=====================================

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

**`GlobalEventHandlers.onselectionchange`** 属性表示当一个 `selectstart` 事件被触发，比如在页面上选中文字变化时，会执行绑定的事件处理器

语法
--
```

obj.onselectionchange = function;
```

示例
--

```js
var selection;

document.onselectionchange = function () {
  console.log("New selection made");
  selection = document.getSelection();
};
```

完整例子请参阅Key quote generator demo.

规范
--

| Specification |
| --- |
| Selection API # selectionchange-event |
| Selection API # dom-globaleventhandlers-onselectionchange |

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

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


HTMLInputElement.select() - Web API 接口参考

HTMLInputElement.select()
=========================

**`HTMLInputElement.select()`** 方法选中一个 `<textarea>` 元素或者一个带有 text 字段的 `<input>` 元素里的所有内容。

语法
--
```

element.select()
```

示例
--

点击这个例子的按钮以选中所有在`<input>`元素中的文字

HTML

```html
<input type="text" id="text-box" size="20" value="Hello world!" />
<button onclick="selectText()">Select text</button>
```

JavaScript

```js
function selectText() {
  const input = document.getElementById("text-box");
  input.focus();
  input.select();
}
```

### 结果

注意
--

调用 `element.select()` 并不一定会使得该 input 元素被 focused，所以它经常和 `HTMLElement.focus()` (en-US) 一起使用。

规范
--

| Specification |
| --- |
| HTML Standard # dom-textarea/input-select |

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

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

相关链接
----

* `<input>`
* `<textarea>`
* `HTMLInputElement`
* `HTMLInputElement.setSelectionRange`


HTMLInputElement：webkitdirectory 属性 - Web API 接口参考

HTMLInputElement：webkitdirectory 属性
===================================

**`HTMLInputElement.webkitdirectory`** 是一个反应了 HTML 属性 `webkitdirectory` 的属性，其指示 `<input>` 元素应该让用户选择文件目录而非文件。在选择文件目录后，该目录及其整个内容层次结构将包含在所选项目集内。可以使用 `webkitEntries` (en-US) 属性获取选定的文件系统条目。

**备注：** 该属性在规范中被称为 `webkitEntries` 的原因是，其起源于 Google Chrome 特定的 API。它有可能会被重命名。

值
-

一个布尔值；如果设置为 `true`，则 `<input>` 元素只允许选择目录；如果设置为 `false`，则只允许选择文件。

理解结果
----

在用户进行选择后，`files` 里的每个 `File` 对象都会将其 `File.webkitRelativePath` 属性设置为所选目录内文件所在的相对路径。例如，考虑以下文件系统：

* PhotoAlbums
    + Birthdays
        - Jamie's 1st birthday
            * PIC1000.jpg
            * PIC1004.jpg
            * PIC1044.jpg
        - Don's 40th birthday
            * PIC2343.jpg
            * PIC2344.jpg
            * PIC2355.jpg
            * PIC2356.jpg
    + Vacations
        - Mars
            * PIC5533.jpg
            * PIC5534.jpg
            * PIC5556.jpg
            * PIC5684.jpg
            * PIC5712.jpg

如果用户选择了 `PhotoAlbums`，则文件列表上将会包含上面列出的每个文件（而不包含目录）的 `File` 对象。条目 `PIC2343.jpg` 的 `webkitRelativePath` 属性值将会是 `PhotoAlbums/Birthdays/Don's 40th birthday/PIC2343.jpg`。即使 `FileList` 是扁平的，这也使得知道层次结构成为可能。

**备注：** 在 *Chromium < 72* 的版本中，`webkitRelativePath` 的行为表现有所不同。有关更多详细信息，请参见此 bug。

示例
--

这个示例提供了一个目录选择器，它允许用户选择一个或多个目录。当触发 `change` 事件时，将生成并显示所选目录层次结构中包含的所有文件的列表。

### HTML

```html
<input type="file" id="filepicker" name="fileList" webkitdirectory multiple />
<ul id="listing"></ul>
```

### JavaScript

```js
document.getElementById("filepicker").addEventListener(
  "change",
  (event) => {
    let output = document.getElementById("listing");
    for (const file of event.target.files) {
      let item = document.createElement("li");
      item.textContent = file.webkitRelativePath;
      output.appendChild(item);
    }
  },
  false,
);
```

### 结果

规范
--

| Specification |
| --- |
| File and Directory Entries API # dom-htmlinputelement-webkitdirectory |

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

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

参见
--

* 文件和目录条目 API
* `HTMLInputElement.webkitEntries` (en-US)
* `File.webkitRelativePath`


HTMLInputElement: invalid event - Web API 接口参考

HTMLInputElement: invalid event
===============================

若一个可提交元素在检查有效性时，不符合对它的约束条件，则会触发 **`invalid`** 事件。

|  |  |
| --- | --- |
| 冒泡 | 否 |
| 可取消 | 是 |
| 接口 | `Event` |
| 事件处理程序属性 | `GlobalEventHandlers.oninvalid` |

这个事件可用于展示提交表单时所出现的问题的概览。当表单提交时，若任一表单控件无效，则会触发 `invalid` 事件。对可提交元素有效性的检查是在提交父元素 `<form>` 之前或调用父元素 `<form>` 或元素自己的 `checkValidity()` 方法之后。

这个事件不会在 `blur` 事件中触发。

示例
--

如果表单提交时有无效值，检查可提交元素时发现了错误，则 `invalid` 事件会在那个无效元素上触发。在这个例子中，当输入无效值触发 `invalid` 事件时，这个无效值被记录下来。

### HTML

```html
<form action="#">
  <ul>
    <li>
      <label
 >Enter an integer between 1 and 10:
        <input type="number" min="1" max="10" required
 /></label>
    </li>
    <li><input type="submit" value="submit" /></li>
  </ul>
</form>
<p id="log"></p>
```

### JavaScript

```js
const input = document.querySelector("input");
const log = document.getElementById("log");

input.addEventListener("invalid", logValue);

function logValue(e) {
  log.textContent += e.target.value;
}
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # event-invalid |

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

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

参见
--

* HTML `<form>` 元素
* 相关事件：`submit`
* CSS `:invalid` 伪类


HTMLInputElement.showPicker() - Web API 接口参考

HTMLInputElement.showPicker()
=============================

**`HTMLInputElement.showPicker()`** 方法为 `input` 元素展示浏览器的默认选择器（picker）。

这与选择元素时通常展示的选择器相同，但是它可以由按钮或者用户交互触发。

通常地，浏览器为这些类型的 input 实现此方法：`"date"`、`"month"`、`"week"`、`"time"`、`"datetime-local"`、`"color"` 或 `"file"`。它也可以预填充来自 `<datalist>` 元素或者 `autocomplete` 属性的项目。

更一般地说，这种方法完美地展示了平台上任何具有选择器的 input 元素的选择器。

语法
--

```js
showPicker()
```

### 参数

无。

### 返回值

无（`undefined`）。

### 异常

`InvalidStateError` `DOMException`

如果元素不可变，则抛出，这意味着用户不能修改它和/或无法自动预填充它。

`NotAllowedError` `DOMException`

如果不是由触摸手势或者鼠标点击等显示触发（选择器需要瞬态激活 (en-US)），则抛出。

`SecurityError` `DOMException`

如果在跨域 iframe 中调用，则抛出，除了文件和颜色选择器（由于历史原因豁免）。

安全性
---

瞬态用户激活 (en-US)是需要的。用户必须与页面或者 UI 元素交互，才能使这个功能按顺序工作。

示例
--

### 功能检测

以下代码展示了如何检查 `showPicker()` 是否被支持：

```js
if ("showPicker" in HTMLInputElement.prototype) {
  // showPicker() is supported.
}
```

### 正常的 input 选择器

这个示例展示了如何将这个功能用于 `color` 和 `file` 的 input 选择器。

**备注：** `date`、`datetime-local`、`month`、`time`、`week` 的选择器以同样的方式启动。它们并不能在这里展示，因为在线示例运行在一个跨域 frame 中，并且会导致 `SecurityError`。

#### HTML

```html
<p>
  <input type="color" />
  <button id="color">Show the color picker</button>
</p>

<p>
  <input type="file" />
  <button id="file">Show the file picker</button>
</p>
```

#### JavaScript

代码只要获取所选按钮的上一个元素并在上面调用 `showPicker()` 即可。

```js
document.querySelectorAll("button").forEach((button) => {
  button.addEventListener("click", (event) => {
    const input = event.srcElement.previousElementSibling;
    try {
      input.showPicker();
    } catch (error) {
      window.alert(error);
    }
  });
});
```

#### 结果

单击每个 input 类型旁边的按钮以显示其选择器。

### showPicker() 用于 datalist input

`showPicker()` 可以启动定义在 `<datalist>` 列表中选项的选择器。

首先，我们在 HTML 中定一个了 `<datalist>`，它由许多互联网浏览器、使用类型为 `text` 的 input 和 一个按钮组成。

```html
<datalist id="browsers">
  <option value="Chrome"></option>
  <option value="Firefox"></option>
  <option value="Internet Explorer"></option>
  <option value="Opera"></option>
  <option value="Safari"></option>
  <option value="Microsoft Edge"></option>
</datalist>

<input type="text" list="browsers" />
<button>Select browser</button>
```

以下代码增加了一个事件监听器，当按钮被点击时，调用 `showPicker()`。

```js
const button = document.querySelector("button");
const browserInput = document.querySelector("input");

button.addEventListener("click", () => {
  try {
    browserInput.showPicker();
  } catch (error) {
    // Fall back to another picker mechanism
  }
});
```

### showPicker() 用于 autocomplete

`showPicker()` 可以为一个 `autocomplete` input 开启选择器。

这里，我们定义了一个 input，其采用了 autocomplete 为“name”的选项。

```html
<input autocomplete="name" /> <button>Show autocomplete options</button>
```

以下代码展示了当按钮被点击时，input 展示的选择器。

```js
const button = document.querySelector("button");
const browserInput = document.querySelector("input");

button.addEventListener("click", () => {
  try {
    browserInput.showPicker();
  } catch (error) {
    // Fall back to another picker mechanism
  }
});
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-input-showpicker |

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

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

参见
--

* `<input>`
* `HTMLInputElement`
* `<datalist>`
* `autocomplete`


select - Web API 接口参考

select
======

**`select`** 选择某些文本时会触发事件。

该事件不适用于所有语言的所有元素。例如，在 HTML，`select`事件只能在表单<input type="text">和 `<textarea>`元素上触发。

General info
------------

| Interface | `UIEvent` if generated from a user interface,
 `Event` otherwise
  |
| Bubbles | Yes |
| Cancelable | No |
| Target | `Element` |
| Default Action | None |

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | `EventTarget` | The event target (the topmost target in the DOM tree). |
| `type` 只读  | `DOMString` | The type of event. |
| `bubbles` 只读  | `Boolean` (en-US) | Whether the event normally bubbles or not. |
| `cancelable` 只读  | `Boolean` (en-US) | Whether the event is cancellable or not. |
| `view` 只读  | `WindowProxy` | `document.defaultView` (`window` of the document) |
| `detail` 只读  | `long` (`float`) | 0. |

示例
--

### HTML

```html
<input value="Try selecting some text in this element." />
<p id="log"></p>
```

### JavaScript

```js
function logSelection(event) {
  const log = document.getElementById("log");
  const selection = event.target.value.substring(
    event.target.selectionStart,
    event.target.selectionEnd,
  );
  log.textContent = `You selected: ${selection}`;
}

const input = document.querySelector("input");
input.addEventListener("select", logSelection);
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # event-select |
| HTML Standard # handler-onselect |

参见
--

* `GlobalEventHandlers.onselect`


CountQueuingStrategy.size() - Web API 接口参考

CountQueuingStrategy.size()
===========================

`CountQueuingStrategy` 接口的 **`size()`** 方法始终返回 `1`，因此队列的总大小是队列中所有分块的数量。

语法
--

```js
size()
```

### 参数

无。

### 返回值

`1`。

示例
--

```js
const queuingStrategy = new CountQueuingStrategy({ highWaterMark: 1 });

const writableStream = new WritableStream(
  {
    // Implement the sink
    write(chunk) {
      // …
    },
    close() {
      // …
    },
    abort(err) {
      console.log("Sink error:", err);
    },
  },
  queuingStrategy,
);

const size = queuingStrategy.size();
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-cqs-size② |

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

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

参见
--

* `CountQueuingStrategy()` 构造函数


CountQueuingStrategy：highWaterMark 属性 - Web API 接口参考

CountQueuingStrategy：highWaterMark 属性
=====================================

只读属性 **`CountQueuingStrategy.highWaterMark`** 返回在应用背压之前，内置队列可以包含的分块总数。

值
-

一个整数，表示分块的数量。

示例
--

```js
const queueingStrategy = new CountQueuingStrategy({ highWaterMark: 1 });

const readableStream = new ReadableStream(
  {
    start(controller) {
      // …
    },
    pull(controller) {
      // …
    },
    cancel(err) {
      console.log("stream error:", err);
    },
  },
  queuingStrategy,
);

const size = queuingStrategy.size(chunk);
console.log(`highWaterMark value: ${queuingStrategy.highWaterMark}$`);
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-cqs-high-water-mark① |

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

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

参见
--

* `CountQueuingStrategy()` 构造函数


CountQueuingStrategy() - Web API 接口参考

CountQueuingStrategy()
======================

**`CountQueuingStrategy()`** 构造函数创建并返回一个 `CountQueuingStrategy` 对象实例。

语法
--

```js
new CountQueuingStrategy(highWaterMark)
```

### 参数

`highWaterMark`

一个包含 `highWaterMark` 属性的对象。这个属性是一个非负整数，定义了在应用背压之前内部队列包含的分块的总数。

### 返回值

一个 `CountQueuingStrategy` 对象实例。

### 异常

无。

示例
--

```js
const queuingStrategy = new CountQueuingStrategy({ highWaterMark: 1 });

const writableStream = new WritableStream(
  {
    // Implement the sink
    write(chunk) {
      // …
    },
    close() {
      // …
    },
    abort(err) {
      console.log("Sink error:", err);
    },
  },
  queuingStrategy,
);

const size = queuingStrategy.size();
```

规范
--

| Specification |
| --- |
| Streams Standard # ref-for-cqs-constructor① |

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

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

参见
--

* `CountQueuingStrategy`


XMLHttpRequest.responseURL - Web API 接口参考

XMLHttpRequest.responseURL
==========================

只读属性 **`XMLHttpRequest.responseURL`** 返回响应的序列化 URL，如果 URL 为空则返回空字符串。如果 URL 有锚点，则位于 URL # 后面的内容会被删除。如果 URL 有重定向，`responseURL` 的值会是经过多次重定向后的最终 URL。

实例
--

```js
var xhr = new XMLHttpRequest();
xhr.open("GET", "http://example.com/test", true);
xhr.onload = function () {
  console.log(xhr.responseURL); // http://example.com/test
};
xhr.send(null);
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-responseurl-attribute |

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

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


loadstart - Web API 接口参考

loadstart
=========

当程序开始加载时，loadstart 事件将被触发。这个事件可以被 `XMLHttpRequest` 调用，也适用于 `<img>` 和 `<video>` 元素。

基本信息
----

规范文档

Progress

接口

ProgressEvent

冒泡

No

可取消

No

目标

Element

默认动作

None

属性
--

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | `EventTarget` | The event target (the topmost target in the DOM tree). |
| `type` 只读  | `DOMString` | The type of event. |
| `bubbles` 只读  | `Boolean` | Whether the event normally bubbles or not. |
| `cancelable` 只读  | `Boolean` | Whether the event is cancellable or not. |
| `lengthComputable` 只读  | `Boolean` | Specifies whether or not the total size of the transfer is known. Read only. |
| `loaded` 只读  | unsigned long (long) | The number of bytes transferred since the beginning of the operation. This doesn't include headers and other overhead, but only the content itself. Read only. |
| `total` 只读  | unsigned long (long) | The total number of bytes of content that will be transferred during the operation. If the total size is unknown, this value is zero. Read only. |

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # event-xhr-loadstart |
| XMLHttpRequest Standard # handler-xhr-onloadstart |

参见
--

* 相关事件：`loadend`、`load`、`progress`、`error`、`abort`
* 监测进度


XMLHttpRequest.response - Web API 接口参考

XMLHttpRequest.response
=======================

`XMLHttpRequest` 的 **`response`** 属性返回响应的正文。返回的类型为 `ArrayBuffer`、`Blob`、`Document`、JavaScript `Object` 或字符串中的一个。这取决于请求的 `responseType` 属性。

值
-

一个对象，其类型取决于 `responseType` 的值。你可以尝试设置 `responseType` 的值，以便请求特定的类型的数据。 `responseType` 要在调用 `open()` 初始化请求之后以及在调用 `send()` 发送请求到服务器之前设置。

如果请求尚未完成或未成功，则取值是 `null`。例外的，读取文本数据时如果将 `responseType` 的值设置成 `"text"` 或空字符串（`""`）而请求状态还是 `LOADING` `readyState`（3）时，`response` 包含到目前为止该请求已经取得的内容。

示例
--

此示例提供了一个方法——`load()`，它可以从服务器加载和处理页面。它通过创建一个 `XMLHttpRequest` 对象并为 `readystatechange` 事件创建一个监听器。这样的话，当 `readyState` 变成 `DONE`（4）时就会获取 `response` 并将其传递给 `load()` 中提供的回调函数。

返回的内容会被作为原始文本数据处理（因为这里没有覆盖 `responseType` 的默认值）。

```js
const url = "somePage.html"; // 一个本地页面

function load(url, callback) {
  const xhr = new XMLHttpRequest();

  xhr.onreadystatechange = () => {
    if (xhr.readyState === 4) {
      callback(xhr.response);
    }
  };

  xhr.open("GET", url, true);
  xhr.send("");
}
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-response-attribute |

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

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

参见
--

* 使用 XMLHttpRequest
* 获取文本和 HTML/XML 数据：`XMLHttpRequest.responseText` 和 `XMLHttpRequest.responseXML`


XMLHttpRequest.setRequestHeader() - Web API 接口参考

XMLHttpRequest.setRequestHeader()
=================================

**XMLHttpRequest.setRequestHeader()** 是设置 HTTP 请求头部的方法。此方法必须在 `open()` 方法和 `send()` 之间调用。如果多次对同一个请求头赋值，只会生成一个合并了多个值的请求头。

如果没有设置 `Accept` 属性，则此发送出`send()` 的值为此属性的默认值：`*/*`。

安全起见，有些请求头的值只能由 user agent 设置：forbidden header names 和forbidden response header names。

**备注：** 自定义一些 header 属性进行跨域请求时，可能会遇到"**not allowed by Access-Control-Allow-Headers in preflight response**"，你可能需要在你的服务端设置 "Access-Control-Allow-Headers"。

语法
--
```

myReq.setRequestHeader(header, value);
```

### 参数

`header`

属性的名称。

`value`

属性的值。

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-setrequestheader()-method |

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

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

参考
--

使用 XMLHttpRequest


XMLHttpRequest：withCredentials 属性 - Web API 接口参考

XMLHttpRequest：withCredentials 属性
=================================

**`XMLHttpRequest.withCredentials`** 属性是一个布尔值，它指示了是否该使用类似 cookie、Authorization 标头或者 TLS 客户端证书等凭据进行跨站点访问控制（`Access-Control`）请求。设置 `withCredentials` 对同源请求是无效的。

此外，这个标志还用于指示何时在响应中忽略 cookie。默认值是 `false`。除非在发送 `XMLHttpRequest` 请求之前，将 `withCredentials` 设置为 `true`，否则来自不同域的 `XMLHttpRequest` 响应无法为自己的域设置 cookie 值。而通过设置 `withCredentials` 为 true 获得第三方 cookie，仍将遵循同源策略，因此请求的脚本无法通过 document.cookie 或者响应标头访问。

**备注：** 永远不会影响到同源请求。

**备注：** 不同域下的 `XmlHttpRequest` 响应，不论其 `Access-Control-` 标头设置什么值，都无法为它自身站点设置 Cookie 值，除非它在请求之前将 `withCredentials` 设为 true。

值
-

布尔值。

示例
--

```js
const xhr = new XMLHttpRequest();
xhr.open("GET", "http://example.com/", true);
xhr.withCredentials = true;
xhr.send(null);
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-withcredentials-attribute |

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

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


XMLHttpRequest: load event - Web API 接口参考

XMLHttpRequest: load event
==========================

当一个`XMLHttpRequest`请求完成的时候会触发`load` 事件。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `ProgressEvent` |
| Event handler property | `onload` |

示例
--

### 在线示例

#### HTML

```html
<div class="controls">
  <input
 class="xhr success"
 type="button"
 name="xhr"
 value="Click to start XHR (success)" />
  <input
 class="xhr error"
 type="button"
 name="xhr"
 value="Click to start XHR (error)" />
  <input
 class="xhr abort"
 type="button"
 name="xhr"
 value="Click to start XHR (abort)" />
</div>

<textarea readonly class="event-log"></textarea>
```

```
.event-log {
  width: 25rem;
  height: 4rem;
  border: 1px solid black;
  margin: 0.5rem;
  padding: 0.2rem;
}

input {
  width: 11rem;
  margin: 0.5rem;
}
```

#### JS

```js
const xhrButtonSuccess = document.querySelector(".xhr.success");
const xhrButtonError = document.querySelector(".xhr.error");
const xhrButtonAbort = document.querySelector(".xhr.abort");
const log = document.querySelector(".event-log");

function handleEvent(e) {
  log.textContent =
    log.textContent + `${e.type}: ${e.loaded} bytes transferred\n`;
}

function addListeners(xhr) {
  xhr.addEventListener("loadstart", handleEvent);
  xhr.addEventListener("load", handleEvent);
  xhr.addEventListener("loadend", handleEvent);
  xhr.addEventListener("progress", handleEvent);
  xhr.addEventListener("error", handleEvent);
  xhr.addEventListener("abort", handleEvent);
}

function runXHR(url) {
  log.textContent = "";

  const xhr = new XMLHttpRequest();
  addListeners(xhr);
  xhr.open("GET", url);
  xhr.send();
  return xhr;
}

xhrButtonSuccess.addEventListener("click", () => {
  runXHR("dgszyjnxcaipwzy.jpg");
});

xhrButtonError.addEventListener("click", () => {
  runXHR("https://somewhere.org/i-dont-exist");
});

xhrButtonAbort.addEventListener("click", () => {
  runXHR("dgszyjnxcaipwzy.jpg").abort();
});
```

#### 结果

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # event-xhr-load |
| XMLHttpRequest Standard # handler-xhr-onload |

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

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

参见
--

* 相关事件：`loadstart`、`loadend`、`progress`、`error`、`abort`
* 监测进度


XMLHttpRequest: error 事件 - Web API 接口参考

XMLHttpRequest: error 事件
========================

当请求遇到错误时，将触发`error` 事件。

|  |  |
| --- | --- |
| 可冒泡 | No |
| 可取消 | No |
| 接口 | `ProgressEvent` |
| 事件处理程序属性 | `onerror` |

示例
--

### 在线示例

#### HTML

```html
<div class="controls">
  <input
 class="xhr success"
 type="button"
 name="xhr"
 value="Click to start XHR (success)" />
  <input
 class="xhr error"
 type="button"
 name="xhr"
 value="Click to start XHR (error)" />
  <input
 class="xhr abort"
 type="button"
 name="xhr"
 value="Click to start XHR (abort)" />
</div>

<textarea readonly class="event-log"></textarea>
```

```
.event-log {
  width: 25rem;
  height: 4rem;
  border: 1px solid black;
  margin: 0.5rem;
  padding: 0.2rem;
}

input {
  width: 11rem;
  margin: 0.5rem;
}
```

#### JS

```js
const xhrButtonSuccess = document.querySelector(".xhr.success");
const xhrButtonError = document.querySelector(".xhr.error");
const xhrButtonAbort = document.querySelector(".xhr.abort");
const log = document.querySelector(".event-log");

function handleEvent(e) {
  log.textContent =
    log.textContent + `${e.type}: ${e.loaded} bytes transferred\n`;
}

function addListeners(xhr) {
  xhr.addEventListener("loadstart", handleEvent);
  xhr.addEventListener("load", handleEvent);
  xhr.addEventListener("loadend", handleEvent);
  xhr.addEventListener("progress", handleEvent);
  xhr.addEventListener("error", handleEvent);
  xhr.addEventListener("abort", handleEvent);
}

function runXHR(url) {
  log.textContent = "";

  const xhr = new XMLHttpRequest();
  addListeners(xhr);
  xhr.open("GET", url);
  xhr.send();
  return xhr;
}

xhrButtonSuccess.addEventListener("click", () => {
  runXHR("dgszyjnxcaipwzy.jpg");
});

xhrButtonError.addEventListener("click", () => {
  runXHR("https://somewhere.org/i-dont-exist");
});

xhrButtonAbort.addEventListener("click", () => {
  runXHR("dgszyjnxcaipwzy.jpg").abort();
});
```

#### 结果

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # event-xhr-error |
| XMLHttpRequest Standard # handler-xhr-onerror |

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

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

参见
--

* 相关事件：`loadstart`、`load`、`progress`、`loadend`、`abort`
* 监视进度


XMLHttpRequest.responseText - Web API 接口参考

XMLHttpRequest.responseText
===========================

**XMLHttpRequest.responseText** 在一个请求被发送后，从服务器端返回文本。

语法
--
```

var resultText = XMLHttpRequest.responseText;
```

### 取值

`DOMString` 是 `XMLHttpRequest` 返回的纯文本的值。当 `DOMString` 为 `null` 时，表示请求失败了。当`DOMString` 为 "" 时，表示这个请求还没有被 `send()`

当处理一个异步 request 的时候，尽管当前请求并没有结束，`responseText` 的返回值是当前从后端收到的内容。

当请求状态 `readyState` 变为 `XMLHttpRequest.DONE` (`4`)，且 `status` 值为 200（"OK"）时，`responseText` 是全部后端的返回数据

例子
--

```js
var xhr = new XMLHttpRequest();
xhr.open("GET", "/server", true);

// If specified, responseType must be empty string or "text"
xhr.responseType = "text";

xhr.onload = function () {
  if (xhr.readyState === xhr.DONE) {
    if (xhr.status === 200) {
      console.log(xhr.response);
      console.log(xhr.responseText);
    }
  }
};

xhr.send(null);
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-responsetext-attribute |

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

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


XMLHttpRequest.send() - Web API 接口参考

XMLHttpRequest.send()
=====================

**`XMLHttpRequest.send()`** 方法用于发送 HTTP 请求。如果是异步请求（默认为异步请求），则此方法会在请求发送后立即返回；如果是同步请求，则此方法直到响应到达后才会返回。`XMLHttpRequest.send()` 方法接受一个可选的参数，其作为请求主体；如果请求方法是 GET 或者 HEAD，则应将请求主体设置为 null。

如果没有使用 `setRequestHeader()` 方法设置 `Accept` 头部信息，则会发送带有 `"* / *"` 的`Accept` 头部。

**备注：** 请注意不要使用一个简单的 ArrayBuffer 对象作为参数，ArrayBuffer 已经不再是 AJAX 规范的一部分，请改用 ArrayBufferView（有关信息请参考兼容性列表。）

语法
--
```

XMLHttpRequest.send(body)
```

### 参数

`body` 可选

在 XHR 请求中要发送的数据体。可以是：

* 可以为 `Document`, 在这种情况下，它在发送之前被序列化。
* 为 `XMLHttpRequestBodyInit`, 从 per the Fetch spec （规范中）可以是 `Blob`, `BufferSource`, `FormData`, `URLSearchParams`, 或者 `USVString` 对象。
* `null`

如果 body 没有指定值，则默认值为 `null`。

### 返回值

`undefined`.

### 例外

| Exception | Description |
| --- | --- |
| `InvalidStateError` | `send()` has already been invoked for the request, and/or the request is complete. |
| `NetworkError` | The resource type to be fetched is a Blob, and the method is not `GET`. |

```js
XMLHttpRequest.send();
XMLHttpRequest.send(ArrayBuffer data);
XMLHttpRequest.send(ArrayBufferView data);
XMLHttpRequest.send(Blob data);
XMLHttpRequest.send(Document data);
XMLHttpRequest.send(DOMString? data);
XMLHttpRequest.send(FormData data);
```

如果发送的数据是 Document 对象，需要在发送之前将其序列化。当发送一个 Document 对象时，Firefox 3 之前的版本都是使用 UTF-8 编码发送请求的；FireFox 3 则使用由 `body.xmlEncoding` 指定的编码格式正确的发送文档，但如果未指定编码格式，则使用 UTF-8 编码格式发送。

如果是一个 nsIInputStream 接口，它必须与 nsIUploadChannel 的 `setUploadStream()` 方法兼容。在这种情况下，将 Content-Length 的头部添加到请求中，它的值则使用 nsIInputStream 接口的 `available()` 方法获取。任何报头包括在数据流顶部的都会被当做报文主体。所以，应该在发送请求即调用 `send()` 方法之前使用`setRequestHeader()` 方法设置 Content-Type 头部来指定数据流的 MIME 类型。

发送二进制内容的最佳方法（如上传文件）是使用一个与 `send()` 方法结合的 ArrayBufferView 或者 Blobs

案例：GET
------
```

var xhr = new XMLHttpRequest();
xhr.open('GET', '/server', true);

xhr.onload = function () {
   // 请求结束后，在此处写处理代码
};

xhr.send(null);
// xhr.send('string');
// xhr.send(new Blob());
// xhr.send(new Int8Array());
// xhr.send(document);
```

案例：POST
-------
```

var xhr = new XMLHttpRequest();
xhr.open("POST", '/server', true);

//发送合适的请求头信息
xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");

xhr.onload = function () {
    // 请求结束后，在此处写处理代码
};
xhr.send("foo=bar&lorem=ipsum");
// xhr.send('string');
// xhr.send(new Blob());
// xhr.send(new Int8Array());
// xhr.send(document);
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-send()-method |

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

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

参见
--

* 使用 XMLHttpRequest
* XMLHttpRequest 中的 HTML


XMLHttpRequest.upload - Web API 接口参考

XMLHttpRequest.upload
=====================

**XMLHttpRequest.upload 属性返回一个** `XMLHttpRequestUpload` (en-US)对象，用来表示上传的进度。这个对象是不透明的，但是作为一个`XMLHttpRequestEventTarget`，可以通过对其绑定事件来追踪它的进度。

可以被绑定在 upload 对象上的事件监听器如下：

| 事件 | 相应属性的信息类型 |
| --- | --- |
| `onloadstart` | 获取开始 |
| `onprogress` | 数据传输进行中 |
| `onabort` | 获取操作终止 |
| `onerror` | 获取失败 |
| `onload` | 获取成功 |
| `ontimeout` | 获取操作在用户规定的时间内未完成 |
| `onloadend` | 获取完成（不论成功与否） |

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-upload-attribute |

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

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


loadend - Web API 接口参考

loadend
=======

loadend 事件总是在一个资源的加载进度停止之后被触发 (例如，在已经触发“error”，“abort”或“load”事件之后)。这适用于 `XMLHttpRequest` 调用，以及 `<img>` 或 `<video>` 之类元素的内容。

General info
------------

规范

Progress

接口

ProgressEvent

可冒泡

否

可取消

否

触发对象

例如`HTMLImageElement`

默认行为

无

Properties
----------

| Property | Type | Description |
| --- | --- | --- |
| `target` 只读  | `EventTarget` | The event target (the topmost target in the DOM tree). |
| `type` 只读  | `DOMString` | The type of event. |
| `bubbles` 只读  | `Boolean` | Whether the event normally bubbles or not. |
| `cancelable` 只读  | `Boolean` | Whether the event is cancellable or not. |
| `lengthComputable` 只读  | `Boolean` | Specifies whether or not the total size of the transfer is known. Read only. |
| `loaded` 只读  | unsigned long (long) | The number of bytes transferred since the beginning of the operation. This doesn't include headers and other overhead, but only the content itself. Read only. |
| `total` 只读  | unsigned long (long) | The total number of bytes of content that will be transferred during the operation. If the total size is unknown, this value is zero. Read only. |

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # event-xhr-loadend |
| XMLHttpRequest Standard # handler-xhr-onloadend |

参见
--

* 相关事件：`loadstart`、`load`、`progress`、`error`、`abort`
* 监测进度


XMLHttpRequest.timeout - Web API 接口参考

XMLHttpRequest.timeout
======================

**`XMLHttpRequest.timeout`** 是一个无符号长整型数，代表着一个请求在被自动终止前所消耗的毫秒数。默认值为 0，意味着没有超时。超时并不应该用在一个 document environment 中的同步 XMLHttpRequests 请求中，否则将会抛出一个 `InvalidAccessError` 类型的错误。当超时发生， timeout 事件将会被触发。

**备注：** 你不能在拥有的 window 中，给同步请求使用超时。

在异步请求中使用 timeout

在 IE 中，超时属性可能只能在调用 open() 方法之后且在调用 send() 方法之前设置。

示例
--

```js
var xhr = new XMLHttpRequest();
xhr.open("GET", "/server", true);

xhr.timeout = 2000; // 超时时间，单位是毫秒

xhr.onload = function () {
  // 请求完成。在此进行处理。
};

xhr.ontimeout = function (e) {
  // XMLHttpRequest 超时。在此做某事。
};

xhr.send(null);
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-timeout-attribute |


XMLHttpRequest.getResponseHeader() - Web API 接口参考

XMLHttpRequest.getResponseHeader()
==================================

\*\*XMLHttpRequest.getResponseHeader()\*\*方法返回包含指定响应头文本的字符串。

如果在返回的响应头中有多个一样的名称，那么返回的值就会是用逗号和空格将值分隔的字符串。`getResponseHeader()` 方法以 UTF 编码返回值。搜索的报文名是不区分大小写的。

语法
--
```

var myHeader = XMLHttpRequest.getResponseHeader(name);
```

### 参数

name

一个字符串，表示要返回的报文项名称。

### 返回值

报文项值，如果连接未完成，响应中不存在报文项，或者被 W3C 限制，则返回 null。

示例：
---

```js
var client = new XMLHttpRequest(); //新建 XMLHttpRequest 对象。
client.open("GET", "somefile.txt", true); // 采用异步，GET 方式获取 somefile.txt。
client.send(); // 发送空的 query string。
client.onreadystatechange = function() { //设定侦听器 onreadystatechange。
  if(this.readyState == this.HEADERS\_RECEIVED) { // 如果 readyState 表示响应头已返回
    var contentType=client.getResponseHeader("Content-Type")); // 将此连接的 Content-Type 响应头项赋值到 contentType。
    if(contentType != my_expected_type) { // 如果这不是你的预期值
      client.abort(); // 终止连接
    }
  }
}
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # dom-xmlhttprequest-getresponseheader |

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

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

参见
--

* 如何使用 XMLHttpRequest
* HTTP 标头
* `getAllResponseHeaders()`
* `response`
* 设置请求标头：`setRequestHeader()`


XMLHttpRequest.open() - Web API 接口参考

XMLHttpRequest.open()
=====================

**XMLHttpRequest.open()** 方法初始化一个新创建的请求，或重新初始化一个请求。

**备注：** 为已激活的请求调用此方法（`open()`或`openRequest()` 已被调用）相当于调用`abort()`。

语法
--

```js
xhrReq.open(method, url);
xhrReq.open(method, url, async);
xhrReq.open(method, url, async, user);
xhrReq.open(method, url, async, user, password);
```

### 参数

`method`

要使用的 HTTP 方法，比如 `GET`、`POST`、`PUT`、`DELETE`、等。对于非 HTTP(S) URL 被忽略。

`url`

一个 `DOMString` 表示要向其发送请求的 URL。

`async` 可选

一个可选的布尔参数，表示是否异步执行操作，默认为 `true`。如果值为 `false`，`send()` 方法直到收到答复前不会返回。如果 `true`，已完成事务的通知可供事件监听器使用。如果 `multipart` 属性为 `true` 则这个必须为 `true`，否则将引发异常。

**备注：** 主线程上的同步请求很容易破坏用户体验，应该避免；实际上，许多浏览器已完全弃用主线程上的同步 XHR 支持。在 `Worker` 中允许同步请求

`user` 可选

可选的用户名用于认证用途；默认为 `null`。

`password` 可选

可选的密码用于认证用途，默认为 `null`。

规格
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-open()-method |

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

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

参见
--

使用 XMLHttpRequest


timeout - Web API 接口参考

timeout
=======

当进度由于预定时间到期而终止时，会触发 `timeout` 事件。

|  |  |
| --- | --- |
| 冒泡 | 否 |
| 可取消 | 否 |
| 目标对象 | `XMLHttpRequest` |
| 接口 | `ProgressEvent` |

示例
--

```js
var client = new XMLHttpRequest();
client.open("GET", "http://www.example.org/example.txt");
client.ontimeout = function (e) {
  console.error("Timeout!!");
};
client.send();
```

继承
--

`timeout` 事件实现了 `ProgressEvent` 接口，它继承自 `Event` — 它拥有在这个接口上定义的属性和方法。

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # event-xhr-timeout |
| XMLHttpRequest Standard # handler-xhr-ontimeout |

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

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

参见
--

* XMLHttpRequest


XMLHttpRequest: abort event - Web API 接口参考

XMLHttpRequest: abort event
===========================

当一个请求终止时 `abort` 事件被触发，比如程序执行 `XMLHttpRequest.abort()`。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `ProgressEvent` |
| Event handler property | `onabort` |

示例
--

### 在线示例

#### HTML

```html
<div class="controls">
  <input
 class="xhr success"
 type="button"
 name="xhr"
 value="Click to start XHR (success)" />
  <input
 class="xhr error"
 type="button"
 name="xhr"
 value="Click to start XHR (error)" />
  <input
 class="xhr abort"
 type="button"
 name="xhr"
 value="Click to start XHR (abort)" />
</div>

<textarea readonly class="event-log"></textarea>
```

```
.event-log {
  width: 25rem;
  height: 4rem;
  border: 1px solid black;
  margin: 0.5rem;
  padding: 0.2rem;
}

input {
  width: 11rem;
  margin: 0.5rem;
}
```

#### JS

```js
const xhrButtonSuccess = document.querySelector(".xhr.success");
const xhrButtonError = document.querySelector(".xhr.error");
const xhrButtonAbort = document.querySelector(".xhr.abort");
const log = document.querySelector(".event-log");

function handleEvent(e) {
  log.textContent =
    log.textContent + `${e.type}: ${e.loaded} bytes transferred\n`;
}

function addListeners(xhr) {
  xhr.addEventListener("loadstart", handleEvent);
  xhr.addEventListener("load", handleEvent);
  xhr.addEventListener("loadend", handleEvent);
  xhr.addEventListener("progress", handleEvent);
  xhr.addEventListener("error", handleEvent);
  xhr.addEventListener("abort", handleEvent);
}

function runXHR(url) {
  log.textContent = "";

  const xhr = new XMLHttpRequest();
  addListeners(xhr);
  xhr.open("GET", url);
  xhr.send();
  return xhr;
}

xhrButtonSuccess.addEventListener("click", () => {
  runXHR("dgszyjnxcaipwzy.jpg");
});

xhrButtonError.addEventListener("click", () => {
  runXHR("https://somewhere.org/i-dont-exist");
});

xhrButtonAbort.addEventListener("click", () => {
  runXHR("dgszyjnxcaipwzy.jpg").abort();
});
```

#### 结果

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # event-xhr-abort |
| XMLHttpRequest Standard # handler-xhr-onabort |

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

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

参见
--

* 相关事件：`loadstart`、`load`、`progress`、`error`、`loadend`
* 监测进度


XMLHttpRequest.responseType - Web API 接口参考

XMLHttpRequest.responseType
===========================

`XMLHttpRequest` 属性 **`responseType`** 是一个枚举字符串值，用于指定响应中包含的数据类型。

它还允许作者更改响应类型。如果将 `responseType` 的值设置为空字符串，则会使用 `text` 作为默认值。

语法
--

```js
var type = XMLHttpRequest.responseType;

XMLHttpRequest.responseType = type;
```

### 值

`Global_Objects/String` 类型的值，指定响应包含的数据类型。它可以采用以下值：

`""`

空的 `responseType` 字符串与默认类型 `"text"` 相同。

`"arraybuffer"`

`response` 是一个包含二进制数据的 JavaScript `ArrayBuffer`。

`"blob"`

`response` 是一个包含二进制数据的 `Blob` 对象。

`"document"`

`response` 是一个 HTML `Document` 或 XML `XMLDocument`，根据接收到的数据的 MIME 类型而定。请参阅 XMLHttpRequest 中的 HTML，了解有关使用 XHR 获取 HTML 内容的更多信息。

`"json"`

`response` 是通过将接收到的数据内容解析为 JSON 而创建的 JavaScript 对象。

`"text"`

`response` 是 `DOMString` 对象中的文本。

`"ms-stream"`
非标准

`response` 是流式下载的一部分；此响应类型仅允许用于下载请求，并且仅受 Internet Explorer 支持。

**备注：** 将 `responseType` 设置为特定值时，作者应确保服务器实际发送的响应与该格式兼容。如果服务器返回的数据与设置的 `responseType` 不兼容，则 `response` 的值将为`null` .

### 异常

`InvalidAccessError`

试图更改 `XMLHttpRequest` 的 `responseType`，该值处于同步模式但不在 `Worker` 中。有关其他详细信息，请参阅下面的 同步 XHR 限制。

使用说明
----

### 同步 XHR 限制

你不能在同步`XMLHttpRequest` 中更改 `responseType` 的值，除非请求属于 `Worker`。此限制部分旨在帮助确保同步操作不会用于阻塞浏览器主线程的大型事务，从而阻碍用户体验。

XHR 请求默认是异步的；它们仅通过在调用 `open()` 时将 `false` 作为可选`async` 参数的值传递来置于同步模式。

### Worker 中的限制

在 `Worker` 中尝试将 `responseType` 的值设置为 `document` 时会被忽略。

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-responsetype-attribute |

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

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

参见
--

* 使用 XMLHttpRequest
* XMLHttpRequest 中的 HTML
* 响应数据：`response`、
 `responseText` 和 `responseXML`


XMLHttpRequest.abort() - Web API 接口参考

XMLHttpRequest.abort()
======================

如果该请求已被发出，**XMLHttpRequest.abort()** 方法将终止该请求。当一个请求被终止，它的 `readyState` 将被置为 `XMLHttpRequest.UNSENT` (0)，并且请求的 `status` 置为 0。

语法
--
```

xhrInstance.abort();
```

### 参数

无。

### 返回值

`undefined`

示例
--

```js
var xhr = new XMLHttpRequest(),
  method = "GET",
  url = "https://developer.mozilla.org/";
xhr.open(method, url, true);

xhr.send();

if (OH\_NOES\_WE\_NEED\_TO\_CANCEL\_RIGHT\_NOW\_OR\_ELSE) {
  xhr.abort();
}
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-abort()-method |

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

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

参见
--

* 使用 XMLHttpRequest


XMLHttpRequest() - Web API 接口参考

XMLHttpRequest()
================

The **`XMLHttpRequest()`** 构造器初始化一个新的 `XMLHttpRequest` 对象。

关于 `XMLHttpRequest` 的具体用法，请参考使用 XMLHttpRequest。

语法
--

```js
new XMLHttpRequest()
```

### 参数

无。

### 返回值

一个新的 `XMLHttpRequest` 对象。此对象 must be prepared by at least calling `open()` to initialize it before calling `send()` to send the request to the server.

非标准 Firefox 语法
--------------

Firefox 16 added a non-standard parameter to the constructor that can enable anonymous mode (see Firefox bug 692677). Setting the `mozAnon` flag to `true` effectively resembles the `AnonXMLHttpRequest()` constructor described in older versions of the XMLHttpRequest specification.

Gecko/Firefox 16 为该构造方法新增了一个非标准的参数，以启用匿名模式（参见 Firefox bug 692677）。将 `mozAnon` 属性设置为 `true`，即可有效地模拟 `AnonXMLHttpRequest()` 构造器。此构造器在早先的 XMLHttpRequest 规范中有描述，但并未在任何浏览器中被实现。
```

const request = new XMLHttpRequest(paramsDictionary);
```

### 参数（非标准）

`objParameters`

有两个属性可以设置：

`mozAnon`

布尔值：将此属性设置为 `true` 将使浏览器在获取资源时不暴露自身来源和用户凭据。最重要的是，这意味着只有明确添加使用 setRequestHeader 才会发送 Cookies。

`mozSystem`

布尔值：将此属性设置为 `true` 允许建立跨站点的连接，而无需服务器选择使用 CORS\*（译者注：Cross-Origin Resource Sharing 跨域资源共享）\*。*必须同时将参数* `mozAnon` *设置为* `true`，*即不能与 Cookie 或其他用户凭据同时发送。仅限于在 privileged (reviewed) apps 起效（译者注：此句原文 This only works in privileged (reviewed) apps;）；在 Firefox 上任何网页加载后不起作用（译者注：此句原文 it does not work on arbitrary webpages loaded in Firefox.）。*

参见
--

* 使用 XMLHttpRequest
* XMLHttpRequest 中的 HTML


XMLHttpRequest.mozBackgroundRequest - Web API 接口参考

XMLHttpRequest.mozBackgroundRequest
===================================

**备注：** Web 内容无法使用此方法。它需要提升权限才能访问。

**`XMLHttpRequest.mozBackgroundRequest`** 是一个布尔对象，表示 `object` 是否为后台的服务请求。如果为 `true`，则不会将任何加载组与请求关联，并且不会向用户显示安全对话框。

请求失败时通常会显示安全对话框（例如身份验证或错误证书通知）。

**备注：** 该属性必须在调用 `open()` 之前设置。


XMLHttpRequest.getAllResponseHeaders() - Web API 接口参考

XMLHttpRequest.getAllResponseHeaders()
======================================

**XMLHttpRequest.getAllResponseHeaders()** 方法返回所有的响应头，以 CRLF 分割的字符串，或者 `null` 如果没有收到任何响应。 **注意：** 对于复合请求（multipart requests），这个方法返回当前请求的头部，而不是最初的请求的头部。
```

DOMString getAllResponseHeaders();
```

语法
--
```

var headers = XMLHttpRequest.getAllResponseHeaders();
```

### 参数

无

### 返回值

一个原始的 Header 头例子：
```

date: Fri, 08 Dec 2017 21:04:30 GMT\r\n
content-encoding: gzip\r\n
x-content-type-options: nosniff\r\n
server: meinheld/0.6.1\r\n
x-frame-options: DENY\r\n
content-type: text/html; charset=utf-8\r\n
connection: keep-alive\r\n
strict-transport-security: max-age=63072000\r\n
vary: Cookie, Accept-Encoding\r\n
content-length: 6502\r\n
x-xss-protection: 1; mode=block\r\n
```

每一行通过\r\n 来进行分割。

例子
--
```

var request = new XMLHttpRequest();
request.open("GET", "foo.txt", true);
request.send();

request.onreadystatechange = function() {
  if(this.readyState == this.HEADERS_RECEIVED) {

    // Get the raw header string
    var headers = request.getAllResponseHeaders();

    // Convert the header string into an array
    // of individual headers
    var arr = headers.trim().split(/[\r\n]+/);

    // Create a map of header names to values
    var headerMap = {};
    arr.forEach(function (line) {
      var parts = line.split(': ');
      var header = parts.shift();
      var value = parts.join(': ');
      headerMap[header] = value;
    });
  }
```

上面的代码执行后，你可以：
```

var contentType = headerMap["content-type"];
```

上面的变量 `contentType` 可以获取到 HTTP header 里的 `content-type` 字段值。


XMLHttpRequest.statusText - Web API 接口参考

XMLHttpRequest.statusText
=========================

只读属性 **`XMLHttpRequest.statusText`** 返回了`XMLHttpRequest` 请求中由服务器返回的一个`DOMString` 类型的文本信息，这则信息中也包含了响应的数字状态码。不同于使用一个数字来指示的状态码`XMLHTTPRequest.status`，这个属性包含了返回状态对应的文本信息，例如"OK"或是"Not Found"。如果请求的状态`readyState`的值为"UNSENT"或者"OPENED"，则这个属性的值将会是一个空字符串。如果服务器未明确指定一个状态文本信息，则`statusText`的值将会被自动赋值为"OK"。例子
--

```js
var xhr = new XMLHttpRequest();
console.log("0 UNSENT", xhr.statusText);

xhr.open("GET", "/server", true);
console.log("1 OPENED", xhr.statusText);

xhr.onprogress = function () {
  console.log("3 LOADING", xhr.statusText);
};

xhr.onload = function () {
  console.log("4 DONE", xhr.statusText);
};

xhr.send(null);

/\*\*
 \* 输出如下：
 \*
 \* 0 UNSENT
 \* 1 OPENED
 \* 3 LOADING OK
 \* 4 DONE OK
 \*/
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-statustext-attribute |

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

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

参考内容
----

* List of HTTP response codes
* HTTP


XMLHttpRequest.mozAnon - Web API 接口参考

XMLHttpRequest.mozAnon
======================

**`XMLHttpRequest.mozAnon`** 是布尔类型。如果这个变量为真，则这次请求将不携带 Cookies 或头部认证信息来发送。


XMLHttpRequest.readyState - Web API 接口参考

XMLHttpRequest.readyState
=========================

**XMLHttpRequest.readyState** 属性返回一个 XMLHttpRequest 代理当前所处的状态。一个 XHR 代理总是处于下列状态中的一个：

| 值 | 状态 | 描述 |
| --- | --- | --- |
| `0` | `UNSENT` | 代理被创建，但尚未调用 open() 方法。 |
| `1` | `OPENED` | `open()` 方法已经被调用。 |
| `2` | `HEADERS_RECEIVED` | `send()` 方法已经被调用，并且头部和状态已经可获得。 |
| `3` | `LOADING` | 下载中；`responseText` 属性已经包含部分数据。 |
| `4` | `DONE` | 下载操作已完成。 |

UNSENT

XMLHttpRequest 代理已被创建，但尚未调用 open() 方法。

OPENED

open() 方法已经被触发。在这个状态中，可以通过 setRequestHeader() 方法来设置请求的头部，可以调用 send() 方法来发起请求。

HEADERS\_RECEIVED

send() 方法已经被调用，响应头也已经被接收。

LOADING

响应体部分正在被接收。如果 `responseType` 属性是“text”或空字符串，`responseText` 将会在载入的过程中拥有部分响应数据。

DONE

请求操作已经完成。这意味着数据传输已经彻底完成或失败。

**备注：** 在 IE 中，状态有着不同的名称，并不是 `UNSENT`，`OPENED` ，`HEADERS_RECEIVED` ，`LOADING` 和 `DONE`，而是 `READYSTATE_UNINITIALIZED` (0)，`READYSTATE_LOADING` (1) ，`READYSTATE_LOADED` (2) ，`READYSTATE_INTERACTIVE` (3) `和 READYSTATE_COMPLETE` (4) 。

示例
--

```js
var xhr = new XMLHttpRequest();
console.log("UNSENT", xhr.readyState); // readyState 为 0

xhr.open("GET", "/api", true);
console.log("OPENED", xhr.readyState); // readyState 为 1

xhr.onprogress = function () {
  console.log("LOADING", xhr.readyState); // readyState 为 3
};

xhr.onload = function () {
  console.log("DONE", xhr.readyState); // readyState 为 4
};

xhr.send(null);
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # states |

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

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


progress 事件 - Web API 接口参考

progress 事件
===========

**`progress`** 事件会在请求接收到数据的时候被周期性触发。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `ProgressEvent` |
| Event handler property | `onprogress` |

示例
--

### 在线示例

#### HTML

```html
<div class="controls">
  <input
 class="xhr success"
 type="button"
 name="xhr"
 value="Click to start XHR (success)" />
  <input
 class="xhr error"
 type="button"
 name="xhr"
 value="Click to start XHR (error)" />
  <input
 class="xhr abort"
 type="button"
 name="xhr"
 value="Click to start XHR (abort)" />
</div>

<textarea readonly class="event-log"></textarea>
```

```
.event-log {
  width: 25rem;
  height: 4rem;
  border: 1px solid black;
  margin: 0.5rem;
  padding: 0.2rem;
}

input {
  width: 11rem;
  margin: 0.5rem;
}
```

#### JS

```js
const xhrButtonSuccess = document.querySelector(".xhr.success");
const xhrButtonError = document.querySelector(".xhr.error");
const xhrButtonAbort = document.querySelector(".xhr.abort");
const log = document.querySelector(".event-log");

function handleEvent(e) {
  log.textContent =
    log.textContent + `${e.type}: ${e.loaded} bytes transferred\n`;
}

function addListeners(xhr) {
  xhr.addEventListener("loadstart", handleEvent);
  xhr.addEventListener("load", handleEvent);
  xhr.addEventListener("loadend", handleEvent);
  xhr.addEventListener("progress", handleEvent);
  xhr.addEventListener("error", handleEvent);
  xhr.addEventListener("abort", handleEvent);
}

function runXHR(url) {
  log.textContent = "";

  const xhr = new XMLHttpRequest();
  addListeners(xhr);
  xhr.open("GET", url);
  xhr.send();
  return xhr;
}

xhrButtonSuccess.addEventListener("click", () => {
  runXHR("dgszyjnxcaipwzy.jpg");
});

xhrButtonError.addEventListener("click", () => {
  runXHR("https://somewhere.org/i-dont-exist");
});

xhrButtonAbort.addEventListener("click", () => {
  runXHR("dgszyjnxcaipwzy.jpg").abort();
});
```

#### 结果

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # event-xhr-progress |
| XMLHttpRequest Standard # handler-xhr-onprogress |

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

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

参见
--

* 相关事件：`loadstart`、`load`、`loadend`、`error`、`abort`
* 监测进度


XMLHttpRequest.channel - Web API 接口参考

XMLHttpRequest.channel
======================

创建请求的时候，XMLHttpRequest.channel 是一个被对象使用的 `nsIChannel`。如果管道（channel）还没被创建的话，它的值是 `null`。在一个 multi-part 请求案例中，它是初始化的管道，不是 multi-part 请求中的不同部分。

**需要权限提升。**


XMLHttpRequest.responseXML - Web API 接口参考

XMLHttpRequest.responseXML
==========================

**XMLHttpRequest.responseXML** 属性是一个只读值，它返回一个包含请求检索的 HTML 或 XML 的`Document`，如果请求未成功，尚未发送，或者检索的数据无法正确解析为 XML 或 HTML，则为 null。默认是当作“text / xml”来解析。当 `responseType` 设置为“document”并且请求已异步执行时，响应将被当作“text / html”来解析。`responseXML` 对于任何其他类型的数据以及 `data:` URLs 为 null。

**备注：** `responseXML` 在这个属性的历史堪称神器，它可以同时在 HTML 和 XML 中工作

如果服务器没有明确指出 `Content-Type` 头是 `"text/xml"` 还是 `"application/xml"`, 你可以使用`XMLHttpRequest.overrideMimeType()` 强制 `XMLHttpRequest` 解析为 XML。

语法
--
```

var data = XMLHttpRequest.responseXML;
```

### 值

`Document` 中包含从 `XMLHttpRequest` 中收到的 HTML 节点或解析后的 XML 节点，也可能是在没有收到任何数据或数据类型错误的情况下返回的 null。

### 例外

`InvalidStateError`

`responseType` 既不是 `"document"` 也不是空字符串 (接收的数据应是 XML 或 HTML)。

示例
--

```js
var xhr = new XMLHttpRequest();
xhr.open("GET", "/server", true);

// 如果已指明，responseType 必须是空字符串或 "document"
xhr.responseType = "document";

// overrideMimeType() 用来强制解析 response 为 XML
xhr.overrideMimeType("text/xml");

xhr.onload = function () {
  if (xhr.readyState === xhr.DONE) {
    if (xhr.status === 200) {
      console.log(xhr.response);
      console.log(xhr.responseXML);
    }
  }
};

xhr.send(null);
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-responsexml-attribute |

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

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

了解更多
----

* `XMLHttpRequest`
* `XMLHttpRequest.response`
* `XMLHttpRequest.responseType`


XMLHttpRequest.mozSystem - Web API 接口参考

XMLHttpRequest.mozSystem
========================

**`mozSystem`** is a boolean. If true, the same origin policy is not enforced on the request.

mozSystem 是一个布尔值。如果它被设置为 true，那么在请求时就不会强制要求执行同源策略（Same Origin Policy）。


XMLHttpRequest.overrideMimeType() - Web API 接口参考

XMLHttpRequest.overrideMimeType()
=================================

XMLHttpRequest 的 **`overrideMimeType`** 方法是指定一个 MIME 类型用于替代服务器指定的类型，使服务端响应信息中传输的数据按照该指定 MIME 类型处理。例如强制使流方式处理为"text/xml"类型处理时会被使用到，即使服务器在响应头中并没有这样指定。此方法必须在 send 方法之前调用方为有效。

Syntax
------
```

XMLHttpRequest.overrideMimeType(mimeType)
```

### Parameters

`mimeType`

一个 `DOMString` 指定具体的 MIME 类型去代替有服务器指定的 MIME 类型。如果服务器没有指定类型，那么 `XMLHttpRequest` 将会默认为 `"text/xml"`.

### Return value

`undefined`.

Example
-------

这个样例指定 Content-Type 为“text/plain",为接受的数据重写 ContentType

**备注：** 如果服务器没有指定一个`Content-Type` 头，`XMLHttpRequest` 默认 MIME 类型为`"text/xml"`. 如果接受的数据不是有效的 XML，将会出现格”格式不正确“的错误。你能够通过调用 `overrideMimeType()` 指定各种类型来避免这种情况。

```js
// Interpret the received data as plain text

req = new XMLHttpRequest();
req.overrideMimeType("text/plain");
req.addEventListener("load", callback, false);
req.open("get", url);
req.send();
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-overridemimetype()-method |

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

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

参见
--

* 使用 XMLHttpRequest
* `XMLHttpRequest.responseType`


XMLHttpRequest.onreadystatechange - Web API 接口参考

XMLHttpRequest.onreadystatechange
=================================

只要 `readyState` 属性发生变化，就会调用相应的处理函数 (en-US)。这个回调函数会被用户线程所调用。**`XMLHttpRequest.onreadystatechange`** 会在 `XMLHttpRequest` 的`readyState` 属性发生改变时触发 `readystatechange` 事件的时候被调用。

**警告：** 这个方法不该用于同步的 requests 对象，并且不能在内部 (C++) 代码中使用。

当一个 `XMLHttpRequest` 请求被 abort() 方法取消时，其对应的 `readystatechange` 事件不会被触发。

**备注：** UPDATE: 在下面的浏览器版本中会触发 (Firefox 51.0.1, Opera 43.0.2442.991, Safari 10.0.3 (12602.4.8), Chrome 54.0.2840.71, Edge, IE11). 例子在 here - 重新加载几次页面即可。

语法
--
```

XMLHttpRequest.onreadystatechange = callback;
```

### 取值

* 当 `readyState` 的值改变的时候，`callback` 函数会被调用。
示例
--

```js
var xhr = new XMLHttpRequest(),
  method = "GET",
  url = "https://developer.mozilla.org/";

xhr.open(method, url, true);
xhr.onreadystatechange = function () {
  if (xhr.readyState === XMLHttpRequest.DONE && xhr.status === 200) {
    console.log(xhr.responseText);
  }
};
xhr.send();
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # event-xhr-readystatechange |
| XMLHttpRequest Standard # handler-xhr-onreadystatechange |

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

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


XMLHttpRequest.status - Web API 接口参考

XMLHttpRequest.status
=====================

只读属性 **`XMLHttpRequest.status`** 返回了 `XMLHttpRequest` 响应中的数字状态码。`status` 的值是一个`无符号短整型`。在请求完成前，`status` 的值为 `0`。值得注意的是，如果 XMLHttpRequest 出错，浏览器返回的 status 也为 0。status 码是标准的 HTTP status codes。举个例子，`status` `200` 代表一个成功的请求。如果服务器响应中没有明确指定 status 码，`XMLHttpRequest.status` 将会默认为 `200`。例子
--

```js
var xhr = new XMLHttpRequest();
console.log("UNSENT", xhr.status);

xhr.open("GET", "/server", true);
console.log("OPENED", xhr.status);

xhr.onprogress = function () {
  console.log("LOADING", xhr.status);
};

xhr.onload = function () {
  console.log("DONE", xhr.status);
};

xhr.send(null);

/\*\*
 \* 输出如下：
 \*
 \* UNSENT（未发送）0
 \* OPENED（已打开）0
 \* LOADING（载入中）200
 \* DONE（完成）200
 \*/
```

规范
--

| Specification |
| --- |
| XMLHttpRequest Standard # the-status-attribute |

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

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

其他相关资料
------

* HTTP 响应代码（HTTP response codes）列表
* HTTP


DecompressionStream.readable - Web API 接口参考

DecompressionStream.readable
============================

`DecompressionStream` 接口的 **`readable`** 只读属性返回 `ReadableStream`。

值
-

一个 `ReadableStream`。

示例
--

以下示例从 `DecompressionStream` 返回 `ReadableStream`。

```js
let stream = new DecompressionStream("gzip");
console.log(stream.readable); //一个 ReadableStream
```

规范
--

| Specification |
| --- |
| Streams Standard # dom-generictransformstream-readable |

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

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


DecompressionStream.writable - Web API 接口参考

DecompressionStream.writable
============================

`DecompressionStream` 接口的 **`writable`** 属性返回 `WritableStream`。

值
-

一个 `WritableStream`。

示例
--

以下示例从 `DecompressionStream` 返回 `WritableStream`。

```js
let stream = new DecompressionStream("gzip");
console.log(stream.writeable); //一个 WritableStream
```

规范
--

| Specification |
| --- |
| Streams Standard # dom-generictransformstream-writable |

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

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


DecompressionStream() - Web API 接口参考

DecompressionStream()
=====================

**`DecompressionStream()`** 构造函数创建一个新的 `DecompressionStream`，该对象用于解压数据流。

语法
--

```js
new DecompressionStream(format)
```

### 参数

`format`

以下允许的解压格式之一：

* `"gzip"`
* `"deflate"`
* `"deflate-raw"`

异常
--

`TypeError`

如果传递给构造函数的格式是不支持的则抛出。

示例
--

在此示例中，使用 gzip 对 blob 解压缩。

```js
const ds = new DecompressionStream("gzip");
const decompressedStream = blob.stream().pipeThrough(ds);
```

规范
--

| Specification |
| --- |
| Compression Streams # dom-decompressionstream-decompressionstream |

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

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


FileSystemHandle：requestPermission() 方法 - Web API 接口参考

FileSystemHandle：requestPermission() 方法
=======================================

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

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

`FileSystemHandle` 接口的 **`queryPermission()`** 方法用于为文件句柄请求读取或读写权限。

语法
--

```js
requestPermission(fileSystemHandlePermissionDescriptor)
```

### 参数

FileSystemHandlePermissionDescriptor 可选

一个对象，指定需要查询的权限模式，包含以下选项：

* `'mode'`：可以是 `'read'` 或 `'readwrite'`。

### 返回值

`PermissionStatus.state` (en-US)，值为 `'granted'`、`'denied'` 或 `'prompt'` 三者之一。

### 异常

`TypeError`

如果没有指定参数或者 `mode` 的值不是 `'read'` 或 `'readwrite'`，则抛出此异常。

示例
--

以下异步函数会在句柄没有获得授权时请求权限。

```js
// fileHandle 是一个 FileSystemFileHandle
// withWrite 是一个布尔值，如果要求写入则需传入 true

async function verifyPermission(fileHandle, withWrite) {
  const opts = {};
  if (withWrite) {
    opts.mode = "readwrite";
  }

  // 检查是否已经拥有相应权限，如果是，返回 true。
  if ((await fileHandle.queryPermission(opts)) === "granted") {
    return true;
  }

  // 为文件请求权限，如果用户授予了权限，返回 true。
  if ((await fileHandle.requestPermission(opts)) === "granted") {
    return true;
  }

  // 用户没有授权，返回 false。
  return false;
}
```

规范
--

| Specification |
| --- |
| File System Access # api-filesystemhandle-requestpermission |

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

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

参见
--

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