recursal/MDN huggingface dataset:
Promise.allSettled()
====================

**`Promise.allSettled()`** 静态方法将一个 Promise 可迭代对象作为输入，并返回一个单独的 `Promise`。当所有输入的 Promise 都已敲定时（包括传入空的可迭代对象时），返回的 Promise 将被兑现，并带有描述每个 Promise 结果的对象数组。

尝试一下
----

语法
--


```js
Promise.allSettled(iterable)
```

### 参数

`iterable`

一个以 promise 组成的可迭代对象（例如 `Array`）对象。

### 返回值

一个 `Promise`，其状态为：

* **已兑现（already fulfilled）**，如果传入的 `iterable` 为空的话。
* **异步兑现（asynchronously fulfill）**，当给定的 `iterable` 中所有 promise 已经敲定时（要么已兑现，要么已拒绝）。兑现的值是一个对象数组，其中的对象按照 `iterable` 中传递的 promise 的顺序，描述每一个 promise 的结果，无论完成顺序如何。每个结果对象都有以下的属性：

`status`

一个字符串，要么是 `"fulfilled"`，要么是 `"rejected"`，表示 promise 的最终状态。

`value`

仅当 `status` 为 `"fulfilled"`，才存在。promise 兑现的值。

`reason`

仅当 `status` 为 `"rejected"`，才存在，promsie 拒绝的原因。

如果传入的 `iterable` 是非空的，但不包含待定的（pending）promise，则返回的 promise 仍然是异步兑现的，而不是同步兑现。
描述
--

`Promise.allSettled()` 方法是 promise 并发方法之一。在你有多个不依赖于彼此成功完成的异步任务时，或者你总是想知道每个 promise 的结果时，使用 `Promise.allSettled()` 。

相比之下，如果任务相互依赖，或者如果你想在任何 promise 被拒绝时立即拒绝，`Promise.all()` 返回的 Promise 可能更合适。

示例
--

### 使用 Promise.allSettled()


```js
Promise.allSettled([
  Promise.resolve(33),
  new Promise((resolve) => setTimeout(() => resolve(66), 0)),
  99,
  Promise.reject(new Error("一个错误")),
]).then((values) => console.log(values));

// [
// { status: 'fulfilled', value: 33 },
// { status: 'fulfilled', value: 66 },
// { status: 'fulfilled', value: 99 },
// { status: 'rejected', reason: Error: 一个错误 }
// ]
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.allsettled |

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

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

参见
--

* `core-js` 中 `Promise.allSettled` 的 polyfill
* 使用 promise
* 使用 promise 的优雅异步编程
* `Promise`
* `Promise.all()`
* `Promise.any()`
* `Promise.race()`
Promise[@@species]
==================

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

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

语法
--


```js
Promise[Symbol.species]
```

### 返回值

`get @@species` 被调用时的构造函数 `this` 的值。返回值用于构造从创建新 Promise 的 Promise 链式方法的返回值。

描述
--

`@@species` 访问器属性返回 `Promise` 对象的默认构造函数。子类构造函数可以覆盖它以更改构造函数的赋值。默认实现基本上是这样的：


```js
// 以下是一个假设的基本实现，仅供说明
class Promise {
  static get [Symbol.species]() {
    return this;
  }
}
```


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


```js
class SubPromise extends Promise {}
SubPromise[Symbol.species] === SubPromise; // true
```


Promise 链式方法——`then()`、`catch()` 和 `finally()`——返回新的 Promise 对象。它们通过 `this.constructor[@@species]` 获取构造新 Promise 的构造函数。如果 `this.constructor` 为 `undefined`，或者 `this.constructor[@@species]` 为 `undefined` 或 `null`，则会使用默认的 `Promise()` 构造函数。否则，将使用 `this.constructor[@@species]` 返回的构造函数来构造新的 Promise 对象。

示例
--

### 普通对象中的 Species

`Symbol.species` 属性返回默认的构造函数，对于 `Promise` 来说，它的默认构造函数就是 `Promise` 构造函数本身。


```js
Promise[Symbol.species]; // [Function: Promise]
```

### 派生对象中的 Species

在自定义 `Promise` 子类的实例中，比如 `MyPromise`，`MyPromise` 的 species 是 `MyPromise` 构造函数本身。然而，你可能希望在派生类的方法中覆盖该属性，以便返回父类 `Promise` 对象。


```js
class MyPromise extends Promise {
  // 将 MyPromise 的 species 覆盖为父类 Promise 构造函数
  static get [Symbol.species]() {
    return Promise;
  }
}
```


默认情况下，Promise 方法将返回具有子类类型的 Promise。


```js
class MyPromise extends Promise {
  someValue = 1;
}

