Atomics.sub() - JavaScript

Atomics.sub()
=============

**`Atomics.sub()`** 静态方法对数组中的指定位置减去给定的值，并返回该位置的旧值。此原子操作保证在修改后的值写回之前不会发生其他写操作。

尝试一下
----

语法
--

```js
Atomics.sub(typedArray, index, value)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中的要减去 `value` 的位置。

`value`

要减去的数字。

### 返回值

给定位置的旧值 (`typedArray[index]`)。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

示例
--

### 使用 sub()

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 48;

Atomics.sub(ta, 0, 12); // 返回 48，即旧的值
Atomics.load(ta, 0); // 36
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.sub |

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

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

参见
--

* `Atomics`
* `Atomics.add()`


Atomics.xor() - JavaScript

Atomics.xor()
=============

**`Atomics.xor()`** 静态方法会将给定的值与数组指定位置上的值进行按位异或运算，并返回该位置的旧值。此原子操作保证在修改后的值写回之前不会发生其他写操作。

尝试一下
----

语法
--

```js
Atomics.xor(typedArray, index, value)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中要进行按位异或运算的位置。

`value`

要进行按位异或运算的值。

### 返回值

给定位置的旧值（`typedArray[index]`）。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

描述
--

当 `a` 和 `b` 不同时，按位异或运算结果为 1。异或运算的真值表如下：

| `a` | `b` | `a ^ b` |
| --- | --- | --- |
| 0 | 0 | 0 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 0 |

例如，`5 ^ 1` 按位异或运算的结果是 `0100`，也就是十进制的 4。
```

5  0101
1  0001
   ----

4  0100
```

### 使用 xor()

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 5;

Atomics.xor(ta, 0, 1); // 返回 5，即旧的值
Atomics.load(ta, 0); // 4
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.xor |

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

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

参见
--

* `Atomics`
* `Atomics.and()`
* `Atomics.or()`


Atomics.or() - JavaScript

Atomics.or()
============

**`Atomics.or()`** 静态方法会将给定的值与数组指定位置上的值进行按位或运算，并返回该位置的旧值。此原子操作保证在修改后的值写回之前不会发生其他写操作。

尝试一下
----

语法
--

```js
Atomics.or(typedArray, index, value)
```

### 参数

`typedArray`

一个整数类型数组。`Int8Array`、`Uint8Array`、`Int16Array`、`Uint16Array`、`Int32Array`、`Uint32Array`、`BigInt64Array` 或 `BigUint64Array` (en-US) 之一。

`index`

`typedArray` 中要进行按位或运算的位置。

`value`

要进行按位或运算的值。

### 返回值

给定位置的旧值（`typedArray[index]`）。

### 异常

`TypeError`

如果 `typedArray` 不是允许的整数类型数组之一，则抛出该异常。

`RangeError`

如果 `index` 超出 `typedArray` 的范围，则抛出该异常。

描述
--

当 `a` 或 `b` 为 1 时，按位或运算结果为 1。或运算的真值表如下：

| `a` | `b` | `a | b` |
| --- | --- | --- |
| 0 | 0 | 0 |
| 0 | 1 | 1 |
| 1 | 0 | 1 |
| 1 | 1 | 1 |

例如， `5 | 1` 按位或运算的结果是 `0101` ，也就是十进制的 5：
```

5  0101
1  0001
   ----

5  0101
```

示例
--

### 使用 or()

```js
const sab = new SharedArrayBuffer(1024);
const ta = new Uint8Array(sab);
ta[0] = 2;

Atomics.or(ta, 0, 1); // 返回 2，即旧的值
Atomics.load(ta, 0); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-atomics.or |

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

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

参见
--

* `Atomics`
* `Atomics.and()`
* `Atomics.xor()`


Proxy.revocable() - JavaScript

Proxy.revocable()
=================

**`Proxy.revocable()`** 方法可以用来创建一个可撤销的代理对象。

语法
--
```

Proxy.revocable(target, handler);
```

`target`

将用 `Proxy` 封装的目标对象。可以是任何类型的对象，包括原生数组，函数，甚至可以是另外一个代理对象。

`handler`

一个对象，其属性是一批可选的函数，这些函数定义了对应的操作被执行时代理的行为。

### 返回值

返回一个包含了代理对象本身和它的撤销方法的可撤销 `Proxy` 对象。

描述
--

该方法的返回值是一个对象，其结构为： `{"proxy": proxy, "revoke": revoke}`，其中：

`proxy`

表示新生成的代理对象本身，和用一般方式 `new Proxy(target, handler)` 创建的代理对象没什么不同，只是它可以被撤销掉。

`revoke`

撤销方法，调用的时候不需要加任何参数，就可以撤销掉和它一起生成的那个代理对象。

一旦某个代理对象被撤销，它将变得几乎完全不可调用，在它身上执行任何的**可代理操作**都会抛出 `TypeError` 异常（注意，可代理操作一共有 `14 种`，执行这 14 种操作以外的操作不会抛出异常）。一旦被撤销，这个代理对象便不可能被直接恢复到原来的状态，同时和它关联的**目标对象**以及**处理器对象**都有可能被垃圾回收掉。再次调用撤销方法 `revoke()` 则不会有任何效果，但也不会报错。

示例
--

```js
var revocable = Proxy.revocable(
  {},
  {
    get(target, name) {
      return "[[" + name + "]]";
    },
  },
);
var proxy = revocable.proxy;
proxy.foo; // "[[foo]]"

revocable.revoke();

console.log(proxy.foo); // 抛出 TypeError
proxy.foo = 1; // 还是 TypeError
delete proxy.foo; // 又是 TypeError
typeof proxy; // "object"，因为 typeof 不属于可代理操作
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy.revocable |

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

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

参见
--

* `Proxy`


Proxy() 构造器 - JavaScript

Proxy() 构造器
===========

**`Proxy()`** 构造器用来创建 `Proxy` 对象。语法
--

```js
new Proxy(target, handler)
```

### 参数

`target`

`Proxy` 会对 target 对象进行包装。它可以是任何类型的对象，包括内置的数组，函数甚至是另一个代理对象。

`handler`

它是一个对象，它的属性提供了某些操作发生时所对应的处理函数。

描述
--

我们可以使用 `Proxy()` 构造器来创建一个新的 `Proxy` 对象。构造器接收两个主要参数：

* `target` 被代理的对象
* `handler` 被代理对象上的自定义行为

一个空的 `handler` 参数将会创建一个与被代理对象行为几乎完全相同的代理对象。通过在 `handler` 对象上定义一组处理函数，你可以自定义被代理对象的一些特定行为。例如，通过定义 `get()` 你就可以自定义被代理对象的属性访问器。

### 处理函数

本节列出了所有你可以自定义的处理函数。处理函数有时候也被成为“劫持”（traps），这是由于它们会对底层被代理对象的调用进行劫持。

`handler.apply()`

函数调用劫持。

`handler.construct()`

`new` 操作符劫持

`handler.defineProperty()`

`Object.defineProperty`调用劫持。

`handler.deleteProperty()`

`delete` 操作符劫持。

`handler.get()`

获取属性值劫持。

`handler.getOwnPropertyDescriptor()`

`Object.getOwnPropertyDescriptor` 调用劫持。

`handler.getPrototypeOf()`

`Object.getPrototypeOf`调用劫持。

`handler.has()`

`in` 操作符劫持。

`handler.isExtensible()`

`Object.isExtensible`调用劫持。

`handler.ownKeys()`

`Object.getOwnPropertyNames` 和`Object.getOwnPropertySymbols`调用劫持。

`handler.preventExtensions()`

`Object.preventExtensions`调用劫持。

`handler.set()`

设置属性值劫持。

`handler.setPrototypeOf()`

`Object.setPrototypeOf`调用劫持。

示例
--

### 选择性代理属性访问器

本例中，被代理对象有两个属性： `notProxied` 和 `proxied` 。我们定义了一个处理函数，它为 `proxied` 属性返回一个不同的值，而其他属性返回原值。

```js
const target = {
  notProxied: "original value",
  proxied: "original value",
};

const handler = {
  get: function (target, prop, receiver) {
    if (prop === "proxied") {
      return "replaced value";
    }
    return Reflect.get(...arguments);
  },
};

const proxy = new Proxy(target, handler);

console.log(proxy.notProxied); // "original value"
console.log(proxy.proxied); // "replaced value"
```

规范
--

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

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

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

参见
--

* 元编程指南
* `Reflect`


handler.getPrototypeOf() - JavaScript

handler.getPrototypeOf()
========================

**`handler.getPrototypeOf()`** 是一个代理（Proxy）方法，当读取代理对象的原型时，该方法就会被调用。

尝试一下
----

语法
--

```js
const p = new Proxy(obj, {
  getPrototypeOf(target) {
  ...
  }
});
```

### 参数

当 `getPrototypeOf` 方法被调用时，`this` 指向的是它所属的处理器对象。

`target`

被代理的目标对象。

### 返回值

`getPrototypeOf` 方法的返回值必须是一个对象或者 `null`。

描述
--

在 JavaScript 中，下面这五种操作（方法/属性/运算符）可以触发 JS 引擎读取一个对象的原型，也就是可以触发 `getPrototypeOf()` 代理方法的运行：

* `Object.getPrototypeOf()`
* `Reflect.getPrototypeOf()`
* `Object.prototype.__proto__`
* `Object.prototype.isPrototypeOf()`
* `instanceof`

如果遇到了下面两种情况，JS 引擎会抛出 `TypeError` 异常：

* `getPrototypeOf()` 方法返回的不是对象也不是 `null`。
* 目标对象是不可扩展的，且 `getPrototypeOf()` 方法返回的原型不是目标对象本身的原型。
示例
--

### 基本用法

```js
var obj = {};
var proto = {};
var handler = {
  getPrototypeOf(target) {
    console.log(target === obj); // true
    console.log(this === handler); // true
    return proto;
  },
};

var p = new Proxy(obj, handler);
console.log(Object.getPrototypeOf(p) === proto); // true
```

### 5 种触发 getPrototypeOf 代理方法的方式

```js
var obj = {};
var p = new Proxy(obj, {
  getPrototypeOf(target) {
    return Array.prototype;
  },
});
console.log(
  Object.getPrototypeOf(p) === Array.prototype, // true
  Reflect.getPrototypeOf(p) === Array.prototype, // true
  p.__proto__ === Array.prototype, // true
  Array.prototype.isPrototypeOf(p), // true
  p instanceof Array, // true
);
```

### 两种情况下的异常

```js
var obj = {};
var p = new Proxy(obj, {
  getPrototypeOf(target) {
    return "foo";
  },
});
Object.getPrototypeOf(p); // TypeError: "foo" is not an object or null

var obj = Object.preventExtensions({});
var p = new Proxy(obj, {
  getPrototypeOf(target) {
    return {};
  },
});
Object.getPrototypeOf(p); // TypeError: expected same prototype value
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-getprototypeof |

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

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

参见
--

* `Proxy`
* `handler` (en-US)
* `Object.getPrototypeOf()`
* `Reflect.getPrototypeOf()`


handler.deleteProperty() - JavaScript

handler.deleteProperty()
========================

**`handler.deleteProperty()`** 方法用于拦截对对象属性的 `delete` 操作。

语法
--

```js
var p = new Proxy(target, {
  deleteProperty: function (target, property) {},
});
```

### 参数

`deleteProperty` 方法将会接受以下参数。`this` 被绑定在 handler 上。

`target`

目标对象。

`property`

待删除的属性名。

### 返回值

`deleteProperty` 必须返回一个 `Boolean` 类型的值，表示了该属性是否被成功删除。

描述
--

**`handler.deleteProperty()`** 方法可以拦截 `delete` 操作。

### 拦截

该方法会拦截以下操作：

* 删除属性：`delete proxy[foo]` 和 `delete proxy.foo`
* `Reflect.deleteProperty()`
### 不变量

如果违背了以下不变量，proxy 将会抛出一个 `TypeError`:

* 如果目标对象的属性是不可配置的，那么该属性不能被删除。
示例
--

以下代码演示了对 `delete` 操作的拦截。

```js
var p = new Proxy(
  {},
  {
    deleteProperty: function (target, prop) {
      console.log("called: " + prop);
      return true;
    },
  },
);

delete p.a; // "called: a"
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-delete-p |

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

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

另见
--

* `Proxy`
* `handler` (en-US)
* `delete` 操作符
* `Reflect.deleteProperty()`


handler.getOwnPropertyDescriptor() - JavaScript

handler.getOwnPropertyDescriptor()
==================================

**`handler.getOwnPropertyDescriptor()`** 方法是 `Object.getOwnPropertyDescriptor()` 的钩子。

语法
--

```js
var p = new Proxy(target, {
  getOwnPropertyDescriptor: function (target, prop) {},
});
```

### 参数

`下列参数会被传入 getOwnPropertyDescriptor` 方法中。这是绑定到 handler 上。

`target`

目标对象。

`prop`

返回属性名称的描述。

### 返回值

`getOwnPropertyDescriptor` 方法必须返回一个 object 或 `undefined`。

描述
--

**`handler.getOwnPropertyDescriptor()`** 方法是 `Object.getOwnPropertyDescriptor()` 的陷阱。

### 拦截

这个陷阱可以拦截这些操作：

* `Object.getOwnPropertyDescriptor()`
* `Reflect.getOwnPropertyDescriptor()`
### 不变量

如果下列不变量被违反，代理将抛出一个 `TypeError`：

* `getOwnPropertyDescriptor` 必须返回一个 object 或 `undefined`。
* 如果属性作为目标对象的不可配置的属性存在，则该属性无法报告为不存在。
* 如果属性作为目标对象的属性存在，并且目标对象不可扩展，则该属性无法报告为不存在。
* 如果属性不存在作为目标对象的属性，并且目标对象不可扩展，则不能将其报告为存在。
* 属性不能被报告为不可配置，如果它不作为目标对象的自身属性存在，或者作为目标对象的可配置的属性存在。
* Object.getOwnPropertyDescriptor（target）的结果可以使用 Object.defineProperty 应用于目标对象，也不会抛出异常。
示例
--

以下是 `Object.getOwnPropertyDescriptor()` 的代码陷阱：

```js
var p = new Proxy(
  { a: 20 },
  {
    getOwnPropertyDescriptor: function (target, prop) {
      console.log("called: " + prop);
      return { configurable: true, enumerable: true, value: 10 };
    },
  },
);

console.log(Object.getOwnPropertyDescriptor(p, "a").value); // "called: a"; output 10
```

以下代码则违反了不变量。

