recursal/MDN huggingface dataset:
AsyncGeneratorFunction() 构造函数
=============================

**`AsyncGeneratorFunction()`** 构造函数创建 `AsyncGeneratorFunction` 对象。

注意，`AsyncGeneratorFunction` 不是全局对象。它可以通过执行以下代码获取。


```js
const AsyncGeneratorFunction = async function\* () {}.constructor;
```


`AsyncGeneratorFunction()` 构造函数不应直接使用，并且所有在 `Function()` 的描述中提到的注意事项也适用于 `AsyncGeneratorFunction()`。

语法
--


```js
new AsyncGeneratorFunction(functionBody)
new AsyncGeneratorFunction(arg1, functionBody)
new AsyncGeneratorFunction(arg1, arg2, functionBody)
new AsyncGeneratorFunction(arg1, arg2, /\* …, \*/ argN, functionBody)

AsyncGeneratorFunction(functionBody)
AsyncGeneratorFunction(arg1, functionBody)
AsyncGeneratorFunction(arg1, arg2, functionBody)
AsyncGeneratorFunction(arg1, arg2, /\* …, \*/ argN, functionBody)
```


**备注：** 无论是否使用 `new` 调用 `AsyncGeneratorFunction()`，都可以创建一个新的 `AsyncGeneratorFunction` 实例。

### 参数

参见 `Function()`。

示例
--

### 使用构造函数

以下示例使用 `AsyncGeneratorFunction` 构造函数创建一个异步生成器函数。


```js
const AsyncGeneratorFunction = async function\* () {}.constructor;
const createAsyncGenerator = new AsyncGeneratorFunction("a", "yield a \* 2");
const asyncGen = createAsyncGenerator(10);
asyncGen.next().then((res) => console.log(res.value)); // 20
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-asyncgeneratorfunction-constructor |

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

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

参见
--

* `async function*`
* `async function*` 表达式
* `Function()` 构造函数
* 迭代器和生成器指南
* 函数
SharedArrayBuffer.prototype.maxByteLength
=========================================

`SharedArrayBuffer` 实例的 **`maxByteLength`** 访问器属性返回当前 `SharedArrayBuffer` 可以增大到的最大长度（以字节为单位）。

描述
--

`maxByteLength` 属性是一个访问器属性，其设置访问器函数为 `undefined`，因此你只能读取该属性。该属性的值在构造数组时确定。通过 `SharedArrayBuffer()` 构造函数的 `maxByteLength` 选项来设置该值，并且无法更改。

如果当前 `SharedArrayBuffer` 构造时时没有指定 `maxByteLength` 的值，这个属性会返回一个等于 `SharedArrayBuffer` 的 `byteLength` 属性值的数值。

示例
--

### 使用 maxByteLength

在这个示例中，我们创建一个 8 字节缓冲区，该缓冲区可调整到的最大长度是 16 字节，然后返回其 `maxByteLength`：


```js
const buffer = new SharedArrayBuffer(8, { maxByteLength: 16 });

buffer.maxByteLength; // 16
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-sharedarraybuffer.prototype.maxbytelength |

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

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

参见
--

* `SharedArrayBuffer`
SharedArrayBuffer.prototype.grow()
==================================

`SharedArrayBuffer` 实例的 **`grow()`** 方法将 `SharedArrayBuffer` 增大到以字节为单位的指定大小。

语法
--


```js
grow(newLength)
```

### 参数

`newLength`

新的长度，以字节为单位，`SharedArrayBuffer` 调整后的大小。

### 返回值

无（`undefined`）。

### 异常

`TypeError`

如果当前的 `SharedArrayBuffer` 不可增大，则抛出该异常。

`RangeError`

如果 `newLength` 大于当前 `SharedArrayBuffer` 的 `maxByteLength` 或小于 `byteLength`，则抛出该异常。

描述
--

`grow()` 方将 `SharedArrayBuffer` 增大到 `newLength` 参数指定的大小，前提是 `SharedArrayBuffer` 是可增大的，并且新的大小小于等于当前 `SharedArrayBuffer` 的 `maxByteLength`。新字节被初始化为 0。