console.log(MyPromise.resolve(1).then(() => {}).someValue); // 1
```


通过覆盖 `@@species`，Promise 方法将返回基本的 `Promise` 类型。


```js
class MyPromise extends Promise {
  someValue = 1;
  static get [Symbol.species]() {
    return Promise;
  }
}

console.log(MyPromise.resolve(1).then(() => {}).someValue); // undefined
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-promise-@@species |

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

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

参见
--

* `Promise`
* `Symbol.species`
Promise.prototype.finally()
===========================

`Promise` 实例的 **`finally()`** 方法用于注册一个在 promise 敲定（兑现或拒绝）时调用的函数。它会立即返回一个等效的 `Promise` 对象，这可以允许你链式调用其他 promise 方法。

这可以让你避免在 promise 的 `then()` 和 `catch()` 处理器中重复编写代码。

尝试一下
----

语法
--


```js
finally(onFinally)
```

### 参数

`onFinally`

一个当 promise 敲定时异步执行的函数。它的返回值将被忽略，除非返回一个被拒绝的 promise。调用该函数时不带任何参数。

### 返回值

返回等效的 `Promise`。如果处理程序抛出错误或返回被拒绝的 promise，那么 `finally()` 返回的 promise 将以该值被拒绝。否则，处理程序的返回值不会影响原始 promise 的状态。

描述
--

如果你想在 promise 敲定时进行一些处理或者清理，无论其结果如何，那么 `finally()` 方法会很有用。

`finally()` 方法类似于调用 `then(onFinally, onFinally)`。然而，有几个不同之处：

* 创建内联函数时，你可以只将其传入一次，而不是强制声明两次或为其创建变量。
* `onFinally` 回调函数不接收任何参数。这种情况恰好适用于你*不关心*拒绝原因或兑现值的情况，因此无需提供它。
* `finally()` 调用通常是透明的，不会更改原始 promise 的状态。例如：
    + 与 `Promise.resolve(2).then(() => 77, () => {})` 不同，它返回一个最终会兑现为值 `77` 的 promise，而 `Promise.resolve(2).finally(() => 77)` 返回一个最终兑现为值 `2` 的 promise。
    + 类似地，与 `Promise.reject(3).then(() => {}, () => 88)` 不同，它返回一个最终兑现为值 `88` 的 promise，而 `Promise.reject(3).finally(() => 88)` 返回一个最终以原因 `3` 拒绝的 promise。

**备注：** 在 `finally` 回调函数中抛出错误（或返回被拒绝的 promise）仍会导致返回的 promise 被拒绝。例如，`Promise.reject(3).finally(() => { throw 99; })` 和 `Promise.reject(3).finally(() => Promise.reject(99))` 都以理由 `99` 拒绝返回的 promise。

与 `catch()` 一样，`finally()` 在内部调用其调用对象上的 `then` 方法。如果 `onFinally` 不是函数，则调用 `then()` 时使用 `onFinally` 同时作为两个参数——对于 `Promise.prototype.then()`，这意味着没有附加有效的处理器。否则，`then()` 被调用时会使用两个内部创建的函数，其行为如下：

**警告：** 这只是为了演示，而不是一个 polyfill。


```js
promise.then(
  (value) => Promise.resolve(onFinally()).then(() => value),
  (reason) =>
    Promise.resolve(onFinally()).then(() => {
      throw reason;
    }),
);
```