```js
var obj = { a: 10 };
Object.preventExtensions(obj);
var p = new Proxy(obj, {
  getOwnPropertyDescriptor: function (target, prop) {
    return undefined;
  },
});

Object.getOwnPropertyDescriptor(p, "a"); // TypeError is thrown
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-getownproperty-p |

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

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

参见
--

* `Proxy`
* `handler` (en-US)
* `Object.getOwnPropertyDescriptor()`
* `Reflect.getOwnPropertyDescriptor()`


handler.ownKeys() - JavaScript

handler.ownKeys()
=================

**`handler.ownKeys()`** 方法用于拦截 `Reflect.ownKeys()`.

尝试一下
----

语法
--

```js
var p = new Proxy(target, {
  ownKeys: function (target) {},
});
```

### 参数

下面的参数被传递给 ownKeys。`this` 被绑定在 `handler` 上。

`target`

目标对象。

### 返回值

`ownKeys` 方法必须返回一个可枚举对象。

描述
--

**`handler.ownKeys()`** 方法用于拦截 `Reflect.ownKeys()`.

### 拦截

该拦截器可以拦截以下操作::

* `Object.getOwnPropertyNames()`
* `Object.getOwnPropertySymbols()`
* `Object.keys()`
* `Reflect.ownKeys()`
### 约束

如果违反了下面的约束，proxy 将抛出错误 `TypeError`:

* `ownKeys` 的结果必须是一个数组。
* 数组的元素类型要么是一个 `String` ，要么是一个 `Symbol`.
* 结果列表必须包含目标对象的所有不可配置（non-configurable）、自有（own）属性的 key.
* 如果目标对象不可扩展，那么结果列表必须包含目标对象的所有自有（own）属性的 key，不能有其他值。
示例
--

下面的代码拦截 `Object.getOwnPropertyNames()`.

```js
var p = new Proxy(
  {},
  {
    ownKeys: function (target) {
      console.log("called");
      return ["a", "b", "c"];
    },
  },
);

console.log(Object.getOwnPropertyNames(p)); // "called"; outputs [ 'a', 'b', 'c' ]
```

下面的代码违反了约定

```js
var obj = {};
Object.defineProperty(obj, "a", {
  configurable: false,
  enumerable: true,
  value: 10,
});

var p = new Proxy(obj, {
  ownKeys: function (target) {
    return [123, 12.5, true, false, undefined, null, {}, []];
  },
});

console.log(Object.getOwnPropertyNames(p));

// TypeError: proxy [[OwnPropertyKeys]] 必须返回一个数组
// 数组元素类型只能是 String 或 Symbol
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-ownpropertykeys |

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

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

另见
--

* `Proxy`
* `handler` (en-US)
* `Object.getOwnPropertyNames()`
* `Reflect.ownKeys()`


handler.defineProperty() - JavaScript

handler.defineProperty()
========================

**`handler.defineProperty()`** 用于拦截对象的 `Object.defineProperty()` 操作。

语法
--

```js
var p = new Proxy(target, {
  defineProperty: function (target, property, descriptor) {},
});
```

### 参数

下列参数将会被传递给 `defineProperty` 方法。`this` 绑定在 handler 对象上。

`target`

目标对象。

`property`

待检索其描述的属性名。

`descriptor`

待定义或修改的属性的描述符。

### 返回值

`defineProperty` 方法必须以一个 `Boolean` 返回，表示定义该属性的操作成功与否。

描述
--

**`handler.defineProperty()`** 用于拦截对对象的 `Object.defineProperty()` 操作。

### 拦截

该方法会拦截目标对象的以下操作：

* `Object.defineProperty()`
* `Reflect.defineProperty()`
* `proxy.property='value'`
### 不变量

如果违背了以下的不变量，proxy 会抛出 `TypeError`:

* 如果目标对象不可扩展，将不能添加属性。
* 不能添加或者修改一个属性为不可配置的，如果它不作为一个目标对象的不可配置的属性存在的话。
* 如果目标对象存在一个对应的可配置属性，这个属性可能不会是不可配置的。
* 如果一个属性在目标对象中存在对应的属性，那么 `Object.defineProperty(target, prop, descriptor)` 将不会抛出异常。
* 在严格模式下，`false` 作为 `handler.defineProperty` 方法的返回值的话将会抛出 `TypeError` 异常。
示例
--

以下代码演示如何拦截对目标对象的 `Object.defineProperty()` 操作。

```js
var p = new Proxy(
  {},
  {
    defineProperty: function (target, prop, descriptor) {
      console.log("called: " + prop);
      return true;
    },
  },
);

var desc = { configurable: true, enumerable: true, value: 10 };
Object.defineProperty(p, "a", desc); // "called: a"
```

当调用 `Object.defineProperty()` 或者 `Reflect.defineProperty()`，传递给 `defineProperty` 的 `descriptor` 有一个限制 - 只有以下属性才有用，非标准的属性将会被无视：

* `enumerable`
* `configurable`
* `writable`
* `value`
* `get`
* `set`

```js
var p = new Proxy(
  {},
  {
    defineProperty(target, prop, descriptor) {
      console.log(descriptor);
      return Reflect.defineProperty(target, prop, descriptor);
    },
  },
);

Object.defineProperty(p, "name", {
  value: "proxy",
  type: "custom",
}); // { value: 'proxy' }
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-defineownproperty-p-desc |

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

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

另见
--

* `Proxy`
* `handler` (en-US)
* `Object.defineProperty()`
* `Reflect.defineProperty()`


handler.get() - JavaScript

handler.get()
=============

**`handler.get()`** 方法用于拦截对象的读取属性操作。

语法
--

```js
var p = new Proxy(target, {
  get: function (target, property, receiver) {},
});
```

### 参数

以下是传递给 get 方法的参数，`this 上下文绑定在`handler 对象上。

`target`

目标对象。

`property`

被获取的属性名。

`receiver`

Proxy 或者继承 Proxy 的对象

### 返回值

get 方法可以返回任何值。

描述
--

**`handler.get`** 方法用于拦截对象的读取属性操作。

### 拦截

该方法会拦截目标对象的以下操作：

* 访问属性：`proxy[foo] 和` `proxy.bar`
* 访问原型链上的属性：`Object.create(proxy)[foo]`
* `Reflect.get()`
### 约束

如果违背了以下的约束，proxy 会抛出 `TypeError`:

* 如果要访问的目标属性是不可写以及不可配置的，则返回的值必须与该目标属性的值相同。
* 如果要访问的目标属性没有配置访问方法，即 get 方法是 undefined 的，则返回值必须为 undefined。
示例
--

以下代码演示如何拦截属性值的读取操作。

```js
var p = new Proxy(
  {},
  {
    get: function (target, prop, receiver) {
      console.log("called: " + prop);
      return 10;
    },
  },
);

console.log(p.a); // "called: a"; ouptut 10
```

以下代码演示违反约束的情况。

```js
var obj = {};
Object.defineProperty(obj, "a", {
  configurable: false,
  enumerable: false,
  value: 10,
  writable: false,
});

var p = new Proxy(obj, {
  get: function (target, prop) {
    return 20;
  },
});

p.a; //会抛出 TypeError
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-get-p-receiver |

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

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

另见
--

* `Proxy`
* `handler` (en-US)
* `Reflect.get()`


handler.has() - JavaScript

handler.has()
=============

**`handler.has()`** 方法是针对 `in` 操作符的代理方法。

尝试一下
----

语法
--

```js
var p = new Proxy(target, {
  has: function (target, prop) {},
});
```

### 参数

`下面是传递给 has` 方法的参数。`this` is bound to the handler.

`target`

目标对象。

`prop`

需要检查是否存在的属性。

### 返回值

`has` 方法返回一个 boolean 属性的值。

描述
--

**`handler.has`** 方法可以看作是针对 `in` 操作的钩子。

### 拦截

这个钩子可以拦截下面这些操作：

* 属性查询：`foo in proxy`
* 继承属性查询：`foo in Object.create(proxy)`
* `with` 检查`: with(proxy) { (foo); }`
* `Reflect.has()`
### 约束

如果违反了下面这些规则，proxy 将会抛出 `TypeError`:

* 如果目标对象的某一属性本身不可被配置，则该属性不能够被代理隐藏。
* 如果目标对象为不可扩展对象，则该对象的属性不能够被代理隐藏
示例
--

下面的代码拦截了 `in` 操作符。

```js
var p = new Proxy(
  {},
  {
    has: function (target, prop) {
      console.log("called: " + prop);
      return true;
    },
  },
);

console.log("a" in p); // "called: a"; outputs true
```

下面的代码违反了约束。

```js
var obj = { a: 10 };
Object.preventExtensions(obj);
var p = new Proxy(obj, {
  has: function (target, prop) {
    return false;
  },
});

"a" in p; // TypeError is thrown
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-hasproperty-p |

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

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

其他
--

* `Proxy`
* `handler` (en-US)
* `in` operator
* `Reflect.has()`


handler.construct() - JavaScript

handler.construct()
===================

**`handler.construct()`** 方法用于拦截 `new` 操作符。为了使 new 操作符在生成的 Proxy 对象上生效，用于初始化代理的目标对象自身必须具有 [[Construct]] 内部方法（即 `new target` 必须是有效的）。

尝试一下
----

语法
--

```js
var p = new Proxy(target, {
  construct: function (target, argumentsList, newTarget) {},
});
```

### 参数

下面的参数将会传递给 `construct` 方法，`this` 绑定在 handler 上。

`target`

目标对象。

`argumentsList`

constructor 的参数列表。

`newTarget`

最初被调用的构造函数，就上面的例子而言是 p。

### 返回值

`construct` 方法必须返回一个对象。

描述
--

**`handler.construct()`** 方法用于拦截 `new`操作符。

### 拦截

该拦截器可以拦截以下操作：

* `new proxy(...args)`
* `Reflect.construct()`
### 约束

如果违反以下约定，代理将会抛出错误 `TypeError`:

* 必须返回一个对象。
示例
--

下面代码演示如何拦截 `new` 操作。

```js
var p = new Proxy(function () {}, {
  construct: function (target, argumentsList, newTarget) {
    console.log("called: " + argumentsList.join(", "));
    return { value: argumentsList[0] \* 10 };
  },
});

console.log(new p(1).value); // "called: 1"; outputs 10
```

下面的代码违反了约定。

```js
var p = new Proxy(function () {}, {
  construct: function (target, argumentsList, newTarget) {
    return 1;
  },
});

new p(); // TypeError is thrown
```

下面的代码未能正确的初始化 Proxy。Proxy 初始化时，传给它的 `target` 必须具有一个有效的 constructor 供 `new` 操作符调用。

```js
var p = new Proxy(
  {},
  {
    construct: function (target, argumentsList, newTarget) {
      return {};
    },
  },
);

new p(); // TypeError is thrown, "p" is not a constructor
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-construct-argumentslist-newtarget |

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

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

相关主题
----

* `Proxy`
* `handler` (en-US)
* `new` operator.
* `Reflect.construct()`


handler.setPrototypeOf() - JavaScript

handler.setPrototypeOf()
========================

**`handler.setPrototypeOf()`** 方法主要用来拦截 `Object.setPrototypeOf()`.

语法
--

```js
var p = new Proxy(target, {
  setPrototypeOf: function (target, prototype) {},
});
```

### 参数

以下参数传递给 `setPrototypeOf` 方法。

`target`

被拦截目标对象。

`prototype`

对象新原型或为`null`.

### 返回值

如果成功修改了`[[Prototype]]`, `setPrototypeOf` 方法返回 `true`,否则返回 `false`.

描述
--

这个 **`handler.setPrototypeOf`** 方法用于拦截 `Object.setPrototypeOf()`.

### 拦截

这个方法可以拦截以下操作：

* `Object.setPrototypeOf()`
* `Reflect.setPrototypeOf()`
### Invariants

如果违反了下列规则，则 proxy 将抛出一个 `TypeError`：

* `如果 target` 不可扩展，原型参数必须与 `Object.getPrototypeOf(target)` 的值相同。
示例
--

如果你不想为你的对象设置一个新的原型，你的 handler 的 `setPrototypeOf` 方法可以返回 false，也可以抛出异常。

The former approach means that any operation that performs such mutation, that throws an exception on failure to mutate, will have to create the exception itself. For example, `Object.setPrototypeOf()` will create and throw a `TypeError` itself. If the mutation is performed by an operation that *doesn't* ordinarily throw in case of failure, such as `Reflect.setPrototypeOf()`, no exception will be thrown.

```js
var handlerReturnsFalse = {
  setPrototypeOf(target, newProto) {
    return false;
  },
};

var newProto = {},
  target = {};

var p1 = new Proxy(target, handlerReturnsFalse);
Object.setPrototypeOf(p1, newProto); // throws a TypeError
Reflect.setPrototypeOf(p1, newProto); // returns false
```

The latter approach will cause *any* operation that attempts to mutate, to throw. This approach is required if you want even non-throwing operations to throw on failure, or you want to throw a custom exception value.

```js
var handlerThrows = {
  setPrototypeOf(target, newProto) {
    throw new Error("custom error");
  },
};

var newProto = {},
  target = {};

var p2 = new Proxy(target, handlerThrows);
Object.setPrototypeOf(p2, newProto); // throws new Error("custom error")
Reflect.setPrototypeOf(p2, newProto); // throws new Error("custom error")
```

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

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-setprototypeof-v |

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

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

See also
--------

* `Proxy`
* `handler` (en-US)
* `Object.setPrototypeOf()`
* `Reflect.setPrototypeOf()`


handler.set() - JavaScript

handler.set()
=============

**`handler.set()`** 方法是设置属性值操作的捕获器。

尝试一下
----

语法
--

```js
new Proxy(target, {
  set(target, property, value, receiver) {
  }
});
```

### 参数

以下是传递给 `set()` 方法的参数。`this` 绑定在 handler 对象上。

`target`

目标对象。

`property`

将被设置的属性名或 `Symbol`。

`value`

新属性值。

`receiver`

最初接收赋值的对象。通常是 proxy 本身，但 handler 的 set 方法也有可能在原型链上，或以其他方式被间接地调用（因此不一定是 proxy 本身）。

**备注：** 假设有一段代码执行 `obj.name = "jen"`， `obj` 不是一个 proxy，且自身不含 `name` 属性，但是它的原型链上有一个 proxy，那么，那个 proxy 的 `set()` 处理器会被调用，而此时，`obj` 会作为 receiver 参数传进来。

### 返回值

`set()` 方法应当返回一个布尔值。

* 返回 `true` 代表属性设置成功。
* 在严格模式下，如果 `set()` 方法返回 `false`，那么会抛出一个 `TypeError` 异常。
描述
--

`handler.set()` 方法用于拦截设置属性值的操作。

### 拦截

该方法会拦截目标对象的以下操作：

* 指定属性值：`proxy[foo] = bar` 和 `proxy.foo = bar`
* 指定继承者的属性值：`Object.create(proxy)[foo] = bar`
* `Reflect.set()`
### 约束

如果违背以下的约束条件，proxy 会抛出一个 `TypeError` 异常：