示例
--

### 使用 grow()

在这个示例中，我们创建一个 8 字节缓冲区，该缓冲区可调整大小到的最大长度是 16 字节，然后检查其 `growable` 属性，如果 `growable` 返回 `true`，则将其增大：


```js
const buffer = new SharedArrayBuffer(8, { maxByteLength: 16 });

if (buffer.growable) {
  console.log("SAB 是可增大的！");
  buffer.grow(12);
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-sharedarraybuffer.prototype.grow |

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

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

参见
--

* `SharedArrayBuffer`
* `SharedArrayBuffer.prototype.growable`
* `SharedArrayBuffer.prototype.maxByteLength`
SharedArrayBuffer.prototype.byteLength
======================================

`SharedArrayBuffer` 实例的 **`byteLength`** 访问器属性返回该 `SharedArrayBuffer` 的大小（以字节为单位）。

尝试一下
----

描述
--

`byteLength` 属性是一个访问器属性，它的设置访问器函数为 `undefined`，这意味着你只能读取该属性。该值在创建共享数组时就确定了，不能更改。

示例
--

### 使用 byteLength


```js
const sab = new SharedArrayBuffer(1024);
sab.byteLength; // 1024
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-sharedarraybuffer.prototype.bytelength |

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

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

参见
--

* `SharedArrayBuffer`
SharedArrayBuffer.prototype.slice()
===================================

`SharedArrayBuffer` 实例的 **`slice()`** 方法返回一个新的 `SharedArrayBuffer`，其包含当前 `SharedArrayBuffer` 从 `start` 开始（包含）到 `end` 结束（不含）的字节内容的副本。如果 `start` 或 `end` 为负数，则表示从数组末尾开始计数的索引，即与从开头开始的方向相反。

尝试一下
----

语法
--


```js
slice()
slice(start)
slice(start, end)
```

### 参数

`start` 可选

要开始提取的位置索引（从 0 开始），将被转换为整数。

* 负数索引将会从缓冲区末尾开始计算——如果 `start < 0`，那么将会使用 `start + buffer.length`。
* 如果 `start < -buffer.length` 或省略了 `start`，则会使用 `0`。
* 如果 `start >= buffer.length`，则不会提取任何内容。

`end` 可选

要结束提取的位置索引（从 0 开始），将被转换为整数。`slice()` 提取到但不包括 `end`。

* 负数索引将会从缓冲区末尾开始计算——如果 `end < 0`，那么将会使用 `end + buffer.length`。
* 如果 `end < -buffer.length`，则会使用 `0`。
* 如果 `end >= buffer.length` 或省略了 `end`，则会使用 `buffer.length`，则会导致直到末尾的所有元素都被提取。
* 如果标准化后的 `end` 位置在 `start` 位置之前，则不会提取任何内容。

### 返回值

一个新的 `SharedArrayBuffer`，包含提取的元素。

示例
--

### 使用 slice()