因为 `finally()` 调用 `then()`，所以它支持子类化。此外，请注意上面的 `Promise.resolve()` 调用——实际上，`onFinally()` 的返回值是使用与 `Promise.resolve()` 相同的算法解决的，但用于构造解决的 promise 的实际构造函数将是子类。`finally()` 通过 `promise.constructor[@@species]` 获取构造函数。

示例
--

### 使用 finally()


```js
let isLoading = true;

fetch(myRequest)
  .then((response) => {
    const contentType = response.headers.get("content-type");
    if (contentType && contentType.includes("application/json")) {
      return response.json();
    }
    throw new TypeError("Oops, we haven't got JSON!");
  })
  .then((json) => {
    /\* 进一步处理 JSON \*/
  })
  .catch((error) => {
    console.error(error); // 这行代码也可能抛出错误，例如：when console = {}
  })
  .finally(() => {
    isLoading = false;
  });
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.prototype.finally |

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

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

参见
--

* `core-js` 中 `Promise.prototype.finally` 的 Polyfill
* `Promise`
* `Promise.prototype.then()`
* `Promise.prototype.catch()`
Promise.any()
=============

**`Promise.any()`** 静态方法将一个 Promise 可迭代对象作为输入，并返回一个 `Promise`。当输入的任何一个 Promise 兑现时，这个返回的 Promise 将会兑现，并返回第一个兑现的值。当所有输入 Promise 都被拒绝（包括传递了空的可迭代对象）时，它会以一个包含拒绝原因数组的 `AggregateError` 拒绝。

尝试一下
----

语法
--


```js
Promise.any(iterable)
```

### 参数

`iterable`

一个 promise 的可迭代对象（例如一个数组）。

### 返回值

一个 `Promise`，其状态为：

* **已拒绝（already rejected）**，如果传入的 `iterable` 为空的话。
* **异步兑现（asynchronously fulfilled）**，当给定的 `iterable` 中的任何一个 Promise 被兑现时，返回的 Promise 就会被兑现。其兑现值是第一个兑现的 Promise 的兑现值。
* **异步拒绝（asynchronously rejected）**，当给定的 `iterable` 中的所有 Promise 都被拒绝时。拒绝原因是一个 `AggregateError`，其 `errors` 属性包含一个拒绝原因数组。无论完成顺序如何，这些错误都是按照传入的 Promise 的顺序排序。如果传递的 `iterable` 是非空的，但不包含待定的 Promise，则返回的 Promise 仍然是异步拒绝的（而不是同步拒绝的）。
描述
--

`Promise.any()` 方法是 Promise 并发方法之一。该方法对于返回第一个兑现的 Promise 非常有用。一旦有一个 Promise 兑现，它就会立即返回，因此不会等待其他 Promise 完成。

与 `Promise.all()` 返回一个兑现值*数组*不同的是，我们只会得到一个兑现值（假设至少有一个 Promise 被兑现）。此方法对于那些如果我们只需要一个 Promise 被兑现，但不在意哪一个被兑现的情况更有益。请注意另一个区别：该方法在接收到*空的可迭代对象*时会拒绝，因为实际上，该可迭代对象不包含任何兑现的项。你可以将 `Promise.any()` 和 `Promise.all()` 与 `Array.prototype.some()` 和 `Array.prototype.every()` 进行比较。

同时，与 `Promise.race()` 返回第一个*敲定*（无论是兑现还是拒绝）的值不同的是，该方法返回第一个*兑现*的值。该方法忽略所有被拒绝的 Promise，直到第一个被兑现的 Promise。

示例
--

### 使用 Promise.any()

`Promise.any()` 会以第一个兑现的 Promise 来兑现，即使有 Promise 先被拒绝。这与 `Promise.race()` 不同，后者会使用第一个敲定的 Promise 来兑现或拒绝。


```js
const pErr = new Promise((resolve, reject) => {
  reject("总是失败");
});

const pSlow = new Promise((resolve, reject) => {
  setTimeout(resolve, 500, "最终完成");
});

const pFast = new Promise((resolve, reject) => {
  setTimeout(resolve, 100, "很快完成");
});