* 若目标属性是一个不可写及不可配置的数据属性，则不能改变它的值。
* 如果目标属性没有配置存储方法，即 `[[Set]]` 属性的是 `undefined`，则不能设置它的值。
* 在严格模式下，如果 `set()` 方法返回 `false`，那么也会抛出一个 `TypeError` 异常。
示例
--

以下代码演示如何捕获属性的设置操作。

```js
var p = new Proxy(
  {},
  {
    set: function (target, prop, value, receiver) {
      target[prop] = value;
      console.log("property set: " + prop + " = " + value);
      return true;
    },
  },
);

console.log("a" in p); // false

p.a = 10; // "property set: a = 10"
console.log("a" in p); // true
console.log(p.a); // 10
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-set-p-v-receiver |

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

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

另见
--

* `Proxy`
* `handler` (en-US)
* `Reflect.set()`


handler.apply() - JavaScript

handler.apply()
===============

**`handler.apply()`** 方法用于拦截函数的调用。

尝试一下
----

语法
--

```js
var p = new Proxy(target, {
  apply: function (target, thisArg, argumentsList) {},
});
```

### 参数

以下是传递给 apply 方法的参数，`this` 上下文绑定在 handler 对象上。

`target`

目标对象（函数）。

`thisArg`

被调用时的上下文对象。

`argumentsList`

被调用时的参数数组。

### 返回值

`apply` 方法可以返回任何值。

描述
--

**`handler.apply`** 方法用于拦截函数的调用。

### 拦截

该方法会拦截目标对象的以下操作：

* `proxy(...args)`
* `Function.prototype.apply()` 和 `Function.prototype.call()`
* `Reflect.apply()`
### 约束

如果违反了以下约束，代理将抛出一个 TypeError：

`target` 必须是可被调用的。也就是说，它必须是一个函数对象。

示例
--

以下代码演示如何捕获函数的调用。

```js
var p = new Proxy(function () {}, {
  apply: function (target, thisArg, argumentsList) {
    console.log("called: " + argumentsList.join(", "));
    return argumentsList[0] + argumentsList[1] + argumentsList[2];
  },
});

console.log(p(1, 2, 3)); // "called: 1, 2, 3"; outputs 6
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-call-thisargument-argumentslist |

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

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

另见
--

* `Proxy`
* `handler` (en-US)
* `Function.prototype.apply`
* `Function.prototype.call`
* `Reflect.apply()`


handler.isExtensible() - JavaScript

handler.isExtensible()
======================

**handler.isExtensible()** 方法用于拦截对对象的 Object.isExtensible()。
尝试一下
----

语法
--

```js
var p = new Proxy(target, {
  isExtensible: function (target) {},
});
```

### 参数

下列参数将会被传递给 `isExtensible`方法。this 绑定在 handler 对象上。

`target`

目标对象。

### 返回值

`isExtensible`方法必须返回一个 Boolean 值或可转换成 Boolean 的值。

描述
--

handler.isExtensible() 用于拦截对对象的 Object.isExtensible()。

### 拦截

该方法会拦截目标对象的以下操作：

* `Object.isExtensible()`
* `Reflect.isExtensible()`
### 约束

如果违背了以下的约束，proxy 会抛出 TypeError:

* `Object.isExtensible(proxy)` 必须同 `Object.isExtensible(target)` 返回相同值。
示例
--

以下代码演示`Object.isExtensible()`.

```js
var p = new Proxy(
  {},
  {
    isExtensible: function (target) {
      console.log("called");
      return true; // 也可以 return 1; 等表示为 true 的值
    },
  },
);

console.log(Object.isExtensible(p)); // "called"; outputs true
```

以下代码演示违反约束的情况。

```js
var p = new Proxy(
  {},
  {
    isExtensible: function (target) {
      return false; // return 0; return NaN 等都会报错
    },
  },
);

Object.isExtensible(p); // TypeError is thrown
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-isextensible |

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

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

另见
--

* `Proxy`
* `handler` (en-US)
* `Object.isExtensible()`
* `Reflect.isExtensible()`


handler.preventExtensions() - JavaScript

handler.preventExtensions()
===========================

**`handler.preventExtensions()`** 方法用于设置对`Object.preventExtensions()`的拦截

尝试一下
----

语法
--

```js
var p = new Proxy(target, {
  preventExtensions: function (target) {},
});
```

### 参数

以下参数传递给 `preventExtensions` 方法。它会绑定到这个 handler.

`target`

所要拦截的目标对象。

### 返回值

`preventExtensions` 方法返回一个布尔值。

描述
--

**`handler.preventExtensions()`** 拦截 `Object.preventExtensions()`返回一个布尔值。

### 拦截

这个 trap 可以拦截这些操作：

* `Object.preventExtensions()`
* `Reflect.preventExtensions()`
### 约束

如果违反了下列规则，proxy 则会抛出一个 `TypeError`:

* 如果目标对象是可扩展的，那么只能返回 `false`
示例
--

以下代码演示了如何拦截`Object.preventExtensions()`。

```js
var p = new Proxy(
  {},
  {
    preventExtensions: function (target) {
      console.log("called");
      Object.preventExtensions(target);
      return true;
    },
  },
);

console.log(Object.preventExtensions(p)); // "called"; outputs false
```

以下代码违反了约束。

```js
var p = new Proxy(
  {},
  {
    preventExtensions: function (target) {
      return true;
    },
  },
);

Object.preventExtensions(p); // 抛出类型错误
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-proxy-object-internal-methods-and-internal-slots-preventextensions |

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

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

参考
--

* `Proxy`
* `handler` (en-US)
* `Object.preventExtensions()`
* `Reflect.preventExtensions()`


WeakMap() 构造函数 - JavaScript

WeakMap() 构造函数
==============

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

语法
--

```js
new WeakMap()
new WeakMap(iterable)
```

**备注：** `WeakMap()` 构造函数只能使用 `new` 调用。不使用 `new` 而直接调用会抛出 `TypeError`。

参数
--

`iterable`

一个 `Array` 或者其他实现了 `@@iterator` 方法的可迭代对象，该方法返回一个迭代器对象，该对象会产生一个二元类数组对象，其第一个元素是将被用作 `WeakMap` 键的对象，第二个元素是与该键相关联的值。每个键值对都会被添加到新的 `WeakMap` 对象中。`null` 会被视为 `undefined`。

示例
--

### 使用 WeakMap

```js
const wm1 = new WeakMap();
const wm2 = new WeakMap();
const wm3 = new WeakMap();
const o1 = {};
const o2 = function () {};
const o3 = window;

wm1.set(o1, 37);
wm1.set(o2, "azerty");
wm2.set(o1, o2); // value 可以是任何值，包括对象或函数
wm2.set(o3, undefined);
wm2.set(wm1, wm2); // 键和值可以是任何对象，甚至是 WeakMap！

wm1.get(o2); // "azerty"
wm2.get(o2); // undefined，因为 wm2 上没有 o2 的键
wm2.get(o3); // undefined，因为设置的值就是 undefined

wm1.has(o2); // true
wm2.has(o2); // false
wm2.has(o3); // true（即使值是 undefined）

wm3.set(o1, 37);
wm3.get(o1); // 37

wm1.has(o1); // true
wm1.delete(o1);
wm1.has(o1); // false
```

规范
--

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

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

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

参见
--

* `core-js` 中 `WeakMap` 的 polyfill
* JavaScript 指南中的 `WeakMap`
* 使用 ECMAScript 6 WeakMap 隐藏实现细节
* `Map`
* `Set`
* `WeakSet`


WeakMap.prototype.set() - JavaScript

WeakMap.prototype.set()
=======================

`WeakMap` 实例的 **`set()`** 方法根据指定的键值在该 `WeakMap` 中添加新元素。

尝试一下
----

语法
--

```js
set(key, value)
```

### 参数

`key`

必须是对象或非全局注册的符号。要添加到 `WeakMap` 对象的元素的键。

`value`

任何要添加到 `WeakMap` 对象的元素的值。

### 返回值

该 `WeakMap` 对象

### 异常

`TypeError`

如果 `key` 不是一个对象或非全局注册的符号，则抛出该异常。

示例
--

### 使用 set() 方法

```js
const wm = new WeakMap();
const obj = {};

// 将新元素添加到 WeakMap
wm.set(obj, "foo").set(window, "bar"); // 链式调用

// 更新 WeakMap 中的元素
wm.set(obj, "baz");

// 使用非全局注册的符号作为键
const sym = Symbol("foo");
wm.set(sym, "baz");
wm.set(Symbol.iterator, "qux");
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-weakmap.prototype.set |

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

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

参见
--

* `WeakMap`
* `WeakMap.prototype.get()`
* `WeakMap.prototype.has()`


WeakMap.prototype.delete() - JavaScript

WeakMap.prototype.delete()
==========================

`WeakMap` 实例的 **`delete()`** 方法从该 `WeakMap` 中删除指定的元素。

尝试一下
----

概述
--

**`delete()`** 方法可以从一个 `WeakMap` 对象中删除指定的元素。

语法
--

```js
weakMapInstance.delete(key)
```

### 参数

`key`

要从 `WeakMap` 对象中删除的元素的键。

### 返回值

如果成功在 `WeakMap` 对象中删除了元素，则返回 `true`。如果未在 `WeakMap` 中找到该键，则返回 `false`。如果 `key` 不是对象或非全局注册的符号，则始终返回 `false`。

示例
--

### 使用 delete() 方法

```js
const wm = new WeakMap();
wm.set(window, "foo");

wm.delete(window); // 返回 true。成功删除。

wm.has(window); // 返回 false。WeakMap 中已经不存在 window 对象。
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-weakmap.prototype.delete |

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

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

参见
--

* `WeakMap`


WeakMap.prototype.get() - JavaScript

WeakMap.prototype.get()
=======================

`WeakMap` 实例的 **`get()`** 方法返回该 `WeakMap` 中的指定元素。

尝试一下
----

语法
--

```js
get(key)
```

### 参数

`key`

要从 `WeakMap` 对象返回的元素的键。

### 返回值

该 `WeakMap` 对象中与指定键相关联的元素。如果找不到该键，则返回 `undefined`。如果 `key` 不是对象或非全局注册的符号，则始终返回 `undefined`。

示例
--

### 使用 get() 方法

```js
const wm = new WeakMap();
wm.set(window, "foo");

wm.get(window); // 返回 "foo"。
wm.get("baz"); // 返回 undefined。
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-weakmap.prototype.get |

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

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

参见
--

* `WeakMap`
* `WeakMap.set()`
* `WeakMap.has()`


WeakMap.prototype.has() - JavaScript

WeakMap.prototype.has()
=======================

`WeakMap` 实例的 **`has()`** 返回一个布尔值，指示该 `WeakMap` 中是否存在具有指定键的元素。

尝试一下
----

语法
--

```js
has(key)
```

### 参数

`key`

要测试是否在该 `WeakMap` 对象中存在的元素的键。

### 返回值

如果指定键的元素存在于 `WeakMap` 对象中，则返回 `true`；否则返回 `false`。如果 `key` 不是对象或非全局注册的符号，则始终返回 `false`。

示例
--

### 使用 has 方法

```js
const wm = new WeakMap();
wm.set(window, "foo");

wm.has(window); // 返回 true
wm.has("baz"); // 返回 false
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-weakmap.prototype.has |

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

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

参见
--

* `WeakMap`
* `WeakMap.prototype.set()`
* `WeakMap.prototype.get()`


DataView.prototype.setFloat64() - JavaScript

DataView.prototype.setFloat64()
===============================

**`setFloat64()`** 从 `DataView` 起始位置以 byte 为计数的指定偏移量 (byteOffset) 处储存一个 64-bit 数 (双精度浮点型)。

尝试一下
----

语法
--
```

dataview.setFloat64(byteOffset, value [, littleEndian])
```

### 参数

byteOffset

偏移量，从头开始计算，单位为字节。

value

设置的数值。

littleEndian

可选 Indicates whether the 64-bit float is stored in little- or big-endian format. If false or undefined, a big-endian value is written.

### 返回

`undefined`.

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setFloat64(0, 3);
dataview.getFloat64(0); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setfloat64 |

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

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

相关内容
----

* `DataView`
* `ArrayBuffer`


DataView.prototype.byteOffset - JavaScript

DataView.prototype.byteOffset
=============================

**`byteOffset`** 属性描述了从 `ArrayBuffer` 开始的字节偏移量。

尝试一下
----

语法
--
```

dataview.byteOffset
```

描述
--

`byteOffset` 属性是一个获取 (accessor) 属性，它的 set 属性为 undefined，这意味着它是只读的。值在 `DataView` 被创建时就确定了，且不能改变。

示例
--

### `使用 byteOffset 属性`

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.byteOffset; // 0 (没有指定偏移量)

var dataview2 = new DataView(buffer, 3);
dataview2.byteOffset; // 3 (在构造 DataView 时指定)
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-dataview.prototype.byteoffset |

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

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

参见
--

* `DataView`
* `ArrayBuffer`


DataView.prototype.setInt8() - JavaScript

DataView.prototype.setInt8()
============================

**`setInt8()`** 从 `DataView` 起始位置以 byte 为计数的指定偏移量 (byteOffset) 处储存一个 8-bit 数 (一个字节)。

尝试一下
----

语法
--
```

dataview.setInt8(byteOffset, value)
```

参数
--

byteOffset

偏移量，从头开始计算，单位为字节

value

设置的整数值

### 返回

`undefined`.

### 抛出的错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setInt8(1, 3);
dataview.getInt8(1); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setint8 |

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

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

相关内容
----

* `DataView`
* `ArrayBuffer`


DataView.prototype.getFloat32() - JavaScript

DataView.prototype.getFloat32()
===============================

\*\*`getFloat32()`\*\*方法从相对于`DataView` 的起始位置偏移 n 个字节处获取一个 32-bit 浮点数 (单精度浮点数，4 个字节).

尝试一下
----

语法
--
```

dataview.getFloat32(byteOffset [, littleEndian])
```

### 参数

byteOffset

偏移量，单位为字节，为从视图的开始位置到读取数值的位置的偏移。

littleEndian

可选 表示这个 32 位浮点数是否以 little- or big-endian 格式存储，如果设置为 false 或者不指定，将用 big-endian 格式读取数值。

### 返回

一个带符号的 32 位浮点数。

### 抛出错误

`RangeError`

如果 byteOffset 设置导致读数值时超出了视图的末尾就会抛出错误。

说明
--

没有对齐约束; 多字节值可以从任何偏移处获取。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.getFloat32(1); // 0
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getfloat32 |

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

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

另见
--

* `DataView`
* `ArrayBuffer`


DataView.prototype.setInt16() - JavaScript

DataView.prototype.setInt16()
=============================