```js
const sab = new SharedArrayBuffer(1024);
sab.slice(); // SharedArrayBuffer { byteLength: 1024 }
sab.slice(2); // SharedArrayBuffer { byteLength: 1022 }
sab.slice(-2); // SharedArrayBuffer { byteLength: 2 }
sab.slice(0, 1); // SharedArrayBuffer { byteLength: 1 }
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-sharedarraybuffer.prototype.slice |

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

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

参见
--

* `SharedArrayBuffer`
* `ArrayBuffer.prototype.slice()`
SharedArrayBuffer[@@species]
============================

**`SharedArrayBuffer[@@species]`** 静态访问器属性返回用于构造 `SharedArrayBuffer` 方法返回值的构造函数。

**警告：** `@@species` 的存在允许任意代码的执行，这可能导致安全漏洞。它还使某些优化变得更加困难。引擎实现者正在调查是否要移除此特性。如果可能，请避免依赖它。

语法
--


```js
SharedArrayBuffer[Symbol.species]
```

### 返回值

调用 `get @@species` 构造函数（`this`）的值。返回值用于构造创建新数组缓冲区的数组缓冲区方法的返回值。

描述
--

`@@species` 访问器属性返回 `SharedArrayBuffer` 对象的构造函数。子类构造函数可以重写它来改变构造函数赋值。默认实现大概是：


```js
// 用于说明而假设的底层实现
class SharedArrayBuffer {
  static get [Symbol.species]() {
    return this;
  }
}
```


由于这种多态实现，默认情况下，派生子类的 `@@species` 也会返回自身的构造函数。


```js
class SubArrayBuffer extends SharedArrayBuffer {}
SubArrayBuffer[Symbol.species] === SharedArrayBuffer; // true
```


在调用不会更改现有数组，而是返回一个新的数组缓冲实例的方法（例如，`slice()`）时，该数组的 `constructor[@@species]` 会被访问。返回的构造函数将被用于构造该数组缓冲区方法的返回值。

示例
--

### 普通对象中的 species

`@@species` 属性返回默认的构造函数，即 `SharedArrayBuffer` 的构造函数 `SharedArrayBuffer`。


```js
SharedArrayBuffer[Symbol.species]; // function SharedArrayBuffer()
```

### 派生对象中的 species

在自定义的 `SharedArrayBuffer` 子类实例中，例如 `MySharedArrayBuffer`，`MySharedArrayBuffer` 的 species 是 `MySharedArrayBuffer` 构造函数。但是，你可能希望重写它，以便在派生类方法中返回父类 `SharedArrayBuffer` 对象：


```js
class MySharedArrayBuffer extends SharedArrayBuffer {
  // 重写 MySharedArrayBuffer species 来返回父类 SharedArrayBuffer 构造函数
  static get [Symbol.species]() {
    return SharedArrayBuffer;
  }
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-sharedarraybuffer-@@species |

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

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

参见
--

* `SharedArrayBuffer`
* `Symbol.species`
SharedArrayBuffer.prototype.growable
====================================

`SharedArrayBuffer` 实例的 **`growable`** 访问器属性返回该 `SharedArrayBuffer` 是否可增大。

描述
--

`growable` 属性是一个访问器属性，其设置访问器函数为 `undefined`，因此你只能读取该属性。该属性的值在构造数组时确定。如果在构造函数中 `maxByteLength` 选项被设置，`growable` 将返回 `true`；否则，它将返回 `false`。

示例
--

### 使用 growable

在这个示例中，我们创建一个 8 字节缓冲区，该缓冲区可调整大小到的最大长度是 16 字节，然后检查其 `growable` 属性，如果 `growable` 返回 `true`，则增大它：


```js
const buffer = new SharedArrayBuffer(8, { maxByteLength: 16 });

if (buffer.growable) {
  console.log("SAB 是可增大的！");
  buffer.grow(12);
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-sharedarraybuffer.prototype.growable |

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

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

参见
--

* `SharedArrayBuffer`
* `SharedArrayBuffer.prototype.grow()`
* `SharedArrayBuffer.prototype.maxByteLength`
SharedArrayBuffer() 构造函数
========================

**备注：** `SharedArrayBuffer` 构造函数可能并不总是全局可用的，除非满足某些安全要求。

**`SharedArrayBuffer()`** 构造函数创建 `SharedArrayBuffer` 对象。

尝试一下
----

语法
--


```js
new SharedArrayBuffer(length)
new SharedArrayBuffer(length, options)
```


**备注：** `SharedArrayBuffer()` 只能通过 `new` 来调用。不带 `new` 调用会抛出 `TypeError`。

### 参数

`length`

要创建的数组缓冲区大小，以字节为单位。

`options` 可选

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

`maxByteLength` 可选

该共享数组缓冲区可以调整到的最大大小，以字节为单位。


### 返回值

一个指定大小的新 `SharedArrayBuffer` 对象，如果指定了 `maxByteLength`，则其 `maxByteLength` 属性被设置为指定的值。其内容被初始化为 0。

示例
--

### 总是使用 new 运算符来创建 SharedArrayBuffer

`SharedArrayBuffer` 构造函数必须使用 `new` 运算符来构造。将 `SharedArrayBuffer` 构造函数作为函数，不通过 `new` 调用会抛出 `TypeError`。


```js
const sab = SharedArrayBuffer(1024);
// TypeError: calling a builtin SharedArrayBuffer constructor
// 不带 new 调用是不行的
```



```js
const sab = new SharedArrayBuffer(1024);
```

### 增大可增大的 SharedArrayBuffer

在这个示例中，我们创建了一个 8 字节的缓冲区，其可增大到的最大长度为 16 字节，然后 `grow()` 它到 12 字节：


```js
const buffer = new SharedArrayBuffer(8, { maxByteLength: 16 });

buffer.grow(12);
```


**备注：** 推荐设置 `maxByteLength` 为使用场景下最低的大小，不要超过 `1073741824`（1GB）以减小内存溢出风险。

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-sharedarraybuffer-constructor |

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

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

参见
--

* `Atomics`
* `ArrayBuffer`
* JavaScript 类型化数组指南
Boolean() 构造函数
==============

**`Boolean()`** 构造函数可以创建 `Boolean` 对象或返回布尔类型的原始值。

尝试一下
----

语法
--


```js
new Boolean(value)
Boolean(value)
```


**备注：** 调用 `Boolean()` 时可以使用或不使用 `new`，但是效果不同。参见返回值部分。

### 参数

`value`

`Boolean` 对象的初始值。

### 返回值

当 `Boolean()` 作为构造函数调用时（使用 `new`），将创建 `Boolean` 对象，它**不是**一个原始值。

当 `Boolean()` 作为普通函数调用时（不使用 `new`），它将参数强制转换为布尔原始值。

**警告：** 你会发现你很少会使用到 `Boolean` 构造函数。

描述
--

作为第一个参数传递的值被转换为布尔值 。如果该值被省略或为 `0`、`-0`、`0n`、`null`、`false`、`NaN`、`undefined` 或空字符串（`""`），那么该对象的初始值为 `false`。所有其他的值，包括任何对象、空数组（`[]`）或字符串 `"false"`，都会创建一个初始值为 `true` 的对象。

**备注：** 当非标准属性 `document.all` 被用作该构造函数的参数时，结果是一个值为 `false` 的 `Boolean` 对象。这个属性是遗留的和非标准的，不应该被使用。

示例
--

### 使用初始值 false 创建 Boolean 对象


```js
const bZero = new Boolean(0);
const bNull = new Boolean(null);
const bEmptyString = new Boolean("");
const bfalse = new Boolean(false);

typeof bfalse; // "object"
Boolean(bfalse); // true
```


请注意，用 `Boolean()` 将 `Boolean` 对象转换为原始值的结果总是 `true`，即使该对象的值为 `false`。因此，总是建议避免构造 `Boolean` 包装对象。

如果你需要从包装对象中取出原始值，不要使用 `Boolean()` 函数，而是使用对象的 `valueOf()` 方法。


```js
const bfalse = new Boolean(false);

bfalse.valueOf(); // false
```

### 使用初始值 true 创建 Boolean 对象


```js
const btrue = new Boolean(true);
const btrueString = new Boolean("true");
const bfalseString = new Boolean("false");
const bSuLin = new Boolean("Su Lin");
const bArrayProto = new Boolean([]);
const bObjProto = new Boolean({});
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-boolean-constructor |

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

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

参见
--

* Boolean
Boolean.prototype.valueOf()
===========================

**`valueOf()`** 方法返回一个`Boolean`对象的原始值。

尝试一下
----

语法
--
```

bool.valueOf()
```

### 返回值

给定`Boolean`对象的原始值

描述
--

`Boolean`的 `valueOf` 方法返回一个`Boolean`对象或`Boolean`字面量的原始值作为布尔数据类型。

该方法通常在 JavaScript 内部调用，而不是在代码中显式调用。

示例
--

### 使用 `valueOf`


```js
x = new Boolean();
myVar = x.valueOf(); // assigns false to myVar
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-boolean.prototype.valueof |

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

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

参见
--

* `Object.prototype.valueOf()`
Boolean.prototype.toString()
============================

**`toString()`** 方法返回表示指定的布尔对象的字符串。

尝试一下
----

语法
--


```js
toString()
```

### 返回值

一个表示特定 `Boolean` 对象的字符串。

描述
--

`Boolean` 对象覆盖了 `Object` 对象的 `toString` 方法。并没有继承 `Object.prototype.toString()`。对于布尔对象，`toString` 方法返回一个表示该对象的字符串。

当一个 `Boolean` 对象作为文本值或进行字符串连接时，JavaScript 会自动调用其 `toString` 方法。

对于 `Boolean` 对象或值，内置的 `toString` 方法返回字符串 `"true"` 或 `"false"`，具体返回哪个取决于布尔对象的值。

示例
--

### 使用 toString()

下面的代码，`flag.toString()` 返回 `"true"`：


```js
const flag = new Boolean(true);
const myVar = flag.toString();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-boolean.prototype.tostring |

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

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

参见
--

* `Object.prototype.toString()`
Error.prototype.message
=======================

概述
--

**`message`** 属性是有关错误信息，人类易读的（human-readable）描述。

描述
--

如果该属性已经被设置，则该属性包含了错误的一个简短描述。SpiderMonkey 大量应用 `message` 属性在异常方面。 `message` 属性结合 `name` 属性一起被 `Error.prototype.toString()` 方法用来创建错误的字符串形式。

默认情况下，`message` 属性是一个空字符串，但是可以通过指定一段信息作为 `Error constructor` 的第一个参数创建一个实例来改变该属性值。

示例
--

### 示例：抛出一个自定义错误


```js
var e = new Error("Could not parse input"); // e.message is "Could not parse input"
throw e;
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-error.prototype.message |

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

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

参见
--

* `Error.prototype.name`
* `Error.prototype.toString()`
Error.prototype.columnNumber
============================

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

\*\*`columnNumber`\*\*属性包含引发此错误的文件行中的列号。

示例
--

### 使用 `columnNumber`


```js
var e = new Error("Could not parse input");
throw e;
console.log(e.columnNumber); // 0
```

规范
--

#### No specification found

No specification data found for `javascript.builtins.Error.columnNumber`.  
Check for problems with this page or contribute a missing `spec_url` to mdn/browser-compat-data. Also make sure the specification is included in w3c/browser-specs.

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

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

参见
--

* `Error.prototype.stack` 
非标准
* `Error.prototype.lineNumber` 
非标准
* `Error.prototype.fileName` 
非标准
Error: cause
============

`Error` 实例中的 **`cause`** 数据属性指示导致该错误的具体原始原因。

在捕获错误时，我们可能会使用更具体或更加实用的信息对错误进行包装，再将其重新抛出。`cause` 属性就用于这一场景，以便仍然可以访问原始的错误。

取值
--

它通过 `options.cause` 参数被传入 `Error()` 构造函数，并且有可能不存在。

| `Error: cause` 的属性特性 |
| --- |
| 可写 | 是 |
| 可枚举 | 否 |
| 可配置 | 是 |

描述
--

`cause` 的值可以是任何类型。你不应该假设捕获错误的 `cause` 属性是一个 `Error`，正如在 `catch` 语句中绑定的变量未必一定是 `Error`。下文“将结构化的数据作为 cause”示例展示了刻意不提供 `Error` 作为 `cause` 的情况。

示例
--

### 重新抛出包含 cause 的错误

有时，捕获错误并使用新的错误信息将其重新抛出是很有用的。在这种情况下，你应该将原始错误传递给新的 `Error` 的构造函数，如下所示：


```js
try {
  connectToDatabase();
} catch (err) {
  throw new Error("Connecting to database failed.", { cause: err });
}
```


更详细的示例请参阅错误 > 区分相似的错误。

### 将结构化的数据作为 cause

为开发者理解而编写的错误消息可能并不适合机器解析，因为它们会受到表达方式改变（rewording），或标点符号改变的影响，破坏已有解析器的正常使用。因此，当从函数中抛出错误时，你可以提供结构化的数据作为错误原因（即 `cause` 字段）供机器解析，以此替代人类可读的错误消息。


```js
function makeRSA(p, q) {
  if (!Number.isInteger(p) || !Number.isInteger(q)) {
    throw new Error("RSA key generation requires integer inputs.", {
      cause: { code: "NonInteger", values: [p, q] },
    });
  }
  if (!areCoprime(p, q)) {
    throw new Error("RSA key generation requires two co-prime integers.", {
      cause: { code: "NonCoprime", values: [p, q] },
    });
  }
  // rsa algorithm…
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-installerrorcause |

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

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

参见
--

* `Error.prototype.message`
* `Error.prototype.toString()`
Error.prototype.name
====================

概述
--

**`name`** 属性表示 error 类型的名称。初始值为"Error".

描述
--

默认情况下，`Error`对象的`name`属性值为"Error".`name 属性和``message`属性一起，通过调用`Error.prototype.toString()`方法，会作为最后异常信息的字符串表示。

示例
--

### 示例：抛出一个自定义错误


```js
var e = new Error("Malformed input"); // e.name 默认是"Error"

e.name = "ParseError"; // 修改之后，e.toString() 会成为下面这样的字符串
throw e; // "ParseError: Malformed input"
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-error.prototype.name |

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

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

参见
--

* `Error.prototype.message`
* `Error.prototype.toString()`
Error.prototype.toString()
==========================

**`toString()`** 方法返回一个表示指定 `Error` 对象的字符串。

语法
--


```js
toString()
```

### 返回值

一个表示指定 `Error` 对象的字符串。

描述
--

`Error` 对象覆盖了 `Object.prototype.toString()` 方法。该方法实现如下（假定 `Object` 和 `String` 没有被更改）：


```js
Error.prototype.toString = function () {
  "use strict";

  const obj = Object(this);
  if (obj !== this) {
    throw new TypeError();
  }

  let name = this.name;
  name = name === undefined ? "Error" : String(name);

  let msg = this.message;
  msg = msg === undefined ? "" : String(msg);

  if (name === "") {
    return msg;
  }
  if (msg === "") {
    return name;
  }

  return name + ": " + msg;
};
```

示例
--

### 使用 toString()


```js
const e1 = new Error("fatal error");
console.log(e1.toString()); // 'Error: fatal error'

const e2 = new Error("fatal error");
e2.name = undefined;
console.log(e2.toString()); // 'Error: fatal error'

const e3 = new Error("fatal error");
e3.name = "";
console.log(e3.toString()); // 'fatal error'

const e4 = new Error("fatal error");
e4.name = "";
e4.message = undefined;
console.log(e4.toString()); // ''

const e5 = new Error("fatal error");
e5.name = "hello";
e5.message = undefined;
console.log(e5.toString()); // 'hello'
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-error.prototype.tostring |

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

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

参见
--

* `core-js` 中关于 `Error.prototype.toString` 的 polyfill（修复了多个错误）
Error.prototype.stack
=====================

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

`Error`对象作为一个非标准的栈属性提供了一种函数追踪方式。无论这个函数被被调用，处于什么模式，来自于哪一行或者哪个文件，有着什么样的参数。这个栈产生于最近一次调用最早的那次调用，返回原始的全局作用域调用

描述
--

每个步骤都会被分为单独的一行以这个函数的名字作为开始（如果不是一个来自于全局作用域的调用），然后通过一个 `@` 符号标记一个文件的位置（尤其是当一个函数构造错误并且作为错误被抛出，并且如果能定位到这个文件的位置，那么会使用冒号显示行号。（提示）`Error` 对象在错误跑出时同样能处理并渲染出文件名，行号和列号属性（但是仅仅限于错误。而不是追踪他的路径）

注意这是 Firefox 定义的格式，并没有标准的定义。但是 Safari 6+ 和 Opera 12- 定义了一种非常相似的格式。其他使用 JavaScript V8 引擎的浏览器（例如 Chrome、Opera 15+，安卓浏览器）和 IE 10+，定义了一种不同的格式（可参见 error.stack 文档）

堆栈中的参数值：Firefox 14 版本之前是 (Firefox bug 744842) 函数名会随着参数值会在添加 @符号之前被立即转换成用圆括号包裹的 string 类型。然而对象或者数组等其他类型似乎会被转换成`"[object Object]"`并且这种格式不能回退到之前实际上的对象，而纯值会被渲染（或许这种在 Firefox 14 中仍有这种可能，使用 `arguments.callee.caller.arguments` 更加简单。因为函数名可以使用 `arguments.callee.caller.name` 渲染）。`"undefined"` 被显示为 `"(void 0)"` 不过要注意的是如果是字符串类型的参数会直接以类似 `"@"`, `"("`, `")"` 格式通过编译（或者是包含在文件名中）。你不能简单的依赖这些将它分成多个组件，但是，对于 Firefox 14 及以后的版本来说，这些都不是问题

不同的浏览器会在不同时期设置这个值。例如，Firefox 在创建`Error`对象时设置它，然而 PhantomJS 是在当且仅当它抛出 `Error`时，并且MSDN docs 似乎也实现了 PhantomJS 的方式。

示例
--

下面这段 html 代码展示了`stack` 属性的使用方法


```html
<!doctype html>
<meta charset="UTF-8" />
<title>Stack Trace Example</title>
<body>
  <script>
 function trace() {
 try {
 throw new Error("myError");
 } catch (e) {
 alert(e.stack);
 }
 }
 function b() {
 trace();
 }
 function a() {
 b(3, 4, "\n\n", undefined, {});
 }
 a("first call, firstarg");
 </script>
</body>
```


假设上面这段代码被保存在 Windows 系统下的 `C:\example.html` 在处理过程中抛出如下所示的错误信息

Firefox 30 及以上版本的浏览器会包含以列号为开始 (Firefox bug 762556):
```

trace@file:///C:/example.html:9:17
b@file:///C:/example.html:16:13
a@file:///C:/example.html:19:13
@file:///C:/example.html:21:9
```


Firefox 14 to Firefox 29:
```

trace@file:///C:/example.html:9
b@file:///C:/example.html:16
a@file:///C:/example.html:19
@file:///C:/example.html:21
```


Firefox 13 及更早版本的浏览器会抛出如下信息：
```

Error("myError")@:0
trace()@file:///C:/example.html:9
b(3,4,"\n\n",(void 0),[object Object])@file:///C:/example.html:16
a("first call, firstarg")@file:///C:/example.html:19
@file:///C:/example.html:21
```

### Stack of eval'ed code

Firefox30 以 Gecko 30 格式开头，`Function()` 和 `eval()` 调用产生的错误代码堆栈，现在在调用内部通过行号和列号以更加详细的格式向我们展示出来。函数调用显示为`"> Function"` 而 eval 调用则是 `"> eval"`这样。下面来看这个Firefox bug 332176.


```js
try {
  new Function("throw new Error()")();
} catch (e) {
  console.log(e.stack);
}

// anonymous@file:///C:/example.html line 7 > Function:1:1
// @file:///C:/example.html:7:6

try {
  eval("eval('FAIL')");
} catch (x) {
  console.log(x.stack);
}

// @file:///C:/example.html line 7 > eval line 1 > eval:1:1
// @file:///C:/example.html line 7 > eval:1:1
// @file:///C:/example.html:7:6
```


你也可以使用`//# sourceURL` 命名 eval 源的指令。也可以查看在 Debugger文档中的Debug eval 源 (en-US)和blog post 博客。

规范
--

不属于任何规范，没有标准规范。

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

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

参见
--

* Components.stack
* 外部项目：TraceKit and javascript-stacktrace
* MSDN：error.stack docs
* Overview of the V8 JavaScript stack trace API
Error() 构造函数
============

**`Error()`** 构造函数能够创建一个包含错误信息的对象。

语法
--


```js
new Error()
new Error(message)
new Error(message, options)
new Error(message, fileName)
new Error(message, fileName, lineNumber)
Error()
Error(message)
Error(message, options)
Error(message, fileName)
Error(message, fileName, lineNumber)
```


**备注：** 调用 `Error()` 时，可以使用关键字 `new`，也可以不使用。两种声明方式均能创建一个新的 `Error` 实例。

### 参数

`message` 可选

人类可读的错误信息。

`options` 可选

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

`cause` 可选

指示错误的具体原因，反映在 `cause` 属性中。当捕获并重新抛出带有更具体或有用的错误消息的错误时，可以使用此属性传递原始错误。


`fileName` 可选 
非标准

引发此错误的文件路径，反映在 `fileName` 属性中。默认为调用 `Error()` 构造函数的代码所在文件的名称。

`lineNumber` 可选 
非标准

引发错误的文件中的行号，反映在 `lineNumber` 属性中。默认为包含 `Error()` 构造函数调用的行号。

示例
--

### 函数调用与构造函数

当 `Error` 作为函数使用，即不包含 `new` 关键字时，它将返回一个 Error 对象。因此，直接调用 `Error` 函数将产生与使用 `new` 关键字构造 `Error` 对象相同的输出。


```js
const x = Error("I was created using a function call!");
// 上述代码与以下代码具有相同的功能
const y = new Error('I was constructed via the "new" keyword!');
```

### 使用 cause 重新抛出错误

在捕获错误时，我们可能会使用新的错误信息对错误进行包装，再将其重新抛出。这种场景下，你应当将原始错误也传入新的 `Error` 的构造函数，如下所示：


```js
try {
  frameworkThatCanThrow();
} catch (err) {
  throw new Error("New error message", { cause: err });
}
```


更多示例参考错误 > 区分相似的错误。

### 省略 options 参数

JavaScript 只有在 `options` 参数为对象时才会尝试读取 `options.cause` 属性，这样可以避免与另一种非标准的 `Error(message, fileName, lineNumber)` 函数签名产生歧义，后者要求第二个参数必须是字符串。如果你省略了 `options` 参数，或者将原始值作为 `options` 传入，又或者传递的对象中没有 `cause` 属性，那么创建的 `Error` 对象将不会包含 `cause` 属性。


```js
// 省略 options
const error1 = new Error("Error message");
console.log("cause" in error1); // false

// 传递原始值
const error2 = new Error("Error message", "");
console.log("cause" in error2); // false

// 传递不包含 cause 属性的对象
const error3 = new Error("Error message", { details: "http error" });
console.log("cause" in error3); // false
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-error-constructor |

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

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

参见
--

* `core-js` 提供了支持 `cause` 等最新特性 (modern behavior) 的 `Error` polyfill
* `throw`
* `try...catch`
* Error cause（v8.dev/features）
Error.prototype.lineNumber
==========================

**非标准:** 该特性是非标准的，请尽量不要在生产环境中使用它！

**`lineNumber`** 属性的值为抛出错误的代码在其源文件中所在的行号。

示例
--

### 使用 `lineNumber`


```js
var e = new Error("Could not parse input");
throw e;
console.log(e.lineNumber); // 2
```

### 监听 `error` 事件的示例


```js
window.addEventListener("error", function (e) {
  console.log(e.lineNumber); // 5
});
var e = new Error("Could not parse input");
throw e;
```


这不是一个标准化的属性，缺乏广泛的支持。参见下面的浏览器兼容性表格。

规范
--

非标准化属性。不属于任何规范。

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

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

相关内容
----

* `Error.prototype.stack` 
非标准
* `Error.prototype.columnNumber` 
非标准
* `Error.prototype.fileName` 
非标准