Promise.any([pErr, pSlow, pFast]).then((value) => {
  console.log(value);
  // pFast 第一个兑现
});
// 打印：
// 很快完成
```

### 拒绝并返回 AggregateError

如果没有 Promise 被兑现，`Promise.any()` 将使用 `AggregateError` 进行拒绝。


```js
const failure = new Promise((resolve, reject) => {
  reject("总是失败");
});

Promise.any([failure]).catch((err) => {
  console.log(err);
});
// AggregateError: No Promise in Promise.any was resolved
```

### 显示第一张已加载的图片

在这个例子，我们有一个获取图片并返回 blob 的函数，我们使用 `Promise.any()` 来获取一些图片并显示第一张可用的图片（即最先解决的那个 promise）。


```js
async function fetchAndDecode(url, description) {
  const res = await fetch(url);
  if (!res.ok) {
    throw new Error(`HTTP 错误！状态码：${res.status}`);
  }
  const data = await res.blob();
  return [data, description];
}

const coffee = fetchAndDecode("coffee.jpg", "Coffee");
const tea = fetchAndDecode("tea.jpg", "Tea");

Promise.any([coffee, tea])
  .then(([blob, description]) => {
    const objectURL = URL.createObjectURL(blob);
    const image = document.createElement("img");
    image.src = objectURL;
    image.alt = description;
    document.body.appendChild(image);
  })
  .catch((e) => {
    console.error(e);
  });
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.any |

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

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

参见
--

* `core-js` 中 `Promise.any` 的 polyfill
* `Promise`
* `Promise.all()`
* `Promise.allSettled()`
* `Promise.race()`
Promise.reject()
================

**`Promise.reject()`** 静态方法返回一个已拒绝（rejected）的 `Promise` 对象，拒绝原因为给定的参数。

尝试一下
----

语法
--


```js
Promise.reject(reason)
```

### 参数

`reason`

该 `Promise` 对象被拒绝的原因。

### 返回值

返回一个已拒绝（rejected）的 `Promise`，拒绝原因为给定的参数。

描述
--

`Promise.reject` 静态方法返回一个被拒绝的 `Promise` 对象。通过使用 `Error` 的实例获取错误原因 `reason` 对调试和选择性错误捕捉很有帮助。

`Promise.reject()` 方法是一个通用方法，支持子类化，这意味着它可以在 `Promise` 的子类上调用，并且结果会是该子类类型的 Promise 对象。为此，子类的构造函数必须实现与 `Promise()` 构造函数相同的签名，即接受一个 `executor` 函数，该函数可以用 `resolve` 和 `reject` 回调函数作为参数进行调用。`Promise.reject()` 实际上相当于 `new Promise((resolve, reject) => reject(reason))` 的简写形式。

与 `Promise.resolve()` 不同，即使 `reason` 已经是一个 Promise 对象，`Promise.reject()` 方法也始终会将其封装在一个新的 `Promise` 对象中。

示例
--

### 使用 `Promise.reject()` 静态方法


```js
Promise.reject(new Error("失败")).then(
  () => {
    // 不会被调用
  },
  (error) => {
    console.error(error); // Stacktrace
  },
);
```

### reject 一个 promise 对象

与 `Promise.resolve` 不同，`Promise.reject` 方法不会重用已存在的 `Promise` 实例。它始终返回一个新的 `Promise` 实例，该实例封装了拒绝的原因（`reason`）。


```js
const p = Promise.resolve(1);
const rejected = Promise.reject(p);
console.log(rejected === p); // false
rejected.catch((v) => {
  console.log(v === p); // true
});
```

### 在非 Promise 构造函数上调用 reject()

`Promise.reject()` 方法是一个通用方法。它可以在任何实现与 `Promise()` 构造函数相同签名的构造函数上调用。例如，我们可以在一个构造函数上调用它，并传入 `console.log` 作为 `reject` 参数：