\*\*`setInt16()`\*\*从 `DataView` 起始位置以 byte 为计数的指定偏移量 (byteOffset) 处储存一个 16-bit 数 (短整型)。

尝试一下
----

语法
--
```

dataview.setInt16(byteOffset, value [, littleEndian])
```

### 参数

byteOffset

偏移量，从头开始计算，单位为字节。

value

设置的数值。

littleEndian

可选 Indicates whether the 16-bit int is stored in little- or big-endian format. If false or undefined, a big-endian value is written.

### 返回

`undefined`.

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setInt16(1, 3);
dataview.getInt16(1); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setint16 |

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

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

相关内容
----

* `DataView`
* `ArrayBuffer`


DataView.prototype.setBigInt64() - JavaScript

DataView.prototype.setBigInt64()
================================

\*\*`setBigInt64()`\*\*方法在距`DataView` 的起始位置的指定字节偏移处存储一个带符号的 64 位整数（long long 类型）值。

尝试一下
----

语法
--
```

dataview.setBigInt64(byteOffset, value [, littleEndian])
```

### 参数说明

byteOffset

字节偏移量，为从视图的起始位置到数据存储位置的字节字节偏移量。

value

作为一个`BigInt`类型设置的数值。满足一个带符号的 64 位整数的最大可能数值是 `2n ** (64n -1n) - 1n` (`9223372036854775807n`)。当发生溢出时，将会变成负数 (`-9223372036854775808n`)。

littleEndian

可选 为可选参数，表示这个 64 位整数是否以little-endian 或者 big-endian格式存储。如果设置为`false` 或者未指定（`undefined`），将会写入一个 big-endian（大端模式：高位字节排放在内存的低地址端，低位字节排放在内存的高地址端）格式的数值。

### 返回值

`undefined`.

### 抛出的错误

`RangeError`

如果 `byteOffset`设置导致存储该数值时超出了视图的末尾位置，将会抛出错误。

示例
--

### 使用 `setBigInt64` 方法

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setBigInt64(0, 3n);
dataview.getBigInt64(0); // 3n
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setbigint64 |

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

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

请参阅
---

* `DataView`
* `ArrayBuffer`
* `BigInt`


DataView.prototype.setUint32() - JavaScript

DataView.prototype.setUint32()
==============================

**`setUint32()`** 从 `DataView` 起始位置以 byte 为计数的指定偏移量 (byteOffset) 处储存一个 32-bit 数 (无符号长整型)。

尝试一下
----

语法
--
```

dataview.setUint32(byteOffset, value [, littleEndian])
```

### 参数

byteOffset

偏移量，从头开始计算，单位为字节。

value

设置的数值。

littleEndian

可选 Indicates whether the 32-bit int is stored in little- or big-endian format. If false or undefined, a big-endian value is written.

### 返回

`undefined`.

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setUint32(1, 3);
dataview.getUint32(1); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setuint32 |

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

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

相关内容
----

* `DataView`
* `ArrayBuffer`


DataView.prototype.getUint8() - JavaScript

DataView.prototype.getUint8()
=============================

**`getUint8()`** 方法从 `DataView`相对于起始位置偏移 n 个字节处开始，获取一个无符号的 8-bit 整数 (一个字节).

尝试一下
----

语法
--
```

dataview.getUint8(byteOffset)
```

参数
--

byteOffset

偏移量，单位为字节，从头开始计算。

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

描述
--

没有对齐约束; 多字节值可以从任何偏移量获取。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.getUint8(1); // 0
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getuint8 |

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

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

相关内容
----

* `DataView`
* `ArrayBuffer`


DataView.prototype.getFloat64() - JavaScript

DataView.prototype.getFloat64()
===============================

**`getFloat64()`** 方法从 `DataView`相对于起始位置偏移 n 个字节处开始，获取一个 64-bit 数 (双精度浮点型，8 个字节)。

尝试一下
----

语法
--
```

dataview.getFloat64(byteOffset [, littleEndian])
```

### 参数

byteOffset

偏移量，单位为字节，从头开始计算。

littleEndian

可选 Indicates whether the 64-bit float is stored in little- or big-endian format. If false or undefined, a big-endian value is read.

### 返回

一个双精度浮点型 64 位数。

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

描述
--

没有对齐约束; 多字节值可以从任何偏移量获取。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.getFloat64(1); // 0
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getfloat64 |

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

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

另见
--

* `DataView`
* `ArrayBuffer`


DataView.prototype.setUint16() - JavaScript

DataView.prototype.setUint16()
==============================

**`setUint16()`** 从 `DataView` 起始位置以 byte 为计数的指定偏移量 (byteOffset) 处储存一个 16-bit 数 (无符号短整型)。

尝试一下
----

语法
--
```

dataview.setUint16(byteOffset, value [, littleEndian])
```

### 参数

byteOffset

偏移量，从头开始计算，单位为字节。

value

设置的数值。

littleEndian

可选 Indicates whether the 16-bit int is stored in little- or big-endian format. If false or undefined, a big-endian value is written.

### 返回

`undefined`.

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setUint16(1, 3);
dataview.getUint16(1); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setuint16 |

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

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

相关内容
----

* `DataView`
* `ArrayBuffer`


DataView.prototype.getBigUint64() - JavaScript

DataView.prototype.getBigUint64()
=================================

`DataView` 的 **`getBigUint64()`** 方法，从 `DataView` 的指定的字节偏移量位置读取 8 个字节，并将其解析为一个无符号 64 位整数（unsigned long long）。

尝试一下
----

语法
--

```js
getBigUint64(byteOffset)
getBigUint64(byteOffset, littleEndian)
```

### 参数

byteOffset

表示从视图的开始位置到要读取数据位置的偏移量，以字节为单位。

`littleEndian` 可选

指示 64 位整数是以小端还是大端格式存储。如果值为 `false` 或 `undefined`，则以大端格式读取。

### 返回值

一个 `BigInt`。

### 异常

`RangeError`

如果 `byteOffset` 设置导致读取时超出了视图的末尾位置，则抛出该错误。

描述
--

没有对齐约束，可以从任意偏移量获取多字节值。

示例
--

### 使用 `getBigUint64` 方法

```js
const buffer = new ArrayBuffer(8);
const dataview = new DataView(buffer);
dataview.getBigUint64(0); // 0n
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getbiguint64 |

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

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

参见
--

* `DataView`
* `ArrayBuffer`
* `BigInt`


DataView.prototype.getInt8() - JavaScript

DataView.prototype.getInt8()
============================

**`getInt8()`** 方法从 `DataView` 相对于起始位置偏移 n 个字节处开始，获取一个有符号的 8-bit 整数 (一个字节)。

尝试一下
----

语法
--
```

dataview.getInt8(byteOffset)
```

参数
--

byteOffset

偏移量，单位为字节，从起始位置开始计算。

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

描述
--

没有对齐约束; 多字节值可以从任何偏移量获取。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.getInt8(1); // 0
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getint8 |

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

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

相关内容
----

* `DataView`
* `ArrayBuffer`


DataView.prototype.setFloat32() - JavaScript

DataView.prototype.setFloat32()
===============================

**`setFloat32()`** 从 `DataView`起始位置以 byte 为计数的指定偏移量 (byteOffset) 处储存一个 32-bit 数 (浮点型)。

尝试一下
----

语法
--
```

dataview.setFloat32(byteOffset, value [, littleEndian])
```

### 参数

byteOffset

偏移量，从头开始计算，单位为字节。

value

设置的数值。

littleEndian

可选 Indicates whether the 32-bit float is stored in little- or big-endian format. If false or undefined, a big-endian value is written.

### 返回

`undefined`.

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setFloat32(1, 3);
dataview.getFloat32(1); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setfloat32 |

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

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

相关内容
----

* `DataView`
* `ArrayBuffer`


DataView.prototype.setInt32() - JavaScript

DataView.prototype.setInt32()
=============================

**`setInt32()`** 从 `DataView` 起始位置以 byte 为计数的指定偏移量 (byteOffset) 处储存一个 32-bit 数 (长整型)。

尝试一下
----

语法
--
```

dataview.setInt32(byteOffset, value [, littleEndian])
```

### 参数

byteOffset

偏移量，从头开始计算，单位为字节。

value

设置的数值。

littleEndian

可选 Indicates whether the 32-bit int is stored in little- or big-endian format. If false or undefined, a big-endian value is written.

### 返回

`undefined`.

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setInt32(1, 3);
dataview.getInt32(1); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setint32 |

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

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

相关
--

* `DataView`
* `ArrayBuffer`


DataView.prototype.getUint16() - JavaScript

DataView.prototype.getUint16()
==============================

**`getUint16()`** 方法从 `DataView` 相对于起始位置偏移 n 个字节处开始，获取一个 16-bit 数 (无符号短整型，2 个字节)。

尝试一下
----

语法
--
```

dataview.getUint16(byteOffset [, littleEndian])
```

### 参数

byteOffset

偏移量，单位为字节，从头开始计算。

littleEndian

可选 Indicates whether the 16-bit int is stored in little- or big-endian format. If false or undefined, a big-endian value is read.

### 返回

一个无符号短整型 16 位数。

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

描述
--

没有对齐约束; 多字节值可以从任何偏移量获取。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.getUint16(1); // 0
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getuint16 |

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

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

另见
--

* `DataView`
* `ArrayBuffer`


DataView.prototype.getInt16() - JavaScript

DataView.prototype.getInt16()
=============================

**`getInt16()`** 方法从 `DataView` 相对于起始位置偏移 n 个字节处开始，获取一个 16-bit 数 (短整型，2 个字节)。

尝试一下
----

语法
--
```

dataview.getInt16(byteOffset [, littleEndian])
```

### 参数

byteOffset

偏移量，单位为字节，从头开始计算。

littleEndian

可选 表示该 16 位整数是否以 little- or big-endian 格式存储的（就是使用的字节序格式，具体参考链接页面）；如果传入的值为 `true`，就表示使用 little-endian（低字节序），如果传入的值为 `false` 或者 `undefined`，则会使用 big-endian（高字节序）方式读值。

### 返回

一个短整型 16 位数。

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

描述
--

没有对齐约束; 多字节值可以从任何偏移量获取。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.getInt16(1); // 0
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getint16 |

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

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

另见
--

* `DataView`
* `ArrayBuffer`


getBigInt64() - JavaScript

getBigInt64()
=============

**`getBigInt64()`** 方法从 `DataView` 开始获取一个指定偏移量的有符号 64 位整数 (long long) 。

尝试一下
----

语法
--
```

dataview.getBigInt64(byteOffset [, littleEndian])
```

### 参数

byteOffset

偏移量，以字节为单位。指明视图开始读取数据的偏移量。

littleEndian

可选 指明该 64 位整型数值的存储方式（ 大小端模式）。如果为 `false` 或 `undefined`, 则按大端方式读取数据。

### 返回值

一个 `BigInt`.

### 异常抛出

`RangeError`

如果 `byteOffset` 设置的偏移量超出了视图的范围，则抛出该异常。

简介
--

* 没有对齐约束;
* 可以从任何偏移量获取多字节值。
示例
--

### 使用 `getBigInt64` 方法

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.getBigInt64(0); // 0n
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getbigint64 |

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

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

参见
--

* `DataView`
* `ArrayBuffer`
* `BigInt`


DataView.prototype.setUint8() - JavaScript

DataView.prototype.setUint8()
=============================

**`setUint8()`** 从 `DataView` 起始位置以 byte 为计数的指定偏移量 (byteOffset) 处储存一个 8-bit 数 (无符号字节)。

尝试一下
----

语法
--
```

dataview.setUint8(byteOffset, value)
```

### 参数

byteOffset

偏移量，从头开始计算，单位为字节

value

设置的数值

### 返回

`undefined`.

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setUint8(1, 3);
dataview.getUint8(1); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setuint8 |

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

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

相关内容
----

* `DataView`
* `ArrayBuffer`


DataView.prototype.setBigUint64() - JavaScript

DataView.prototype.setBigUint64()
=================================

**`setBigUint64()`** 方法在距 DataView 的起始位置的指定字节偏移处存储一个无符号的 64 位整数（unsigned long long 类型）值。

尝试一下
----

语法
--
```

dataview.setBigUint64(byteOffset, value [, littleEndian])
```

### 参数说明

byteOffset

字节偏移量，为从视图的起始位置到数据存储位置的字节字节偏移量。

value

作为一个 BigInt 类型设置的数值。满足一个无符号的 64 位整数的最大可能数值是 `2n ** 64n - 1n` (`18446744073709551615n`)。当发生溢出时，将会变成 0。

littleEndian

为可选参数，表示这个 64 位整数是否以 little-endian 或者 big-endian 格式存储。如果设置为 false 或者未指定（undefined），将会写入一个 big-endian（大端模式：高位字节排放在内存的低地址端，低位字节排放在内存的高地址端）格式的数值。

### 返回值

`undefined`.

### 抛出的错误

`RangeError`

如果 byteOffset 设置导致存储该数值时超出了视图的末尾位置，将会抛出错误。

示例
--

### 使用 `setBigUint64` 方法

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.setBigUint64(0, 3n);
dataview.getBigUint64(0); // 3n
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.setbiguint64 |

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

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

请参阅
---

* `DataView`
* `ArrayBuffer`
* `BigInt`


DataView.prototype.buffer - JavaScript

DataView.prototype.buffer
=========================

**`buffer`** 属性描述了在构造时被 DataView 引用的 `ArrayBuffer`。

尝试一下
----

语法
--
```

dataview.buffer
```

描述
--

`buffer` 属性是一个访问器 (accessor) 属性，它的 `set` 属性为 `undefined`，这意味着它是只读的。值在 `DataView` 被创建时就确定了，且不能改变。

示例
--

### 使用 `buffer` 属性

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.buffer; // ArrayBuffer { byteLength: 8 }
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-dataview.prototype.buffer |

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

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

参见
--

* `DataView`
* `ArrayBuffer`


DataView.prototype.byteLength - JavaScript

DataView.prototype.byteLength
=============================

**`byteLength`** 属性描述了视图从它的 `ArrayBuffer` 开始的字节长度。

尝试一下
----

语法
--
```

dataview.byteLength
```

描述
--

`byteLength` 属性是一个获取 (accessor) 属性，它的 set 属性为 `undefined`，这意味着它是只读的。值在 `DataView` 被创建时就确定了，且不能改变。如果 `DataView` 没有指定偏移量或 `byteLength`，那么被引用的 `ArrayBuffer` 的字节长度将被返回。

Examples
--------

### Using the `byteLength` property

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.byteLength; // 8 (matches the byteLength of the buffer)

var dataview2 = new DataView(buffer, 1, 5);
dataview2.byteLength; // 5 (as specified when constructing the DataView)

var dataview3 = new DataView(buffer, 2);
dataview3.byteLength; // 6 (due to the offset of the constructed DataView)
```

规范
--

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

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

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

参见
--

* `DataView`
* `ArrayBuffer`


DataView.prototype.getUint32() - JavaScript

DataView.prototype.getUint32()
==============================

**`getUint32()`** 方法从 `DataView` 相对于起始位置偏移 n 个字节处开始，获取一个 32-bit 数 (无符号长整型，4 个字节)。

尝试一下
----

语法
--
```

dataview.getUint32(byteOffset [, littleEndian])
```

### 参数

byteOffset

偏移量，单位为字节，从头开始计算。

littleEndian

可选 Indicates whether the 32-bit int is stored in little- or big-endian format. If false or undefined, a big-endian value is read.

### 返回

一个无符号长整型 32 位数。

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

描述
--

没有对齐约束; 多字节值可以从任何偏移量获取。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.getUint32(1); // 0
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getuint32 |

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

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

另见
--

* `DataView`
* `ArrayBuffer`


DataView.prototype.getInt32() - JavaScript

DataView.prototype.getInt32()
=============================

**`getInt32()`** 方法从 `DataView` 相对于起始位置偏移 n 个字节处开始，获取一个 32-bit 数 (长整型，4 个字节)。

尝试一下
----

语法
--
```

dataview.getInt32(byteOffset [, littleEndian])
```

### 参数

byteOffset

偏移量，单位为字节，从头开始计算。

littleEndian

可选 Indicates whether the 32-bit int is stored in little- or big-endian format. If false or undefined, a big-endian value is read.

### 返回

一个长整型 32 位数。

### 抛出错误

`RangeError`

如果 byteOffset 超出了视图能储存的值，就会抛出错误。

描述
--

没有对齐约束; 多字节值可以从任何偏移量获取。

示例
--

```js
var buffer = new ArrayBuffer(8);
var dataview = new DataView(buffer);
dataview.getInt32(1); // 0
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-dataview.prototype.getint32 |

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

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

另见
--

* `DataView`
* `ArrayBuffer`


Map.prototype.get() - JavaScript

Map.prototype.get()
===================

`Map` 实例的 **`get()`** 方法返回该 map 中的指定元素。如果与所提供的键相关联的值是一个对象，那么你将获得该对象的引用，对该对象所做的任何更改都会有效地在 `Map` 对象中修改它。

尝试一下
----

语法
--

```js
get(key)
```

### 参数

`key`

从 `Map` 对象返回的元素的键。

### 返回值

与指定键相关联的元素，如果键在 `Map` 对象中找不到，则返回 `undefined`。

示例
--

### 使用 get()

```js
const myMap = new Map();
myMap.set("bar", "foo");

console.log(myMap.get("bar")); // 返回 "foo"
console.log(myMap.get("baz")); // 返回 undefined
```

### 使用 get() 获取对对象的引用

```js
const arr = [];
const myMap = new Map();
myMap.set("bar", arr);

myMap.get("bar").push("foo");

console.log(arr); // ["foo"]
console.log(myMap.get("bar")); // ["foo"]
```

注意，持有原始对象引用的映射实际上意味着对象不能被垃圾回收，这可能会导致意外的内存问题。如果你希望存储在 map 中的对象具有与原始对象相同的生命周期，请考虑使用 `WeakMap`。

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.get |

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

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

参见
--

* `Map`
* `Map.prototype.set()`
* `Map.prototype.has()`


Map.prototype.has() - JavaScript

Map.prototype.has()
===================

`Map` 实例的 **`has()`** 方法返回一个布尔值，指示具有指定键的元素是否存在。

尝试一下
----

语法
--

```js
has(key)
```

### 参数

`key`

用于测试 `Map` 对象中是否存在的元素的键。

### 返回值

如果 `Map` 对象中存在具有指定键的元素，则返回 `true`；否则返回 `false`。

示例
--

### 使用 has()

```js
const myMap = new Map();
myMap.set("bar", "foo");

console.log(myMap.has("bar")); // true
console.log(myMap.has("baz")); // false
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.has |

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

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

参见
--

* `Map`
* `Map.prototype.set()`
* `Map.prototype.get()`


Map.prototype.clear() - JavaScript

Map.prototype.clear()
=====================

`Map` 实例的 **`clear()`** 方法会移除该 map 中的所有元素。

尝试一下
----

语法
--

```js
clear()
```

### 参数

无。

### 返回值

无（`undefined`）。

示例
--

### 使用 clear()

```js
const myMap = new Map();
myMap.set("bar", "baz");
myMap.set(1, "foo");

console.log(myMap.size); // 2
console.log(myMap.has("bar")); // true

myMap.clear();

console.log(myMap.size); // 0
console.log(myMap.has("bar")); // false
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.clear |

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

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

参见
--

* `Map`


Map.prototype[@@iterator]() - JavaScript

Map.prototype[@@iterator]()
===========================

`Map` 实例的 **`[@@iterator]()`** 方法实现了可迭代协议以允许 `Map` 对象被大多数语法所接受，例如展开语法和 `for...of` 循环。它返回一个 map 迭代器对象，此对象会以插入顺序生成 map 的键值对。

该属性的初始值与 `Map.prototype.entries` 属性的初始值是同一个函数对象。

尝试一下
----

语法
--

```js
map[Symbol.iterator]()
```

### 参数

无。

### 返回值

与 `Map.prototype.entries()` 返回值相同：一个新的迭代器对象，它会以插入顺序生成 map 的键值对。

示例
--

### 使用 for...of 循环进行迭代

请注意，通常你不需要直接调用此方法。`@@iterator` 方法的存在使得 `Map` 对象可迭代，而像 `for...of` 循环这样的迭代语法会自动调用此方法以获取用于循环的迭代器。

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

for (const entry of myMap) {
  console.log(entry);
}
// ["0", "foo"]
// [1, "bar"]
// [{}, "baz"]

for (const [key, value] of myMap) {
  console.log(`${key}: ${value}`);
}
// 0: foo
// 1: bar
// [Object]: baz
```

### 手动控制迭代器

你仍然可以手动调用返回的迭代器对象的 `next()` 方法来获得最大程度的控制权。

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

const mapIter = myMap[Symbol.iterator]();

console.log(mapIter.next().value); // ["0", "foo"]
console.log(mapIter.next().value); // [1, "bar"]
console.log(mapIter.next().value); // [Object, "baz"]
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype-@@iterator |

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

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

参见
--

* `Map`
* `Map.prototype.entries()`
* `Map.prototype.keys()`
* `Map.prototype.values()`
* `Symbol.iterator`
* 迭代协议


Map.prototype.keys() - JavaScript

Map.prototype.keys()
====================

`Map` 实例的 **`keys()`** 方法返回一个新的 *map 迭代器*对象，该对象包含了此 map 中每个元素的键，按插入顺序排列。

尝试一下
----

语法
--

```js
keys()
```

### 参数

无。

### 返回值

一个新的可迭代迭代器对象。

示例
--

### 使用 keys()

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

const mapIter = myMap.keys();

console.log(mapIter.next().value); // "0"
console.log(mapIter.next().value); // 1
console.log(mapIter.next().value); // {}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.keys |

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

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

参见
--

* `Map.prototype.entries()`
* `Map.prototype.values()`


Map.prototype.size - JavaScript

Map.prototype.size
==================

`Map` 实例的 **`size`** 访问器属性返回此 map 中元素的数量。

尝试一下
----

描述
--

`size` 的值是一个整数，表示 `Map` 对象有多少个键值对。`size` 的设置访问器函数是 `undefined`；你无法更改此属性的值。

示例
--

### 使用 size

```js
const myMap = new Map();
myMap.set("a", "alpha");
myMap.set("b", "beta");
myMap.set("g", "gamma");

console.log(myMap.size); // 3
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-get-map.prototype.size |

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

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

参见
--

* `Map`


Map.prototype.entries() - JavaScript

Map.prototype.entries()
=======================

`Map` 实例的 **`entries()`** 方法返回一个新的 *map 迭代器*对象，该对象包含了此 map 中的每个元素的 `[key, value]` 对，按插入顺序排列。

尝试一下
----

语法
--

```js
entries()
```

### 参数

无。

### 返回值

一个新的可迭代迭代器对象。

示例
--

### 使用 entries()

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

const mapIter = myMap.entries();

console.log(mapIter.next().value); // ["0", "foo"]
console.log(mapIter.next().value); // [1, "bar"]
console.log(mapIter.next().value); // [Object, "baz"]
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.entries |

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

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

参见
--

* `Map.prototype.keys()`
* `Map.prototype.values()`


Map.prototype.values() - JavaScript

Map.prototype.values()
======================

`Map` 实例的 **`values()`** 方法返回一个新的 *map 迭代器*对象，该对象包含此 map 中每个元素的值，按插入顺序排列。

尝试一下
----

语法
--

```js
values()
```

### 参数

无。

### 返回值

一个新的可迭代迭代器对象。

示例
--

### 使用 values()

```js
const myMap = new Map();
myMap.set("0", "foo");
myMap.set(1, "bar");
myMap.set({}, "baz");

const mapIter = myMap.values();

console.log(mapIter.next().value); // "foo"
console.log(mapIter.next().value); // "bar"
console.log(mapIter.next().value); // "baz"
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.values |

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

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

参见
--

* `Map.prototype.entries()`
* `Map.prototype.keys()`


Map.prototype.forEach() - JavaScript

Map.prototype.forEach()
=======================

`Map` 实例的 **`forEach()`** 方法按插入顺序对该 map 中的每个键/值对执行一次提供的函数。

尝试一下
----

语法
--

```js
forEach(callbackFn)
forEach(callbackFn, thisArg)
```

### 参数

`callbackFn`

为 map 中每个元素执行的函数。使用以下参数调用该函数：

`value`

每个迭代的值。

`key`

每个迭代的键。

`map`

正在迭代的 map。

`thisArg` 可选

执行 `callbackFn` 时用作 `this` 的值。

### 返回值

无，`undefined`。

描述
--

`forEach` 方法会对 map 中每个真实存在的键执行一次提供的 `callback`。它不会为被删除的键执行函数。然而，它会为存在但值为 `undefined` 的值执行函数。

`callbackFn` 接收**三个参数**：

* 当前的 `value`
* 当前的 `key`
* 正在被遍历的 **`Map` 对象**

如果向 `forEach` 提供了 `thisArg` 参数，那么每次 `callback` 被调用时，其都会被传入以用作 `this` 的值。否则，`undefined` 将会被传入以用作 `this` 的值。最终 `callback` 可观察到的 `this` 值将会根据确定函数所观察到 `this` 的常用规则来确定。

每个值只被访问一次，除非它在 `forEach` 结束前被删除并被重新添加。对于被访问前就删除的值，`callback` 不会为其调用。在 `forEach` 结束前被新添加的值都将会被访问。

示例
--

### 输出一个 Map 对象中的内容

以下的代码在每行中打印一个 `Map` 对象中的元素：

```js
function logMapElements(value, key, map) {
  console.log(`map.get('${key}') = ${value}`);
}
new Map([
  ["foo", 3],
  ["bar", {}],
  ["baz", undefined],
]).forEach(logMapElements);
// 打印：
// "map.get('foo') = 3"
// "map.get('bar') = [object Object]"
// "map.get('baz') = undefined"
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.foreach |

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

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

参见
--

* `Array.prototype.forEach()`
* `Set.prototype.forEach()`


Map.groupBy() - JavaScript

Map.groupBy()
=============

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback

**备注：** 在某些浏览器的某些版本中，此方法被实现为 `Array.prototype.groupToMap()` 方法。由于 web 兼容性问题，它现在以静态方法实现。参见浏览器兼容性表格以获取更多信息。

**`Map.groupBy()`** 静态方法使用提供的回调函数返回的值对给定可迭代对象中的元素进行分组。最终返回的 `Map` 使用测试函数返回的唯一值作为键，可用于获取每个组中的元素组成的数组。

该方法主要用于对与对象相关的元素进行分组，特别是当该对象可能随时间而变化时。如果对象不变，你可以使用字符串表示它，并使用 `Object.groupBy()` 分组元素。

尝试一下
----

语法
--

```js
Map.groupBy(items, callbackFn)
```

### 参数

`items`

一个将进行元素分组的可迭代对象（例如 `Array`）。

`callbackFn`

对可迭代对象中的每个元素执行的函数。它应该返回一个值（对象或原始类型）来表示当前元素的分组。该函数被调用时将传入以下参数：

`element`

数组中当前正在处理的元素。

`index`

正在处理的元素在数组中的索引。

### 返回值

一个包含了每一个组的键的 `Map` 对象，每个键都分配了一个包含关联组元素的数组。

描述
--

`Map.groupBy()` 为可迭代对象中的每个元素调用一次提供的 `callbackFn` 函数。该回调函数应返回一个值，用以表示相关元素的分组。`callbackFn` 返回的值会被用作 `Map.groupBy()` 返回的 `Map` 的键。每个键都有一个相关联的数组，其中包含回调函数返回相同值的所有元素。

返回的 `Map` 中的元素和原始可迭代对象中的元素相同（不是深拷贝）。更改元素的内部结构将反映在原始可迭代对象和返回的 `Map` 中。

当你需要分组与特定对象相关的信息时，此方法非常有用。因为即使对象被修改，它仍将作为返回的 `Map` 的键继续工作。如果你改为为对象创建字符串表示形式，并在 `Object.groupBy()` 中将其用作分组键，则必须在对象改变时维护原始对象和其表示之间的映射。

**备注：** 要访问返回的 `Map` 中的分组，必须使用最初用作 `Map` 键的相同对象（尽管你可以修改其属性）。你不能使用另一个恰好具有相同名称和属性的对象。

`Map.groupBy` 不会读取 `this` 值。它可以在任何对象上调用，并返回一个新的 `Map` 实例。

示例
--

### 使用 Map.groupBy()

首先，我们定义一个包含代表各种食品库存的对象的数组。每种食品都有一个 `type` 和一个 `quantity` 属性。

```js
const inventory = [
  { name: "芦笋", type: "蔬菜", quantity: 9 },
  { name: "香蕉", type: "水果", quantity: 5 },
  { name: "山羊", type: "肉", quantity: 23 },
  { name: "樱桃", type: "水果", quantity: 12 },
  { name: "鱼", type: "肉", quantity: 22 },
];
```

下面的代码使用箭头函数（函数返回名为 `restock` 或 `sufficient` 的对象键，具体取决于元素是否满足 `quantity < 6`）来调用 `Map.groupBy()`。返回的 `result` 对象是一个 `Map`，因此我们需要使用键调用 `get()` 来获取数组。

```js
const restock = { restock: true };
const sufficient = { restock: false };
const result = Map.groupBy(inventory, ({ quantity }) =>
  quantity < 6 ? restock : sufficient,
);
console.log(result.get(restock));
// [{ name: "香蕉", type: "水果", quantity: 5 }]
```

请注意，函数参数 `{ quantity }` 是函数参数的对象解构语法的一个基本示例。这会解构作为参数传递的对象的 `quantity` 属性，并将其赋值给函数体中名为 `quantity` 的变量。这是一种非常简洁的访问函数中相关元素的值的方式。

`Map` 的键在修改后仍可以使用。但是，你不能重新创建键并仍然使用它。因此，任何需要使用映射的内容都保留对其键的引用是非常重要的。

```js
// 键被修改后仍可以使用
restock["fast"] = true;
console.log(result.get(restock));
// [{ name: "香蕉", type: "水果", quantity: 5 }]