```js
class NotPromise {
  constructor(executor) {
    // “resolve”和“reject”函数的行为与原生 Promise 完全不同，但 `Promise.reject()` 方法以相同的方式调用它们。
    executor(
      (value) => console.log("已解决", value),
      (reason) => console.log("已拒绝", reason),
    );
  }
}

Promise.reject.call(NotPromise, "foo"); // 输出 "已拒绝 foo"
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-promise.reject |

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

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

参见
--

* `Promise`
Promise.withResolvers()
=======================

**`Promise.withResolvers()`** 静态方法返回一个对象，其包含一个新的 `Promise` 对象和两个函数，用于解决或拒绝它，对应于传入给 `Promise()` 构造函数执行器的两个参数。

语法
--


```js
Promise.withResolvers()
```

### 参数

无。

### 返回值

包含以下属性的普通对象：

`promise`

一个 `Promise` 对象。

`resolve`

一个函数，用于解决该 Promise。关于其语义，请参阅 `Promise()` 构造函数。

`reject`

一个函数，用于拒绝该 Promise。关于其语义，请参阅 `Promise()` 构造函数。

描述
--

`Promise.withResolvers()` 完全等同于以下代码：


```js
let resolve, reject;
const promise = new Promise((res, rej) => {
  resolve = res;
  reject = rej;
});
```


只是它更简洁，并且不需要使用 `let`。

使用 `Promise.withResolvers()` 关键的区别在于解决和拒绝函数现在与 Promise 本身处于同一作用域，而不是在执行器中被创建和一次性使用。这可能使得一些更高级的用例成为可能，例如在重复事件中重用它们，特别是在处理流和队列时。这通常也意味着相比在执行器内包装大量逻辑，嵌套会更少。

`Promise.withResolvers()` 是通用的且支持子类化，这意味着它可以在 `Promise` 的子类上调用，结果将包含一个该子类类型的 promise。要做到这一点，子类的构造函数必须实现与 `Promise()` 构造函数相同的签名——接受一个单独的 `executor` 函数，该函数可以用 `resolve` 和 `reject` 回调作为参数来调用。

示例
--

### 将流转换为异步可迭代对象

`Promise.withResolvers()` 的使用场景是，当你有一个 promise，需要通过无法包装在 promise 执行器内的某个事件监听器来解决或拒绝。以下示例将 Node.js 的可读流转换为异步可迭代对象。这里的每个 `promise` 代表一个可用的数据批次，每次读取当前批次时，就会为下一个批次创建一个新的 promise。请注意，事件监听器只附加了一次，但实际上每次都调用了不同版本的 `resolve` 和 `reject` 函数。


```js
async function\* readableToAsyncIterable(stream) {
  let { promise, resolve, reject } = Promise.withResolvers();
  stream.on("error", (error) => reject(error));
  stream.on("end", () => resolve());
  stream.on("readable", () => resolve());

  while (stream.readable) {
    await promise;
    let chunk;
    while ((chunk = stream.read())) {
      yield chunk;
    }
    ({ promise, resolve, reject } = Promise.withResolvers());
  }
}
```

### 在非 Promise 构造函数上调用 withResolvers()

`Promise.withResolvers()` 是一个通用方法。它可以在任何实现了与 `Promise()` 构造函数相同签名的构造函数上调用。例如，我们可以在一个将 `console.log` 作为 `resolve` 和 `reject` 函数传入给 `executor` 的构造函数上调用它：


```js
class NotPromise {
  constructor(executor) {
    // “resolve”和“reject”函数和原生的 promise 的行为完全不同
    // 但 Promise.withResolvers() 只是返回它们，就像是原生的 promise 一样
    executor(
      (value) => console.log("以", value, "解决"),
      (reason) => console.log("以", reason, "拒绝"),
    );
  }
}

const { promise, resolve, reject } = Promise.withResolvers.call(NotPromise);
resolve("hello");
// 输出：以 hello 解决
```

规范
--

| Specification |
| --- |
| ES Promise.withResolvers (2023) # sec-promise.withResolvers |

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

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

参见
--

* `core-js` 中 `Promise.withResolvers` 的 polyfill
* 使用 promise 指南
* `Promise`
* `Promise()` 构造函数
BigInt.prototype.toString()
===========================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

* Learn more
* See full compatibility
* Report feedback
**`toString()`** 方法返回一个字符串，表示指定 `BigInt` 对象。后面的 "n" 不是字符串的一部分。

尝试一下
----

语法
--
```