// 不能使用新的键，即使它具有相同的结构！
const restock2 = { restock: true };
console.log(result.get(restock2)); // undefined
```

规范
--

| Specification |
| --- |
| Array Grouping # sec-map.groupby |

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

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

参见
--

* `core-js` 中 `Map.groupBy` 的 polyfill
* 索引集合类
* `Array.prototype.reduce()`
* `Map()`
* `Object.groupBy()`


Map.prototype.delete() - JavaScript

Map.prototype.delete()
======================

`Map` 实例的 **`delete()`** 方法从该 map 中删除指定键的元素。

尝试一下
----

语法
--

```js
mapInstance.delete(key)
```

### 参数

`key`

要从 `Map` 对象中删除的元素的键。

### 返回值

如果 `Map` 对象中的元素存在并已被移除，则为 `true`；如果该元素不存在，则为 `false`。

示例
--

### 使用 delete()

```js
const myMap = new Map();
myMap.set("bar", "foo");

console.log(myMap.delete("bar")); // 返回 true。成功地移除元素
console.log(myMap.has("bar")); // 返回 false。"bar" 元素将不再存在于 Map 实例中
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.delete |

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

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

参见
--

* `Map`


Map.prototype.set() - JavaScript

Map.prototype.set()
===================

`Map` 实例的 **`set()`** 方法会向 `Map` 对象添加或更新一个指定的键值对。

尝试一下
----

语法
--

```js
set(key, value)
```

### 参数

`key`

要添加到 `Map` 对象的元素的键。该值可以是任何 JavaScript 类型（任何原始值或任何类型的 JavaScript 对象）。

`value`

要添加到 `Map` 对象的元素的值。该值可以是任何 JavaScript 类型（任何原始值或任何类型的 JavaScript 对象）。

### 返回值

`Map` 对象。

示例
--

### 使用 set()

```js
const myMap = new Map();

// 将一个新元素添加到 Map 对象
myMap.set("bar", "foo");
myMap.set(1, "foobar");

// 在 Map 对象中更新某个元素的值
myMap.set("bar", "baz");
```

### 链式使用 set()

因为 `set()` 方法返回 `Map` 对象本身，所以你可以像下面这样链式调用它：

```js
// 链式添加元素
myMap.set("bar", "foo").set(1, "foobar").set(2, "baz");
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-map.prototype.set |

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

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

参见
--

* `Map`
* `Map.prototype.get()`
* `Map.prototype.has()`


Map() 构造函数 - JavaScript

Map() 构造函数
==========

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

语法
--

```js
new Map()
new Map(iterable)
```

**备注：** `Map()` 只能用 `new` 构造。尝试不使用 `new` 调用它会抛出 `TypeError`。

### 参数

`iterable` 可选

一个元素是键值对的数组或其他可迭代对象。（例如，包含两个元素的数组，如 `[[ 1, 'one' ],[ 2, 'two' ]]`。）每个键值对都被添加到新的 `Map` 中。

示例
--

### 创建一个新的 Map

```js
const myMap = new Map([
  [1, "one"],
  [2, "two"],
  [3, "three"],
]);
```

规范
--

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

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

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

参见
--

* `core-js` 中 `Map` 的 polyfill
* `Set`
* `WeakMap`
* `WeakSet`


get Map[@@species] - JavaScript

get Map[@@species]
==================

**`Map[@@species]`** 静态访问器属性是一个未使用的访问器属性，指定了如何复制 `Map` 对象。

语法
--

```js
Map[Symbol.species]
```

### 返回值

调用 `get @@species` 的构造函数的值（`this`）。返回值用于构造复制的 `Map` 实例。

描述
--

`@@species` 访问器属性返回 `Map` 对象的默认构造函数。子类构造函数可以覆盖它以更改构造函数赋值。

**备注：** 目前所有 `Map` 方法均未使用此属性。

示例
--

### 普通对象的 species

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

```js
Map[Symbol.species]; // 函数 Map()
```

### 派生对象的 species

在一个自定义的 `Map` 子类（如 `MyMap`）的实例中，`MyMap` 的 `species` 是 `MyMap` 构造函数。但是，你可能希望覆盖它，以便在派生类方法中返回父 `Map` 对象：

```js
class MyMap extends Map {
  // 用父类 Map 构造函数覆盖 MyMap 的 species
  static get [Symbol.species]() {
    return Map;
  }
}
```

规范
--

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

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

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

参见
--

* `Map`
* `Symbol.species`


Intl.PluralRules - JavaScript

Intl.PluralRules
================

**`Intl.PluralRules`** 对象是用于复数敏感的格式化和复数相关的语言规则。

构造函数
----

`Intl.PluralRules()` (en-US)

创建一个新的 `Intl.PluralRules` 对象。

静态方法
----

`Intl.PluralRules.supportedLocalesOf()` (en-US)

返回一个数组，其中包含提供的区域（locale）中被运行时所支持的，而不必回退到运行时的默认区域。

实例方法
----

`Intl.PluralRules.prototype.resolvedOptions()` (en-US)

返回一个新的对象，其属性反映了在对象初始化期间计算所得的区域和一系列选项。

`Intl.PluralRules.prototype.select()` (en-US)

返回一个字符串，指示用于区域敏感的格式化的复数类别。

`Intl.PluralRules.prototype.selectRange()` (en-US)

此方法接收两个值并返回一个字符串，指示用于区域敏感的格式化的复数类别。

示例
--

### 使用 locales

此示例显示本地化复数类别的一些值。为了获得应用程序用户界面中使用的语言格式，请确保使用 `locales` 参数指定了语言（可能还有一些回退语言）：

```js
// 阿拉伯语有不同的复数类别

new Intl.PluralRules("ar-EG").select(0);
// → 'zero'
new Intl.PluralRules("ar-EG").select(1);
// → 'one'
new Intl.PluralRules("ar-EG").select(2);
// → 'two'
new Intl.PluralRules("ar-EG").select(6);
// → 'few'
new Intl.PluralRules("ar-EG").select(18);
// → 'many'
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # pluralrules-objects |

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

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

参见
--

* `Intl`
* FormatJS 中 `Intl.PluralRules` 的 polyfill


Intl.Collator - JavaScript

Intl.Collator
=============

**`Intl.Collator`** 对象用于语言敏感的字符串比较。

尝试一下
----

构造函数
----

`Intl.Collator()`

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

静态方法
----

`Intl.Collator.supportedLocalesOf()` (en-US)

返回一个数字，其中包含提供的区域（locale）中被运行时所支持的，而不必回退到运行时的默认区域。

实例方法
----

`Intl.Collator.prototype.compare` (en-US)

getter 函数，根据 `Intl.Collator` 对象的排序顺序来比较两个字符串。

`Intl.Collator.prototype.resolvedOptions()` (en-US)

返回一个新对象，其属性反映了在对象初始化期间计算所得的区域和一系列选项。

示例
--

### 使用 Collator

以下示例演示了一个字符串在另一个字符串之前、之后或与另一个字符串处于同一级别时可能出现的不同结果：

```js
console.log(new Intl.Collator().compare("a", "c")); // -1，或一些其他的负值
console.log(new Intl.Collator().compare("c", "a")); // 1，或一些其他的正值
console.log(new Intl.Collator().compare("a", "a")); // 0
```

请注意，上面代码中显示的结果可能因浏览器和浏览器版本而异。这是因为这些值是特定于实现的。即，规范仅要求在比较的字符串之前和之后分别对应负值和正值。

### 使用 locales

`Collator.prototype.compare()` (en-US) 提供的结果在不同语言之间有所不同。为了获得用于你的应用程序的用户界面的语言格式，请确保使用 `locales` 参数指定了语言（可能还有一些回退语言）：

```js
// 德语中，ä 使用 a 的排序
console.log(new Intl.Collator("de").compare("ä", "z"));
// -1，或一些其他的负值

// 在瑞典语中，ä 排在 z 之后
console.log(new Intl.Collator("sv").compare("ä", "z"));
// 1，或一些其他的正值
```

### 使用 options

`Collator.prototype.compare()` (en-US) 提供的结果可以使用 options 参数自定义：

```js
// 德语中，ä 使用 a 作为基本字母
console.log(new Intl.Collator("de", { sensitivity: "base" }).compare("ä", "a"));
// 0

// 瑞典语中，ä 和 a 是单独的基本字母
console.log(new Intl.Collator("sv", { sensitivity: "base" }).compare("ä", "a"));
// 1，或一些其他的正值
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # collator-objects |

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

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

参见
--

* `Intl`


Intl.Locale - JavaScript

Intl.Locale
===========

**`Intl.Locale`** 对象是 Intl 对象的标准内置属性，用于表示 Unicode 区域标识。

尝试一下
----

描述
--

**`Intl.Locale`** 对象是为了更便捷地处理 Unicode 区域设置。Unicode 使用字符串作为区域识别标识。区域标识符由*语言标识符*和*扩展标记*组成。语言标识符是区域 (locale) 的核心，包含了语言、脚本和地域子标记 (region subtags)。有关区域设置的其他信息体现在可选的扩展标记中。扩展标记保存有关区域设置方面的信息，例如日历类型、时钟类型和编号系统类型。

传统上，Intl 接口像 Unicode 一样使用字符串来表示区域设置，这是一个简单而轻量且效果好的解决方案。但是，添加一个 Locale 类可以更容易地解析和操作语言、脚本、区域以及扩展标记。

构造函数
----

`Intl.Locale()` (en-US)

实例化一个 `Locale` 对象。

实例属性
----

`Intl.Locale.prototype.baseName` (en-US)

Returns basic, core information about the `Locale` in the form of a substring of the complete data string.

`Intl.Locale.prototype.calendar` (en-US)

Returns the part of the `Locale` that indicates the Locale's calendar era.

`Intl.Locale.prototype.caseFirst` (en-US)

Returns whether case is taken into account for the locale's collation rules.

`Intl.Locale.prototype.collation` (en-US)

Returns the collation type for the `Locale`, which is used to order strings according to the locale's rules.

`Intl.Locale.prototype.hourCycle` (en-US)

Returns the time keeping format convention used by the locale.

`Intl.Locale.prototype.language` (en-US)

Returns the language associated with the locale.

`Intl.Locale.prototype.numberingSystem` (en-US)

Returns the numeral system used by the locale.

`Intl.Locale.prototype.numeric` (en-US)

Returns whether the locale has special collation handling for numeric characters.

`Intl.Locale.prototype.region` (en-US)

Returns the region of the world (usually a country) associated with the locale.

`Intl.Locale.prototype.script` (en-US)

Returns the script used for writing the particular language used in the locale.

实例方法
----

`Intl.Locale.prototype.maximize()` (en-US)

Gets the most likely values for the language, script, and region of the locale based on existing values.

`Intl.Locale.prototype.minimize()` (en-US)

Gets the most likely values for the language, script, and region of the locale based on existing values.

`Intl.Locale.prototype.toString()` (en-US)

Returns the Locale's full locale identifier string.

范例
--

### 基本使用

很简单，就是需要给`Intl.Locale` (en-US) 构造函数传入一个 locale 标识字符串作为参数：

```js
let us = new Intl.Locale("zh-Hans-CN");
```

### 使用配置实例化

构造函数支持传入 object 作为配置，object 中可包含多个配置属性。例如，设置 `hourCycle` (en-US) 属性，用于设置你所需要的小时周期类型：

```js
let zh12hour = new Intl.Locale("zh-Hans-CN", { hourCycle: "h12" });
console.log(zh12hour.hourCycle); // Prints "h12"
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # locale-objects |

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

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

参阅
--

* The Intl.Locale Polyfill


Intl.NumberFormat - JavaScript

Intl.NumberFormat
=================

**`Intl.NumberFormat`** 对象能使数字在特定的语言环境下格式化。

尝试一下
----

构造函数
----

`Intl.NumberFormat()` (en-US)

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

静态方法
----

`Intl.NumberFormat.supportedLocalesOf()` (en-US)

返回一个数组，其包含着那些被提供的受支持的区域（locale），而运行时的默认的区域不会出现在该数组。

实例方法
----

`Intl.NumberFormat.prototype.format()`

getter 函数，根据此 `Intl.NumberFormat` 对象的区域设置和格式化选项格式化数字。

`Intl.NumberFormat.prototype.formatToParts()` (en-US)

返回一个对象数组，其中表示的是数字字符串的各个部分，可以用于自定义本地化格式。

`Intl.NumberFormat.prototype.formatRange()` (en-US)

getter 函数，根据调用该方法的 `Intl.NumberFormat` 对象的区域设置和格式化选项格式化一个数字的范围。

`Intl.NumberFormat.prototype.formatRangeToParts()` (en-US)

返回一个对象数组，其中表示的是数字范围的字符串的各个部分，可以用于自定义本地化格式。

`Intl.NumberFormat.prototype.resolvedOptions()` (en-US)

返回一个新对象，其属性能够反映相应对象在初始化时计算所得的区域和格式化选项。

示例
--

### 基础用例

在不指定区域设置的基本用例中，返回默认区域和默认选项中的格式化字符串。

```js
const number = 3500;

console.log(new Intl.NumberFormat().format(number));
// 如果在美式英语区域 → '3,500'
```

### 使用 locales

此示例展示了本地数字格式化的一些变化。为了得到用户应用接口使用的语言格式，请确保使用 `locales` 参数指定该语言（可能还有一些备选语言）：

```js
const number = 123456.789;

// 德语使用逗号（,）作为小数点，使用句号（.）作为千位分隔符
console.log(new Intl.NumberFormat("de-DE").format(number));
// → 123.456,789

// 大多数阿拉伯语国家使用阿拉伯语数字
console.log(new Intl.NumberFormat("ar-EG").format(number));
// → ١٢٣٤٥٦٫٧٨٩

// India uses thousands/lakh/crore separators
console.log(new Intl.NumberFormat("en-IN").format(number));
// → 1,23,456.789

// 通过编号系统中的 nu 扩展键请求，例如：中文十进制数字
console.log(new Intl.NumberFormat("zh-Hans-CN-u-nu-hanidec").format(number));
// → 一二三,四五六.七八九

//当请求的语言不被支持，例如巴里，包含一个回滚语言印尼，这时候就会使用印尼语
console.log(new Intl.NumberFormat(["ban", "id"]).format(number));
// → 123.456,789
```

### 使用 options

可以使用 `options` (en-US) 参数自定义结果：

```js
const number = 123456.789;

// 要求货币格式
console.log(
  new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(
    number,
  ),
);
// 123.456,79 €

// 日元不使用小数位
console.log(
  new Intl.NumberFormat("ja-JP", { style: "currency", currency: "JPY" }).format(
    number,
  ),
);
// ￥123,457

// 限制三位有效数字
console.log(
  new Intl.NumberFormat("en-IN", { maximumSignificantDigits: 3 }).format(
    number,
  ),
);
// 1,23,000

// 带有单位的格式化
console.log(
  new Intl.NumberFormat("pt-PT", {
    style: "unit",
    unit: "kilometer-per-hour",
  }).format(50),
);
// 50 km/h

console.log(
  (16).toLocaleString("en-GB", {
    style: "unit",
    unit: "liter",
    unitDisplay: "long",
  }),
);
// 16 litres
```

有关详尽的选项列表，参见 `Intl.NumberFormat()` 构造函数 (en-US)页面。

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # numberformat-objects |

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

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

参见
--

* `Intl`
* FormatJS 中 `Intl.NumberFormat` 的 polyfill


Intl.Segmenter - JavaScript

Intl.Segmenter
==============

**`Intl.Segmenter`** 对象支持语言敏感的文本分割，允许你将一个字符串分割成有意义的片段（字、词、句）。

尝试一下
----

构造函数
----

`Intl.Segmenter()`

创建一个新的 `Intl.Segmenter` 对象。

静态方法
----

`Intl.Segmenter.supportedLocalesOf()` (en-US)

返回一个数组，其中包括了传入参数中的受支持的语言，而不必受限于运行时的默认语言环境。

实例方法
----

`Intl.Segmenter.prototype.resolvedOptions()` (en-US)

返回一个新的对象，对象的属性反映了这个 `Intl.Segmenter` 实例初始化期间计算的语言环境和粒度选项。

`Intl.Segmenter.prototype.segment()` (en-US)

返回一个新的 `Segments` (en-US) 实例，它是一个可迭代对象，包含了根据当前 `Intl.Segmenter` 实例的语言环境和粒度选项生成的字符串片段。

示例
--

### 基础用法及与 String.prototype.split() 的区别

如果我们使用 `String.prototype.split(" ")` 来将一段文本分割成词汇，如果这段文本的语言并不是使用空格来分割词汇的话，那我们就不能保证得到的是正确的结果（例如日语、中文、泰语、老挝语、高棉语、缅甸语等语言）。

```js
const str = "吾輩は猫である。名前はたぬき。";
console.table(str.split(" "));
// ['吾輩は猫である。名前はたぬき。']
// 这两个句子并没有得到正确的分割。
```

```js
const str = "吾輩は猫である。名前はたぬき。";
const segmenterJa = new Intl.Segmenter("ja-JP", { granularity: "word" });

const segments = segmenterJa.segment(str);
console.table(Array.from(segments));
// [{segment: '吾輩', index: 0, input: '吾輩は猫である。名前はたぬき。', isWordLike: true},
// etc.
// ]
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # segmenter-objects |

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

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


Intl.RelativeTimeFormat - JavaScript

Intl.RelativeTimeFormat
=======================

**`Intl.RelativeTimeFormat`** 对象用于语言敏感的相对时间的格式化。

尝试一下
----

构造函数
----

`Intl.RelativeTimeFormat()` (en-US)

创建一个新的 `Intl.RelativeTimeFormat` 对象。

静态方法
----

`Intl.RelativeTimeFormat.supportedLocalesOf()` (en-US)

返回一个数组，其中包含提供的区域（locale）中被运行时所支持的，而不必回退到运行时的默认区域。

实例方法
----

`Intl.RelativeTimeFormat.prototype.format()` (en-US)

根据给定的 `Intl.RelativeTimeFormat` 对象的区域和格式化选项来格式化值（`value`）和单位（`unit`）。

`Intl.RelativeTimeFormat.prototype.formatToParts()` (en-US)

返回一个对象数组，其中的对象表示的是相对事件格式字符串中的各个部分，可用于自定义本地化格式。

`Intl.RelativeTimeFormat.prototype.resolvedOptions()` (en-US)

返回一个新的对象，其属性反映了在对象初始化期间计算所得的区域和一系列选项。

示例
--

### 基本 format 用法

以下示例显示如何为英语创建相对时间格式化程序。

```js
// 在你的区域下创建相对时间格式化程序
// 显式传入默认值。
const rtf = new Intl.RelativeTimeFormat("en", {
  localeMatcher: "bestfit", // 其他值："lookup"
  numeric: "always", // 其他值："auto"
  style: "long", // 其他值："short"或"narrow"
});

// 使用负值（-1）格式化相对时间。
rtf.format(-1, "day"); // "1 day ago"

// 使用正值（1）格式化相对时间。
rtf.format(1, "day"); // "in 1 day"
```

### 使用 formatToParts

以下示例展示了如何创建一个用于返回格式化后的每一个部分的相对时间格式化程序。

```js
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

// 使用日期单位格式化相对时间。
rtf.formatToParts(-1, "day");
// [{type: "literal", value: "yesterday"}]

rtf.formatToParts(100, "day");
// [
// { type: "literal", value: "in " },
// { type: "integer", value: "100", unit: "day" },
// { type: "literal", value: " days" }
// ]
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # relativetimeformat-objects |

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

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

参见
--

* `Intl`
* Intl.RelativeTimeFormat API
* FormatJS 中 `Intl.RelativeTimeFormat` 的 polyfill


Intl.getCanonicalLocales() - JavaScript

Intl.getCanonicalLocales()
==========================

**`Intl.getCanonicalLocales()`** 方法返回一个数组，数组包含规范的区域语言代码，重复的元素将会被去除，每一个元素都会被验证为格式有效的区域语言代码。

尝试一下
----

语法
--

```js
Intl.getCanonicalLocales(locales)
```

### 参数

`locales`

想要规范化的字符串数组。

### 返回值

一个包含规范区域语言代码的数组。

示例
--

```js
Intl.getCanonicalLocales("EN-US"); // ["en-US"]
Intl.getCanonicalLocales(["EN-US", "Fr"]); // ["en-US", "fr"]

Intl.getCanonicalLocales("EN\_US");
// RangeError:'EN\_US' is not a structurally valid language tag
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.getcanonicallocales |

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

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

参见
--

* `Intl.NumberFormat.supportedLocalesOf()` (en-US)
* `Intl.DateTimeFormat.supportedLocalesOf()` (en-US)
* `Intl.Collator.supportedLocalesOf()` (en-US)


Intl.DisplayNames - JavaScript

Intl.DisplayNames
=================

 **`Intl.DisplayNames`** 是一个对象构造器，它支持语言、区域和脚本显示名称的一致翻译。语法
--
```

new Intl.DisplayNames([locales[, options]])
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # intl-displaynames-objects |


Intl.DateTimeFormat - JavaScript

Intl.DateTimeFormat
===================

**`Intl.DateTimeFormat`** 对象能使日期和时间在特定的语言环境下格式化。

尝试一下
----

构造函数
----

`Intl.DateTimeFormat()` (en-US)

创建一个新的 `Intl.DateTimeFormat` 对象。

静态方法
----

`Intl.DateTimeFormat.supportedLocalesOf()` (en-US)

返回一个数组，其中包含所提供的区域（locale）中被运行时所支持的，而不必回退到运行时默认的区域。

实例方法
----

`Intl.DateTimeFormat.prototype.format()` (en-US)

getter 函数，根据此 `DateTimeFormat` 对象的区域设置和格式化选项格式化日期。

`Intl.DateTimeFormat.prototype.formatToParts()` (en-US)

返回一个对象数组，代表日期字符串的各个部分，可用于自定义本地化格式。

`Intl.DateTimeFormat.prototype.resolvedOptions()` (en-US)

返回一个新对象，其属性能够反映相应对象在初始化时计算所得的区域和格式化选项。

`Intl.DateTimeFormat.prototype.formatRange()` (en-US)

此方法接收两个 Date 对象，并根据实例化 `DateTimeFormat` 时提供的区域和选项，以最简洁的方式格式化日期范围。

`Intl.DateTimeFormat.prototype.formatRangeToParts()` (en-US)

此方法接收两个 Date 对象，并返回一个对象数组，该数组包含代表被格式化日期范围的每一部分特定于地区的词语元素对象。

示例
--

### 使用 DateTimeFormat

不指定 locale 时，`DateTimeFormat` 使用默认的 locale 和 默认的 options。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 没有参数的 toLocaleString 返回取决于实现、默认的区域和默认的时区
console.log(new Intl.DateTimeFormat().format(date));
// 如果是在美式英语环境（语言）和洛杉矶时区（UTC-0800）下运行，那么会输出 "12/19/2012"
```

### 使用 locale

这个例子显示了本地化日期和时间格式的一些变化。为了获得用于你的应用程序的用户界面的语言格式，请确保使用 `locales` 参数指定了语言（可能还有一些回退语言）：

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 假定下面输出的结果使用了洛杉矶时区（UTC-0800，太平洋标准时间）

// 美式英语 (US English) 使用 month-day-year 格式
console.log(new Intl.DateTimeFormat("en-US").format(date));
// "12/19/2012"

// 英式英语 (British English) 使用 day-month-year 格式
console.log(new Intl.DateTimeFormat("en-GB").format(date));
// "19/12/2012"

// 韩国使用 year-month-day 格式
console.log(new Intl.DateTimeFormat("ko-KR").format(date));
// "2012. 12. 19."

// 大部分阿拉伯国家使用阿拉伯字母 (real Arabic digits)
console.log(new Intl.DateTimeFormat("ar-EG").format(date));
// "١٩/١٢/٢٠١٢"

// 在日本，应用可能想要使用日本日历，
// 2012 年是平成 24 年（平成是是日本天皇明仁的年号，由 1989 年 1 月 8 日起开始计算直至现在）
console.log(new Intl.DateTimeFormat("ja-JP-u-ca-japanese").format(date));
// "24/12/19"

// 当请求可能不支持的语言，如巴厘语（ban）时，若同时指定了备用的语言，
// 那么将使用备用的语言输出（本例为印尼语（id））
console.log(new Intl.DateTimeFormat(["ban", "id"]).format(date));
// "19/12/2012"
```

### 使用 options

可以使用 `options` 参数来自定义日期时间格式化方法返回的字符串。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 请求参数 (options) 中包含参数星期 (weekday)，并且该参数的值为长类型 (long)
let options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
console.log(new Intl.DateTimeFormat("de-DE", options).format(date));
// "Donnerstag, 20. Dezember 2012"

// 应用可能需要使用世界标准时间 (UTC)，并且 UTC 使用短名字 (short) 展示
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// "Thursday, December 20, 2012, GMT"

// 有时需要更精确的选项
options = {
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  timeZone: "Australia/Sydney",
  timeZoneName: "short",
};
console.log(new Intl.DateTimeFormat("en-AU", options).format(date));
// "2:00:00 pm AEDT"

// 再精确些...
options.fractionalSecondDigits = 3; // 秒数的有效数字数量
console.log(new Intl.DateTimeFormat("en-AU", options).format(date));
// "2:00:00.200 pm AEDT"

// 即便是美国，有时也需要使用 24 小时制
options = {
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  hour12: false,
  timeZone: "America/Los\_Angeles",
};
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// "12/19/2012, 19:00:00"

// 要使用选项，但是需要使用浏览器的默认区域，请使用 'default'
console.log(new Intl.DateTimeFormat("default", options).format(date));
// "12/19/2012, 19:00:00"
// 有时需要包含一天的时段
options = { hour: "numeric", dayPeriod: "short" };
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// 10 at night
```

使用的日历和数字格式也可以通过 `options` 参数分别设置：

```js
const options = { calendar: "chinese", numberingSystem: "arab" };
const dateFormat = new Intl.DateTimeFormat("default", options);
const usedOptions = dateFormat.resolvedOptions();
console.log(usedOptions.calendar);
// "chinese"
console.log(usedOptions.numberingSystem);
// "arab"
console.log(usedOptions.timeZone);
// "America/New\_York"（用户的默认时区）
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # datetimeformat-objects |

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

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

参见
--

* `Intl`
* FormatJS 上的 `Intl.DateTimeFormat` polyfill


Intl.ListFormat - JavaScript

Intl.ListFormat
===============

**`Intl.ListFormat`** 是一个语言相关的列表格式化构造器。

尝试一下
----

语法
--
```

new Intl.ListFormat([locales[, options]])
```

### 参数

`locales`

可选的.。符合 BCP 47 语言标注的字符串或字符串数组。`locales` 参数的一般形式和相关解释，请参阅 Intl page.

`options`

可选的。拥有下面所列属性中任意几个或全部的对象：

* `localeMatcher`
 指定要使用的本地匹配算法。可选的值有`"lookup"` 和 `"best fit"`；默认情况下使用`"best fit"`。该参数的更多信息，请参考`Intl` page.
* `type`
 消息输出的格式。可选的值有用于替代基于“且”关系列表的`"conjunction"` (默认值，例如： `A, B, and C`)，或者用于替代基于“或”关系列表的 `"disjunction"`(例如： `A, B, or C`)，以及用于替代带计量单位的值列表的`"unit"` (例如： `5 pounds, 12 ounces`).
* `style`
 被格式化消息的长度。可选值有：`"long"` (默认值，例如：`A, B, and C`)、`"short"` 或者 `"narrow"` (例如：`A, B, C`)。当`style` 的值为`narrow` 时，type 属性的值只能取值`unit`。

描述
--

### 属性

`Intl.ListFormat.prototype` (en-US)

允许增加一个属性到列表中的所有对象。

### 方法

`Intl.ListFormat.supportedLocalesOf()` (en-US)

返回一个包含指定的被支持区域设置的数组，没有时使用运行环境默认区域设置

示例
--

### 使用 `format`

下面的例子展示了用英语语言怎么去创建一个列表格式化器。

```js
const list = ["Motorcycle", "Bus", "Car"];

console.log(
  new Intl.ListFormat("en-GB", { style: "long", type: "conjunction" }).format(
    list,
  ),
);
// > Motorcycle, Bus and Car

console.log(
  new Intl.ListFormat("en-GB", { style: "short", type: "disjunction" }).format(
    list,
  ),
);
// > Motorcycle, Bus or Car

console.log(
  new Intl.ListFormat("en-GB", { style: "narrow", type: "unit" }).format(list),
);
// > Motorcycle Bus Car
```

### 使用 `formatToParts`

下面的例子展示了如何创建一个返回被格式化部分的列表格式化器。