bigIntObj.toString([radix])
```

### 参数

`radix`可选

可选，介于 2 到 36 之间的整数，指定用于表示数值的基数。

### 返回值

表示指定 `BigInt` 对象的字符串。

### 异常

`RangeError`

如果 `toString()` 的基数小于 2 或大于 36, 则抛出 `RangeError`。

描述
--

`BigInt` 对象重写 `Object` 对象的 `toString()` 方法；它不继承 `Object.prototype.toString()`。对于 `BigInt` 对象，`toString()` 方法返回指定基数中对象的字符串表示形式。

`toString()` 方法解析其第一个参数，并尝试返回指定基数 (base) 的字符串表示形式。对于大于 10 的参数，使用字母表中的字母表示大于 9 的数字。例如，对于十六进制数（以 16 为基数），使用 a 到 f。

如果未指定基数，则假定首选基数为 10。

如果 `bigIntObj` 为负，则保留符号。即使基数是 2，情况也是如此；返回的字符串是 `bigIntObj` 的正二进制表示，前面是一个 `-` 符号，而不是 `bigIntObj` 的两个补码。

示例
--

### Using `toString`


```js
17n.toString(); // '17'
66n.toString(2); // '1000010'
254n.toString(16); // 'fe'
-10n.toString(2); // -1010'
-0xffn.toString(2); // '-11111111'
```

### Negative-zero `BigInt`

没有负零 `BigInt`，因为整数中没有负零。`-0.0` 是一个 IEEE 浮点概念，只出现在 JavaScript `Number` 类型中。


```js
(-0n).toString(); // '0'
BigInt(-0).toString(); // '0'
```

规范
--

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

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

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

请参阅
---

* `BigInt.prototype.toLocaleString()`
* `BigInt.prototype.valueOf()`
* `Number.prototype.toString()`
BigInt() constructor
====================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

* Learn more
* See full compatibility
* Report feedback
**`BigInt()`** 构造函数用来创建 `BigInt` 对象。

语法
--


```js
BigInt(value)
```

### 参数

`value`

被创建的对象的数值。可以是字符串或整数。


**备注：** `BigInt()` 不与 `new` 运算符一起使用。

示例
--


```js
BigInt(123);
// 123n
```

规范
--

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

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

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

参见
--

* `BigInt`
BigInt.prototype.valueOf()
==========================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

* Learn more
* See full compatibility
* Report feedback
**`valueOf()`** 方法返回 `BigInt` 对象包装的原始值。

尝试一下
----

语法
--
```

bigIntObj.valueOf()
```

### 返回值

表示指定 `BigInt` 对象的原始 BigInt 值。

示例
--

### Using `valueOf`


```js
typeof Object(1n); // object
typeof Object(1n).valueOf(); // bigint
```

规范
--

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

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

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

请参阅
---

* `BigInt.prototype.toString()`
BigInt.asIntN()
===============

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

* Learn more
* See full compatibility
* Report feedback
**`BigInt.asIntN`** 静态方法将 `BigInt` 值转换为一个 -`2^(width-1)` 与 `2^(width-1)-1` 之间的有符号整数。

尝试一下
----

语法
--
```

BigInt.asIntN(width, bigint);
```

### 参数

`width`

可存储整数的位数。

`bigint`

要存储在指定位数上的整数。

### 返回值

`bigint` 模 (modulo) `2^width` 作为有符号整数的值。

示例
--

### 保持在 64 位范围内

`BigInt.asIntN()` 方法对于保持在 64 位 (64-bit) 算数范围内非常有用。


```js
const max = 2n \*\* (64n - 1n) - 1n;

BigInt.asIntN(64, max);
// ↪ 9223372036854775807n

BigInt.asIntN(64, max + 1n);
// ↪ -9223372036854775808n
// negative because of overflow
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-bigint.asintn |

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

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

请参阅
---

* `BigInt`
* `BigInt.asUintN()`
BigInt.prototype.toLocaleString()
=================================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