```js
const list = ["Motorcycle", "Bus", "Car"];
console.log(
  new Intl.ListFormat("en-GB", {
    style: "long",
    type: "conjunction",
  }).formatToParts(list),
);

// > [ { "type": "element", "value": "Motorcycle" }, { "type": "literal", "value": ", " }, { "type": "element", "value": "Bus" }, { "type": "literal", "value": ", and " }, { "type": "element", "value": "Car" } ];
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # listformat-objects |

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

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

参见
--

* `Intl`
* A polyfill of `Intl.ListFormat` in FormatJS


Intl.NumberFormat.prototype.format - JavaScript

Intl.NumberFormat.prototype.format
==================================

**`Intl.NumberFormat.prototype.format`** 属性返回一个根据`NumberFormat`对象的语言环境和格式化选项，来格式化一个数字的 getter 函数。

尝试一下
----

语法
--
```

numberFormat.format(number)
```

### 参数

`number`

要格式化的数值。

描述
--

该函数返回一个根据`NumberFormat`对象的语言环境和格式化选项，来`format` 一个数字的函数。

示例
--

### 使用 `format`

使用 `format` 格式化一个单一的货币值，以俄罗斯为例：

```js
var options = { style: "currency", currency: "RUB" };
var numberFormat = new Intl.NumberFormat("ru-RU", options);
console.log(numberFormat.format(654321.987));
// → "654 321,99 руб."
```

### 使用 `format` 和 `map`

使用 `format` 返回的函数来格式化数组中的所有数字。注意，该函数绑定到所获得的`NumberFormat`，因此它可以直接传递给`Array.prototype.map`。

```js
var a = [123456.789, 987654.321, 456789.123];
var numberFormat = new Intl.NumberFormat("es-ES");
var formatted = a.map(numberFormat.format);
console.log(formatted.join("; "));
// → "123.456,789; 987.654,321; 456.789,123"
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.numberformat.prototype.format |

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

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

参见
--

* `Intl.NumberFormat`
* `Number.prototype.toLocaleString()`


Intl.Segmenter() - JavaScript

Intl.Segmenter()
================

**`Intl.Segmenter()`** 构造函数会创建一个 `Intl.Segmenter` 对象，该对象支持语言敏感的文本分割。

尝试一下
----

语法
--

```js
new Intl.Segmenter()
new Intl.Segmenter(locales)
new Intl.Segmenter(locales, options)
```

**备注：** `Intl.Segmenter()` 只能通过 `new` 操作符来构建。如果尝试不使用 `new` 操作符来构建，将会抛出一个 `TypeError` 错误。

### 参数

`locales` 可选

带有 BCP 47 语言区域标记的一个字符串，或者一个这样的字符串数组。对于 `locales` 参数的一般形式和解释，参见语言区域识别和判定。

`options` 可选

带有部分或全部以下属性的一个对象：

`granularity` 可选

字符串。可选值如下：

`"grapheme"`（默认）

根据语言区域，将输入值按字（用户可以感知的字符）划分边界。

`"word"`

根据语言区域，将输入值按词划分边界。

`"sentence"`

根据语言区域，将输入值按句划分边界。

`localeMatcher` 可选

将要使用的语言区域匹配算法。可选值如下：

`"best fit"`（默认）

运行时可能会选择一个可能比查找算法的结果更加合适的语言区域。

`"lookup"`

使用 BCP 47 查找算法来从 `locales` 参数中选择语言区域。对于 `locales` 参数中的每一个语言区域，会返回第一个运行时支持的语言区域（有可能会移除用于限制区域的子标记，来找到一个支持的语言区域。换句话说，如果运行时支持 `"de"` 但不支持 `"de-CH"`，用户传入的 `"de-CH"` 可能就会以 `"de"` 为结果进行使用）。

### 返回值

一个新的 `Intl.Segmenter` 实例。

示例
--

### 基础用法

下面的例子展示了如何计算在一个日语字符串中使用了多少个词汇（使用 `String` 提供的分割方法将得到错误的结果）。

```js
const text = "吾輩は猫である。名前はたぬき。";
const japaneseSegmenter = new Intl.Segmenter("ja-JP", { granularity: "word" });
console.log(
  [...japaneseSegmenter.segment(text)].filter((segment) => segment.isWordLike)
    .length,
);
// 8，文本将会分割为 '吾輩'|'は'|'猫'|'で'|'ある'|'。'|'名前'|'は'|'たぬき'|'。'
```

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl-segmenter-constructor |

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

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


Intl.Collator() constructor - JavaScript

Intl.Collator() constructor
===========================

**`Intl.Collator()`** 构造函数用于创建
 `Intl.Collator` 对象，此类对象用于语言敏感的字符串比较。

尝试一下
----

语法
--

```js
new Intl.Collator()
new Intl.Collator(locales)
new Intl.Collator(locales, options)

Intl.Collator()
Intl.Collator(locales)
Intl.Collator(locales, options)
```

**备注：** `Intl.Collator()` 可以在使用或不适用 `new` 的情况下调用。两者均能创建一个新的 `Intl.Collator` 实例。

### 参数

`locales` 可选

缩写语言代码（BCP 47 language tag）的字符串，或由此类字符串组成的数组。关于参数 `locales` 的一般形式和解释请参见语言区域识别和判定。

下面的这些 Unicode 扩展键也是被允许的：

**备注：** 这些键通常也可用于 `options` 的设置（如下所列）。当两者同时设置时，`options` 属性的优先级更高。

`co`

某些区域设置的变体归类。可能的值包括：

* `big5han`（汉语；在 Chrome 和 Edge 中不可用）
* `compat`（阿拉伯语）
* `dict`（僧伽罗语）
* `direct`（已弃用，请勿使用）
* `ducet`（已弃用，请勿使用）
* `emoji`（root）
* `eor`（root）
* `gb2312`（汉语；在 Chrome 和 Edge 中不可用）
* `phonebk`（德语）
* `phonetic`（林加拉语）
* `pinyin`（汉语）
* `reformed`（瑞典语；不需要明确指定，因为这是瑞典语的默认设置）
* `searchjl`（韩语；请勿用于排序）
* `stroke`（汉语）
* `trad`
* `unihan`（汉语、日语和韩语；在 Chrome 和 Edge 中不可用）
* `zhuyin`（汉语）

该选项也可通过 `options` 的 `collation` 属性设置。

`kn`

是否应使用数字对照，使得“1”<“2”<“10”。可能的值为 `"true"` 和 `"false"`。该选项也可通过 `options` 的 `numeric` 属性设置。

`kf`

是否应该首先根据大小写排序。可能的值为 `"upper"`、`"lower"` 和 `"false"`（使用区域的默认设置）。该选项也可通过 `options` 的 `caseFirst` 属性设置。

`options` 可选

包含一些或所有的以下属性的对象：

`localeMatcher`

 使用的区域匹配算法。可能的值为：`"lookup"` 和 `"best fit"`；默认值为 `"best fit"`。参见
 Intl 页面以了解此选项的详细信息。

`usage`

比较是用于排序还是用于搜索匹配的字符串。可能的值为 `"sort"` 和 `"search"`；默认值为 `"sort"`。

`sensitivity`

字符串中的哪些差异应导致结果值为非零。可能的值为：

* `"base"`：只有字母不同的字符串比较不相等。例如：a ≠ b、a = á、a = A。
* `"accent"`：只有不同的基本字母或重音符号和其他变音符号的字符串比较为不相等。例如：a
 ≠ b、a ≠ á、a = A。
* `"case"`：只有不同的基本字母或大小写的字符串比较不相等。例如：a ≠ b、a = á、a ≠ A。
* `"variant"`：字符串的字母、重音和其他变音符号，或不同大小写比较不相等。也可以考虑其他差异。例如：a ≠ b、a ≠ á、a ≠ A。

`"sort"` 用法（`usage`）的默认值为 `"variant"`。`"search"` 用法则取决于区域。

`ignorePunctuation`

是否应忽略标点。可能的值为 `true` 和 `false`；默认值为 `false`。

`numeric`

是否应使用数字对照，使得“1”<“2”<“10”。可能的值为 `true` 和 `false`；默认值为 `false`。此选项也可以通过 Unicode 扩展键 `kn` 设置；当两者同时设置时，`options` 属性的优先级更高。

`caseFirst`

是否应该首先根据大小写排序。可能的值为 `"upper"`、`"lower"` 和 `"false"`（使用区域的默认设置）。此选项也可以通过 Unicode 扩展键 `kf` 设置；当两者同时设置时，`options` 属性的优先级更高。

`collation`

一些区域的变体。可能的值包括：

* `big5han`（汉语；在 Chrome 和 Edge 中不可用）
* `compat`（阿拉伯语）
* `dict`（僧伽罗语）
* `direct`（已弃用，请勿使用）
* `ducet`（不可用，请勿使用）
* `emoji`（root）
* `eor`（root）
* `gb2312`（汉语；在 Chrome 和 Edge 中不可用）
* `phonebk`（德语）
* `phonetic`（林加拉语）
* `pinyin`（汉语）
* `reformed`（瑞典语；不需要明确指定，因为这是瑞典语的默认设置）
* `searchjl`（韩语；请勿用于排序）
* `stroke`（汉语）
* `trad`
* `unihan`（汉语、日语和韩语；在 Chrome 和 Edge 中不可用）
* `zhuyin`（汉语）

此选项也可以通过 Unicode 扩展键 `co` 设置；当两者同时设置时，`options` 属性的优先级更高。

示例
--

### 使用 Collator

以下示例演示了一个字符串在另一个字符串之前、之后或与另一个字符串处于同一级别时可能出现的不同结果：

```js
console.log(new Intl.Collator().compare("a", "c")); // -1，或一些其他的负值
console.log(new Intl.Collator().compare("c", "a")); // 1，或一些其他的正值
console.log(new Intl.Collator().compare("a", "a")); // 0
```

请注意，上面代码中显示的结果可能因浏览器和浏览器版本而异。这是因为这些值是特定于实现的。即，规范仅要求在比较的字符串之前和之后分别对应负值和正值。

规范
--

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-the-intl-collator-constructor |

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

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

参见
--

* `Intl.Collator`
* `Intl`


WeakRef.prototype.deref() - JavaScript

WeakRef.prototype.deref()
=========================

`deref`方法返回`WeakRef` 实例的目标对象，如果目标对象已被垃圾收集，则返回`undefined` 。语法
--
```

obj = ref.deref();
```

### 返回值

返回 WeakRef 的目标对象，如果该对象已被垃圾收集，则返回`undefined` 。

说明
--

有关一些重要说明，请参阅`WeakRef`页面上的Notes on WeakRefs 。

示例
--

### 使用 deref

有关完整示例，请参阅`WeakRef`页面的示例部分。

```js
const tick = () => {
  // Get the element from the weak reference, if it still exists
  const element = this.ref.deref();
  if (element) {
    element.textContent = ++this.count;
  } else {
    // The element doesn't exist anymore
    console.log("The element is gone.");
    this.stop();
    this.ref = null;
  }
};
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-weak-ref.prototype.deref |

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

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

参见
--

* `WeakRef`


WeakRef() 构造函数 - JavaScript

WeakRef() 构造函数
==============

**`WeakRef()`** 会创建一个 `WeakRef` 对象，它是对于目标对象的弱引用。

语法
--

```js
new WeakRef(targetObject)
```

**备注：** `WeakRef()` 必须通过 `new` 关键字调用。试图在没有 `new` 的情况下调用会抛出一个 `TypeError`。

### 参数

`targetObject`

WeakRef 要指向的目标对象 (也称作 *referent*）。

示例
--

### 创建一个新的 WeakRef 对象

完整的示例请见 `WeakRef` 主页面。

```js
class Counter {
  constructor(element) {
    // 创建一个对 DOM 元素的弱引用
    this.ref = new WeakRef(element);
    this.start();
  }
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-weak-ref-constructor |

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

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

参见
--

* `WeakRef`


Date.prototype.setUTCMilliseconds() - JavaScript

Date.prototype.setUTCMilliseconds()
===================================

**`setUTCMilliseconds()`** 方法会根据世界时来设置指定时间的毫秒数。

尝试一下
----

语法
--
```

dateObj.setUTCMilliseconds(millisecondsValue)
```

### 参数

`millisecondsValue`

0 - 999 之间的数值，代表毫秒数。

### 返回值

返回更新后的时间距 1970 年 1 月 1 日 00:00:00 (UTC) 的毫秒数。

描述
--

如果传递的参数超出了指定的范围，`setUTCMilliseconds()` 方法会相应地尝试更新储存在 `Date` 的时间信息。例如，假设你传递参数的值是 1100，存储在 `Date` 的秒数会加 1，然后使用 100 来作为毫秒数。

示例
--

### 使用 `setUTCMilliseconds() 方法`

```js
var theBigDay = new Date();
theBigDay.setUTCMilliseconds(500);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcmilliseconds |

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

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

参见
--

* `Date.prototype.getUTCMilliseconds()`
* `Date.prototype.setMilliseconds()`


Date.prototype.setTime() - JavaScript

Date.prototype.setTime()
========================

**`setTime()`** 方法以一个表示从 1970-1-1 00:00:00 UTC 计时的毫秒数为来为 `Date` 对象设置时间。

尝试一下
----

语法
--
```

dateObj.setTime(timeValue)
```

### 参数

`timeValue`

一个整数，表示从 1970-1-1 00:00:00 UTC 开始计时的毫秒数。

### 返回值

UTC 1970 年 1 月 1 日 00:00:00 与更新日期之间的毫秒数（实际上是自变量的值）。

描述
--

使用 `setTime` 方法用来把一个日期时间赋值给另一个 `Date` 对象。

示例
--

### 示例：使用`setTime`
```

theBigDay = new Date("July 1, 1999");
sameAsBigDay = new Date();
sameAsBigDay.setTime(theBigDay.getTime());
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.settime |

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

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

参见
--

* `Date.prototype.getTime()`
* `Date.prototype.setUTCHours()`


Date.prototype.getMinutes() - JavaScript

Date.prototype.getMinutes()
===========================

**`getMinutes()`** 方法根据本地时间，返回一个指定的日期对象的分钟数。

尝试一下
----

语法
--

```js
getMinutes()
```

### 参数

无

### 描述

`getMinutes` 返回一个 0 到 59 的整数值。

示例
--

### 示例：使用`getMinutes` 方法

下例中，第二行语句运行过后，变量 `minutes` 的值为 15，也就是说 `Xmas95` 这个日期对象的值为某时 15 分某秒。

```js
var Xmas95 = new Date("December 25, 1995 23:15:00");
var minutes = Xmas95.getMinutes();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getminutes |

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

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

参见
--

* `Date.prototype.getUTCMinutes()`
* `Date.prototype.setMinutes()`