* Learn more
* See full compatibility
* Report feedback
**`toLocaleString()`** 方法返回一个表示给定 BigInt 对象的字符串，该字符串格式因不同语言而不同。在支持 `Intl.NumberFormat` API 的实现中，该方法仅是调用了 `Intl.NumberFormat` 方法。

尝试一下
----

语法
--


```js
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
```

### 参数

`locales` 和 `options` 参数使程序能够指定使用哪种语言格式化规则，允许定制该方法的行为（behavior）。

在支持 `Intl.NumberFormat` API 的实现中，这些参数与 `Intl.NumberFormat()` (en-US) 构造函数的参数完全对应。而对于不支持 `Intl.NumberFormat` 的实现，则要求函数忽略这两个参数，使得函数使用的区域（locale）以及返回的字符串的格式完全取决于实现。

`locales` 可选

表示缩写语言代码（BCP 47 language tag）的字符串，或由此类字符串组成的数组。对应于 `Intl.NumberFormat()` 构造函数的 `locales` (en-US) 参数。

在不支持 `Intl.NumberFormat` 的实现中，该参数会被忽略，并且通常会使用主机的区域设置。

`options` 可选

一个调整输出格式的对象。对应于 `Intl.NumberFormat()` 构造函数的 `options` (en-US) 参数。

在不支持 `Intl.NumberFormat` 的实现中，该参数会被忽略。

参见 `Intl.NumberFormat()` 构造函数 (en-US)以详细了解这些参数以及如何使用它们。

### 返回值

一个表示给定 BitInt 对象的字符串，该字符串格式因不同语言而不同。

在支持 `Intl.NumberFormat` 的实现中，此方法等价于 `new Intl.NumberFormat(locales, options).format(number)`。

性能
--

当需要对大量的数字进行格式化时，最好创建一个 `Intl.NumberFormat` 对象，并使用其 `format()` 方法提供的函数。

示例
--

### 使用 `toLocaleString`

没有指定区域（locale）时，返回一个使用默认区域和格式设置（options）的格式化字符串。


```js
const bigint = 3500n;

console.log(bigint.toLocaleString());
// "3,500" 如果区域为 en-US
```

### 使用 `locales`

这个例子展示了本地化数字格式的一些变体。为了获得应用程序用户界面中使用的语言的格式，请确保使用 `locales` 参数指定该语言（可能还有一些回退语言）：


```js
const bigint = 123456789123456789n;

// 德国使用句号表示千位
console.log(bigint.toLocaleString("de-DE"));
// 123.456.789.123.456.789

// 大多数说阿拉伯语的阿拉伯国家使用东阿拉伯数字
console.log(bigint.toLocaleString("ar-EG"));
// ١٢٣٬٤٥٦٬٧٨٩٬١٢٣٬٤٥٦٬٧٨٩

// 印度使用千、万、千万分隔符
console.log(bigint.toLocaleString("en-IN"));
// 1,23,45,67,89,12,34,56,789

// nu 扩展键要求使用编号系统，例如中文十进制数
console.log(bigint.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// 一二三,四五六,七八九,一二三,四五六,七八九

// 当使用的语言不被支持，例如
// 巴厘岛语，则可以包含一种回退语言，这里以印尼语为例
console.log(bigint.toLocaleString(["ban", "id"]));
// 123.456.789.123.456.789
```

### 使用 `options`

`toLocaleString` 提供的结果可以使用 `options` 参数进行自定义：


```js
const bigint = 123456789123456789n;

// 要求使用货币格式
console.log(
  bigint.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// 123.456.789.123.456.789,00 €

// 日元不使用小数单位
console.log(
  bigint.toLocaleString("ja-JP", { style: "currency", currency: "JPY" }),
);
// ￥123,456,789,123,456,789

// 保留三位有效数字
console.log(bigint.toLocaleString("en-IN", { maximumSignificantDigits: 3 }));
// 1,23,00,00,00,00,00,00,000
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sup-bigint.prototype.tolocalestring |

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

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

参见
--

* `BigInt.prototype.toString()`
BigInt.asUintN()
================

Baseline Widely available
-------------------------

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2020.

* Learn more
* See full compatibility
* Report feedback
**`BigInt.asUintN`** 静态方法将 `BigInt` 转换为一个 0 和 2^width-1 之间的无符号整数。

尝试一下
----

语法
--
```

BigInt.asUintN(width, bigint);
```

### 参数

`width`

可存储整数的位数。

`bigint`

要存储在指定位数上的整数。

### 返回值

`bigint` 模 (modulo) `2^width` 作为无符号整数的值。

示例
--

### 保持在 64 位范围内

`BigInt.asUintN()` 方法对于保持在 64 位 (64-bit) 算数范围内非常有用。


```js
const max = 2n \*\* 64n - 1n;

BigInt.asUintN(64, max);
// ↪ 18446744073709551615n

BigInt.asUintN(64, max + 1n);
// ↪ 0n
// zero because of overflow
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-bigint.asuintn |

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

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

请参阅
---

* `BigInt`
* `BigInt.asIntN()`
JSON.parse()
============

**`JSON.parse()`** 方法用来解析 JSON 字符串，构造由字符串描述的 JavaScript 值或对象。提供可选的 **reviver** 函数用以在返回之前对所得到的对象执行变换 (操作)。

尝试一下
----

语法
--


```js
JSON.parse(text)
JSON.parse(text, reviver)
```

### 参数

`text`

要被解析成 JavaScript 值的字符串，关于 JSON 的语法格式，请参考：`JSON`。

`reviver` 可选

转换器，如果传入该参数 (函数)，可以用来修改解析生成的原始值，调用时机在 parse 函数返回之前。

### 返回值

与给定的 JSON `text` 相对应的 `Object`、`Array`、string、number、boolean 或者 `null` 值。

### 异常

`SyntaxError`

若传入的字符串不符合 JSON 规范，则会抛出此异常。

示例
--

### 使用 `JSON.parse()`


```js
JSON.parse("{}"); // {}
JSON.parse("true"); // true
JSON.parse('"foo"'); // "foo"
JSON.parse('[1, 5, "false"]'); // [1, 5, "false"]
JSON.parse("null"); // null
```

### 使用 `reviver` 函数

如果指定了 `reviver` 函数，则解析出的 JavaScript 值（解析值）会经过一次转换后才将被最终返回（返回值）。更具体点讲就是：解析值本身以及它所包含的所有属性，会按照一定的顺序（从最最里层的属性开始，一级级往外，最终到达顶层，也就是解析值本身）分别的去调用 `reviver` 函数，在调用过程中，当前属性所属的对象会作为 `this` 值，当前属性名和属性值会分别作为第一个和第二个参数传入 `reviver` 中。如果 `reviver` 返回 `undefined`，则当前属性会从所属对象中删除，如果返回了其他值，则返回的值会成为当前属性新的属性值。

当遍历到最顶层的值（解析值）时，传入 `reviver` 函数的参数会是空字符串 `""`（因为此时已经没有真正的属性）和当前的解析值（有可能已经被修改过了），当前的 `this` 值会是 `{"": 修改过的解析值}`，在编写 `reviver` 函数时，要注意到这个特例。（这个函数的遍历顺序依照：从最内层开始，按照层级顺序，依次向外遍历）


```js
JSON.parse('{"p": 5}', function (k, v) {
  if (k === "") return v; // 如果到了最顶层，则直接返回属性值，
  return v \* 2; // 否则将属性值变为原来的 2 倍。
}); // { p: 10 }

JSON.parse('{"1": 1, "2": 2,"3": {"4": 4, "5": {"6": 6}}}', function (k, v) {
  console.log(k); // 输出当前的属性名，从而得知遍历顺序是从内向外的，
  // 最后一个属性名会是个空字符串。
  return v; // 返回原始属性值，相当于没有传递 reviver 参数。
});

// 1
// 2
// 4
// 6
// 5
// 3
// ""
```

### `JSON.parse()` 不允许用逗号作为结尾


```js
// both will throw a SyntaxError
JSON.parse("[1, 2, 3, 4, ]");
JSON.parse('{"foo" : 1, }');
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-json.parse |

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

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

参见
--

* `JSON.stringify()`