Date.prototype.getYear() - JavaScript

Date.prototype.getYear()
========================

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

**`getYear()`** 方法返回指定的本地日期的年份。因为 `getYear()` 不返回千禧年（"year 2000 problem"），所以这个方法不再被使用，现在替换为 `getFullYear`。

语法
--

```js
getYear()
```

### 返回值

`getYear` 方法返回一个年份减去 1900 的值；因此：

* 如果年份大于等于 2000，则 `getYear()` 的返回值将大于等于 100。例如，如果年份是 2026，则 `getYear()` 返回 126。
* 如果年份在 1900 到 1999 之间，`getYear()` 的返回值将在 0 到 99 之间。例如，如果年份是 1976，则 `getYear()` 返回 76。
* 如果年份小于 1900，则 `getYear()` 的返回值将小于 0。例如，如果年份是 1800，则 `getYear()` 返回 -100。

如果要同时考虑 2000 年之前和之后的年份，应该使用 `getFullYear()` 而不是 `getYear()`，以便指定完整年份。

向后兼容性
-----

### 在 JavaScript 1.2 及更早版本中的行为

The `getYear` method returns either a 2-digit or 4-digit year:

* For years between and including 1900 and 1999, the value returned by `getYear` is the year minus 1900. For example, if the year is 1976, the value returned is 76.
* For years less than 1900 or greater than 1999, the value returned by `getYear` is the four-digit year. For example, if the year is 1856, the value returned is 1856. If the year is 2026, the value returned is 2026.
示例
--

### 1900 年到 1999 年之间的年份

The second statement assigns the value 95 to the variable `year`.

```js
var Xmas = new Date("December 25, 1995 23:15:00");
var year = Xmas.getYear(); // returns 95
```

### 年份大于 1999

The second statement assigns the value 100 to the variable `year`.

```js
var Xmas = new Date("December 25, 2000 23:15:00");
var year = Xmas.getYear(); // returns 100
```

### 年份小于 1900

The second statement assigns the value -100 to the variable `year`.

```js
var Xmas = new Date("December 25, 1800 23:15:00");
var year = Xmas.getYear(); // returns -100
```

### 设置和获取 1900 年到 1999 年之间的年份

The second statement assigns the value 95 to the variable `year`, representing the year 1995.

```js
var Xmas.setYear(95);
var year = Xmas.getYear(); // returns 95
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getyear |

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

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

参见
--

* `Date.prototype.getFullYear()`
* `Date.prototype.getUTCFullYear()`
* `Date.prototype.setYear()`


Date.prototype.getUTCMilliseconds() - JavaScript

Date.prototype.getUTCMilliseconds()
===================================

**`getUTCMilliseconds()`** 方法以世界时为标准，返回一个指定的日期对象的毫秒数。

尝试一下
----

语法
--
```

dateObj.getUTCMilliseconds()
```

### 参数

无。

### 返回值

`getUTCMilliseconds()` 返回一个 0 到 999 的整数。

示例
--

### 示例：使用 `getUTCMilliseconds()` 方法

下例将当前时间的毫秒部分赋值给变量 `milliseconds`。

```js
var today = new Date();
var milliseconds = today.getUTCMilliseconds();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcmilliseconds |

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

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

参见
--

* `Date.prototype.getMilliseconds()`
* `Date.prototype.setUTCMilliseconds()`


Date.prototype.getFullYear() - JavaScript

Date.prototype.getFullYear()
============================

**`getFullYear()`** 方法根据本地时间返回指定日期的年份。

此方法替代 `getYear()` 。

尝试一下
----

语法
--

```html
dateObj.getFullYear()
```

### 返回值

根据当地时间，返回一个对应于给定日期的年份数字。

描述
--

`getFullYear()`返回的值是绝对数。对于 1000 到 9999 之间的日期，`getFullYear()`返回一个四位数字，如 1995。使用此函数确保在 2000 年后兼容。

示例
--

### 使用`getFullYear()`

下面的例子将当前年份的四位数值分配给变量`year`。

```js
var today = new Date();
var year = today.getFullYear();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getfullyear |

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

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

参见
--

* `Date.prototype.getUTCFullYear()`
* `Date.prototype.setFullYear()`
* `Date.prototype.getYear()`


Date.prototype.toLocaleTimeString() - JavaScript

Date.prototype.toLocaleTimeString()
===================================

**`toLocaleTimeString()`** 方法返回该日期对象时间部分的字符串，该字符串格式因语言而异。在支持 `Intl.DateTimeFormat` API 的实现中，该方法仅是调用了 `Intl.DateTimeFormat` 方法。

尝试一下
----

语法
--

```js
toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)
```

### 参数

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

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

`locales` 可选

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

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

`options` 可选

一个调整输出格式的对象。对应于 `Intl.DateTimeFormat()` 构造函数的 `options` (en-US) 参数。如果其 `dayPeriod`、`hour`、`minute`、`second` 和 `fractionalSecondDigits` 属性全是 undefined，则 `hour`、`minute`、`second` 这三个属性会被设置为 `"numeric"`。

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

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

### 返回值

一个表示给定的 `Date` 实例的时间部分，且与语言相关的字符串。

在支持 `Intl.DateTimeFormat` 的实现中，该方法等价于 `new Intl.DateTimeFormat(locales, options).format(date)`，其中的 `options` 已通过上述的规则进行规范化。

性能
--

当需要格式化大量的日期（date）时，最好创建一个 `Intl.DateTimeFormat` 对象，并使用其 `format()` (en-US) 方法。

示例
--

### 使用 toLocaleTimeString()

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

```js
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

// toLocaleTimeString() 不携带参数时，其默认区域和时区取决于实现
console.log(date.toLocaleTimeString());
// "11:00:00" 如果在 zh-CN 区域以及东八区（北京时间）下运行
```

### 使用 locales

以下示例显示不同的本地化时间格式。为了获得用户界面（UI）使用的语言格式表示的字符串，请确保使用了 `locales` 参数，并将其指定为用户所使用的语言。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 以下格式化输出均假设使用区域的本地时区；
// 对于美国，为 America/Los\_Angeles

// 美式英语，使用带有 AM/PM 的 12 小时制
console.log(date.toLocaleTimeString("en-US"));
// "11:00:00 AM"

// 英式英语，使用不带有 AM/PM 的 24 小时制
console.log(date.toLocaleTimeString("en-GB"));
// "03:00:00"

// 韩国，使用带有 AM/PM 的 12 小时制
console.log(date.toLocaleTimeString("ko-KR"));
// "오후 12:00:00"

// 大多数阿拉伯国家使用真正的阿拉伯数字
console.log(date.toLocaleTimeString("ar-EG"));
// "٧:٠٠:٠٠ م"

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

### 使用 options

可以使用 `options` 参数自定义 `toLocaleTimeString()` 所提供的结果。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 应用程序可能想要使用 UTC 时间，并使其可见
const options = { timeZone: "UTC", timeZoneName: "short" };
console.log(date.toLocaleTimeString("en-US", options));
// "3:00:00 AM GMT"

// 有时，区域设置为美国的情况下，需要使用 24 小时制
console.log(date.toLocaleTimeString("en-US", { hour12: false }));
// "19:00:00"

// 只显示小时和分钟，并使用默认区域——使用一个空数组
console.log(
  date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }),
);
// "20:01"
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tolocaletimestring |
| ECMAScript Internationalization API Specification # sup-date.prototype.tolocaletimestring |

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

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

参见
--

* `Intl.DateTimeFormat`
* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toLocaleString()`
* `Date.prototype.toTimeString()`
* `Date.prototype.toString()`


Date.prototype.setUTCMonth() - JavaScript

Date.prototype.setUTCMonth()
============================

**`setUTCMonth()`** 方法根据通用的时间来设置一个准确的月份。

尝试一下
----

语法
--
```

dateObj.setUTCMonth(monthValue[, dayValue])
```

### 参数

`monthValue`

一个 0-11 的整数，代表 1 月到 12 月。

`dayValue`

可选参数：一个 1-31 的整数，代表一个月的天数。

### 返回值

这个数值是从 1970 年 1 月 1 号 00:00:00 到当前时间的毫秒数（国际通用时间）

描述
--

如果你没有明确书写`dayValue` 这个参数，那么就会从`getUTCDate()` 方法返回对应的数值。

如果你写了一个超过在规定的范围内的参数。`setUTCMonth()` 就会试图相应的更新时间信息在 Data 对象中。例如，如果你用 15 作为 `monthValue` 的值，那么年份就会加 1，并且月份会变成 3。（15=12+3）

示例
--

### 使用 `setUTCMonth()`

```js
var theBigDay = new Date();
theBigDay.setUTCMonth(11);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcmonth |

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

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

更多
--

* `Date.prototype.getUTCMonth()`
* `Date.prototype.setMonth()`


Date.prototype.toUTCString() - JavaScript

Date.prototype.toUTCString()
============================

**`toUTCString()`** 方法把一个日期转换为一个字符串，使用 UTC 时区。

尝试一下
----

语法
--
```

dateObj.toUTCString()
```

### 返回值

返回使用 UTC 时区表示给定日期的字符串

描述
--

`toUTCString` 的返回值是一个使用 UTC 时区的易读格式字符串。返回值的格式可能随平台而变化。通常返回值是一个 RFC-1123 格式的时间戳，这是一个 RFC-822 时间戳的小幅更新版。

示例
--

### 示例：使用`toUTCString`
```

var today = new Date();
var UTCstring = today.toUTCString();
// Mon, 03 Jul 2006 21:44:38 GMT
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.toutcstring |

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

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

参见
--

* `Date.prototype.toLocaleString()`
* `Date.prototype.toDateString()`
* `Date.prototype.toISOString()`


Date.prototype.setUTCDate() - JavaScript

Date.prototype.setUTCDate()
===========================

**`setUTCDate()`** 方法就是根据全球时间设置特定 date 对象的日期。

尝试一下
----

语法
--
```

dateObj.setUTCDate(dayValue)
```

### 参数

`dayValue`

一个 1-31 的整形数字，用来指定日期。

描述
--

如果你指定的参数超出了范围，setUTCDate() 会尝试更新对应的`Date` 中的日期信息。例如，如果你使用了 40 来作为参数，但是`Date` 中存储的月份为 6 月，那么日期将被改写为 10 且月份被增到 7 月。

示例
--

### 使用 `setUTCDate()`

```js
var theBigDay = new Date();
theBigDay.setUTCDate(20);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcdate |

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

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

相关内容
----

* `Date.prototype.getUTCDate()`
* `Date.prototype.setDate()`


Date.prototype.setHours() - JavaScript

Date.prototype.setHours()
=========================

**`setHours()`** 方法根据本地时间为一个日期对象设置小时数，返回从 1970-01-01 00:00:00 UTC 到更新后的 `日期` 对象实例所表示时间的毫秒数。

尝试一下
----

语法
--
```

dateObj.setHours(hoursValue[, minutesValue[, secondsValue[, msValue]]])
```

### JavaScript 1.3 版本之前
```

dateObj.setHours(hoursValue)
```

### 参数

`hoursValue`

一个 0 到 23 的整数，表示小时。

`minutesValue`

一个 0 到 59 的整数，表示分钟。

`secondsValue`

一个 0 到 59 的整数，表示秒数。如果指定了 `secondsValue` 参数，则必须同时指定 `minutesValue` 参数。

`msValue`

一个 0 到 999 的数字，表示微秒数，如果指定了 `msValue` 参数，则必须同时指定 `minutesValue` 和 `secondsValue` 参数。

描述
--

如果不指定 `minutesValue`，`secondsValue` 和 `msValue` 参数，则会使用`getMinutes()`，`getSeconds()` 和`getMilliseconds()` 方法的返回值。

如果有一个参数超出了合理范围，`setHours` 会相应地更新日期对象中的日期信息。例如，如果为 `secondsValue` 指定了 100，则分钟会加 1，然后秒数使用 40。

示例
--

### 示例：使用 `setHours` 方法

```js
var theBigDay = new Date();
theBigDay.setHours(7);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.sethours |

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

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

参见
--

* `Date.prototype.getHours()`
* `Date.prototype.setUTCHours()`


Date.prototype.toString() - JavaScript

Date.prototype.toString()
=========================

**`toString()`** 方法返回一个字符串，以本地的时区表示该 `Date` 对象。

尝试一下
----

语法
--

```js
toString()
```

### 返回值

一个表示给定 date 对象的字符串。

描述
--

`Date` 对象覆盖了 `Object` 对象的 `toString()` 方法。`Date.prototype.toString()` 返回一个字符串，并以本地时区表示该 Date 对象，包含日期和时间——将 `toDateString()` 和 `toTimeString()` 通过一个空格拼接起来。

例如：“Thu Jan 01 1970 12:42:04 GMT+0800 (中国标准时间)”。

当 Date 被强制转换为字符串时，`toString()` 方法会被自动调用，例如：`const today = 'Today is ' + new Date()`。

`Date.prototype.toString()` 必须在 `Date` 实例上调用，如果 `this` 的值不是继承自 `Date.prototype`，则抛出 `TypeError`。

* 如果你只想获取*日期*，请使用 `toDateString()`。
* 如果你只想获取*时间*，请使用 `toTimeString()`。
* 如果你想要获取 UTC 时间而非本地时间，请使用 `toUTCString()`。
* 如果你想要以对用户更加友好的格式（例如，本地化）输出字符串，请使用 `toLocaleString()`。
示例
--

### 使用 toString()

```js
const x = new Date();
console.log(x.toString()); // Wed Sep 09 1998 05:36:22 GMT+0800 (中国标准时间)
```

规范
--

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

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

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

参见
--

* `Object.prototype.toString()`
* `Date.prototype.toDateString()`
* `Date.prototype.toLocaleString()`
* `Date.prototype.toTimeString()`


Date.prototype.toISOString() - JavaScript

Date.prototype.toISOString()
============================

**`toISOString()`** 方法返回一个 ISO（ISO 8601 Extended Format）格式的字符串： **YYYY-MM-DDTHH:mm:ss.sssZ**。时区总是 UTC（协调世界时），加一个后缀“Z”标识。

尝试一下
----

语法
--
```

dateObj.toISOString()
```

示例
--

### 使用 toISOString()

```js
const d = new Date(0);

console.log(d.toISOString()); // "1970-01-01T00:00:00.000Z"
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.toisostring |

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

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

参见
--

* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toTimeString()`
* `Date.prototype.toUTCString()`


Date.now() - JavaScript

Date.now()
==========

**`Date.now()`** 方法返回自 1970 年 1 月 1 日 00:00:00 (UTC) 到当前时间的毫秒数。

尝试一下
----

语法
--
```

var timeInMs = Date.now();
```

### 返回值

一个 `Number`，表示自 UNIX 纪元开始（1970 年 1 月 1 日 00:00:00 (UTC)）到当前时间的毫秒数。

描述
--

因为 `now()` 是 `Date` 的一个静态函数，所以必须以 `Date.now()` 的形式来使用。

时间精度被降低
-------

 为了提供针对定时攻击和指纹追踪的保护，`Date.now()` 的精度可能会根据浏览器的高级设置项目而被取整。
 在 Firefox 中，默认启用 `privacy.reduceTimerPrecision` 设置项，在 Firefox 59 中，默认被取整至 20 微秒；在 Firefox 60 中，则被取整至 2 毫秒。

```js
// reduced time precision (2ms) in Firefox 60
Date.now();
// 1519211809934
// 1519211810362
// 1519211811670
// ...

// reduced time precision with `privacy.resistFingerprinting` enabled
Date.now();
// 1519129853500
// 1519129858900
// 1519129864400
// ...
```

在 Firefox 中，还可以通过启用 `privacy.resistFingerprinting` 来进一步降低精度。启用后，精度将为 100 毫秒或者 `privacy.resistFingerprinting.reduceTimerPrecision.microseconds` 的值，取决于这两个值中哪一个更大，也就是，精度更低一些。

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.now |

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

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

参见
--

* `Performance.now()` — 提供了精确到亚毫秒（sub-millisecond）的时间戳，用于衡量网页性能。
* `console.time` / `console.timeEnd`


Date.prototype.setMinutes() - JavaScript

Date.prototype.setMinutes()
===========================

**`setMinutes()`** 方法根据本地时间为一个日期对象设置分钟数。

尝试一下
----

语法
--
```

dateObj.setMinutes(minutesValue[, secondsValue[, msValue]])
```

### JavaScript 1.3 之前版本
```

dateObj.setMinutes(minutesValue)
```

### 参数

`minutesValue`

一个 0 到 59 的整数，表示分钟数。

`secondsValue`

一个 0 到 59 的整数，表示秒数。如果指定了 `secondsValue` 参数，则必须同时指定 `minutesValue` 参数。

`msValue`

一个 0 到 999 的数字，表示微秒数，如果指定了 `msValue` 参数，则必须同时指定 `minutesValue` 和`secondsValue` 参数。

描述
--

如果没有指定 `secondsValue` 和 `msValue` 参数，就会使用 `getSeconds()` 和 `getmilliseconds()` 方法的返回值。

如果有一个指定的参数超出了合理范围，`setMinutes` 会相应地更新日期对象中的时间信息。例如，为 `secondsValue` 指定 100，分钟数将会加 1，而秒数会为 40。

示例
--

### 示例：使用`setMinutes` 方法

```js
var theBigDay = new Date();
theBigDay.setMinutes(45);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setminutes |

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

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

参见
--

* `Date.prototype.getMinutes()`
* `Date.prototype.setUTCMinutes()`


Date.prototype.getUTCFullYear() - JavaScript

Date.prototype.getUTCFullYear()
===============================

**`getUTCFullYear()`** 以世界时为标准，返回一个指定的日期对象的年份。

尝试一下
----

语法
--
```

dateObj.getUTCFullYear()
```

### 参数

无。

### 返回值

`getUTCFullYear()` 返回一个绝对数值，符合 Year-2000 标准，例如 1995。

示例
--

### 示例：使用 `getUTCFullYear()` 方法

下面的例子是把当前年份的四位数值复制给变量 `year`。

```js
var today = new Date();
var year = today.getUTCFullYear();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcfullyear |

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

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

参见
--

* `Date.prototype.getFullYear()`
* `Date.prototype.setFullYear()`


Date.prototype.setYear() - JavaScript

Date.prototype.setYear()
========================

**已弃用:** 不再推荐使用该特性。虽然一些浏览器仍然支持它，但也许已从相关的 web 标准中移除，也许正准备移除或出于兼容性而保留。请尽量不要使用该特性，并更新现有的代码；参见本页面底部的兼容性表格以指导你作出决定。请注意，该特性随时可能无法正常工作。

**`setYear()`** 方法根据一个本地时间为一个确定的日期对象设置年份。由于`setYear()` 并不设置完整年份（"正是千年虫问题"），本方法已经完全被`setFullYear()` 方法所取代。

语法
--
```

dateObj.setYear(yearValue)
```

### 参数

`yearValue`

一个整数。

### 返回值

介于 1970 年 1 月 1 日 00:00:00 UTC 时间与更新后日期的毫秒数。

描述
--

如果`yearValue` 是介于 0 到 99(包含 99) 之间的整数，则目标对象 `dateObj` 的年份被设置为 `1900 + yearValue`。否则，目标对象 `dateObj` 的年份被设置为 `yearValue`.

示例
--

### 使用 `setYear()`

例子前两行（除去声明）将年份设置为 1996。第三行将年份设置为 2000.

```js
var theBigDay = new Date();

theBigDay.setYear(96);
theBigDay.setYear(1996);
theBigDay.setYear(2000);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setyear |

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

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

参见
--

* `Date.prototype.getFullYear()`
* `Date.prototype.getUTCFullYear()`
* `Date.prototype.setFullYear()`
* `Date.prototype.setUTCFullYear()`


Date.prototype.toLocaleDateString() - JavaScript

Date.prototype.toLocaleDateString()
===================================

**`toLocaleDateString()`** 方法返回指定日期对象日期部分的字符串，该字符串格式因不同语言而不同。在支持 `Intl.DateTimeFormat` API 的实现中，该方法仅是调用了 `Intl.DateTimeFormat` 方法。

尝试一下
----

语法
--

```js
toLocaleDateString()
toLocaleDateString(locales)
toLocaleDateString(locales, options)
```

### 参数

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

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

`locales` 可选

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

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

`options` 可选

一个调整输出格式的对象。对应于 `Intl.DateTimeFormat()` 构造函数的 `options` (en-US) 参数。如果其 `dayPeriod`、`hour`、`minute`、`second` 和 `fractionalSecondDigits` 属性全是 undefined，则 `hour`、`minute`、`second` 这三个属性会被设置为 `"numeric"`。

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

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

### 返回值

一个表示给定的 `Date` 实例的日期部分，且与语言相关的字符串。

在支持 `Intl.DateTimeFormat` 的实现中，该方法等价于 `new Intl.DateTimeFormat(locales, options).format(date)`，其中的 `options` 已通过上述的规则进行规范化。

性能
--

当需要格式化大量的日期（date）时，最好创建一个 `Intl.DateTimeFormat` 对象，并使用其 `format()` (en-US) 方法。

示例
--

### 使用 toLocaleDateString()

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

```js
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

// toLocaleDateString() 不携带参数时，其默认区域和时区取决于实现
console.log(date.toLocaleDateString());
// "2012/12/12" 如果在 zh-CN 区域以及东八区（北京时间）下运行
```

### 检测 locales 和 options 参数支持情况

`locales` 和 `options` 参数不是所有的浏览器都支持。为了检测一种实现环境（implementation）是否支持它们，可以使用不合法的语言标签，如果实现环境支持该参数，则会抛出 `RangeError` 异常，反之会忽略参数。

```js
function toLocaleDateStringSupportsLocales() {
  try {
    new Date().toLocaleDateString("i");
  } catch (e) {
    return e.name === "RangeError";
  }
  return false;
}
```

### 使用 locales

下例展示了本地化日期格式的一些变化。为了在应用的用户界面得到某种语言的日期格式，必须确保使用 `locales` 参数指定了该语言（可能还需要设置某些回退语言）。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 以下格式化输出均假设使用区域的本地时区；
// 对于美国，为 America/Los\_Angeles

// 美式英语，使用 month-day-year 的顺序
console.log(date.toLocaleDateString("en-US"));
// "12/20/2012"

// 英式英语，使用 day-month-year 的顺序
console.log(date.toLocaleDateString("en-GB"));
// "20/12/2012"

// 韩国，使用 year-month-day 的顺序
console.log(date.toLocaleDateString("ko-KR"));
// "2012. 12. 20."

// Event for Persian, It's hard to manually convert date to Solar Hijri
console.log(date.toLocaleDateString("fa-IR"));
// "۱۳۹۱/۹/۳۰"

// 大多数阿拉伯国家使用真正的阿拉伯数字
console.log(date.toLocaleDateString("ar-EG"));
// "٢٠/١٢/٢٠١٢"

// 对于日语，应用倾向于使用日本的和历，
// 2012 年是平成时代的第 24 年
console.log(date.toLocaleDateString("ja-JP-u-ca-japanese"));
// "24/12/20"

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

### 使用 options

可以使用 `options` 参数来自定义 `toLocaleDateString` 方法返回的字符串。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// request a weekday along with a long date
const options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
console.log(date.toLocaleDateString("de-DE", options));
// "Donnerstag, 20. Dezember 2012"

// 应用程序可能想要使用 UTC 时间，并使其可见
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(date.toLocaleDateString("en-US", options));
// "Thursday, December 20, 2012, UTC"
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tolocaledatestring |
| ECMAScript Internationalization API Specification # sup-date.prototype.tolocaledatestring |

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

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

参见
--

* `Intl.DateTimeFormat`
* `Date.prototype.toLocaleString()`
* `Date.prototype.toLocaleTimeString()`
* `Date.prototype.toString()`


Date.prototype.getMilliseconds() - JavaScript

Date.prototype.getMilliseconds()
================================

**`getMilliseconds()`** 方法根据本地时间，返回一个指定的日期对象的毫秒数。

尝试一下
----

语法
--

```js
getMilliseconds()
```

### 参数

无

### 描述

`getMilliseconds()` 方法返回一个 0 到 999 的整数。

示例
--

### 示例：使用`getMilliseconds`方法

下例中，将当前时间的毫秒数赋值给变量 `ms`。

```js
var ms;
Today = new Date();
ms = Today.getMilliseconds();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getmilliseconds |

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

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

参见
--

* `Date.prototype.getUTCMilliseconds()`
* `Date.prototype.setMilliseconds()`


Date.prototype.getUTCMinutes() - JavaScript

Date.prototype.getUTCMinutes()
==============================

**`getUTCMinutes()`** 方法以世界时为标准，返回一个指定的日期对象的分钟数。

尝试一下
----

语法
--
```

dateObj.getUTCMinutes()
```

### 参数

无。

### 返回值

`getUTCMinutes()` 返回一个 0 到 59 的整数。

示例
--

### 示例：使用 `getUTCMinutes()` 方法

下例将当前时间的分钟部分赋值给变量 `minutes`。

```js
var today = new Date();
var minutes = today.getUTCMinutes();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcminutes |

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

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

参见
--

* `Date.prototype.getMinutes()`
* `Date.prototype.setUTCMinutes()`


Date.prototype.setMonth() - JavaScript

Date.prototype.setMonth()
=========================

**`setMonth()`** 方法根据本地时间为一个日期对象设置月份。

尝试一下
----

语法
--
```

dateObj.setMonth(monthValue[, dayValue])
```

### JavaScript 1.3 版本之前
```

dateObj.setMonth(monthValue)
```

### 参数

`monthValue`

介于 0 到 11 之间的整数（表示一月到十二月）。

`dayValue`

从 1 到 31 之间的整数，表示月份中的第几天。0 为上个月最后一天

返回值！

基于 1 January 1970 00:00:00 UTC 开始计算的毫秒数

描述
--

如果不指定 `dayValue` 参数，就会使用 `getDate` 方法的返回值。

如果有一个指定的参数超出了合理范围，`setMonth` 会相应地更新日期对象中的日期信息。例如，为 `monthValue` 指定 15，则年份会加 1，月份将会使用 3。

示例
--

### 示例：使用 `setMonth` 方法

```js
var theBigDay = new Date();
theBigDay.setMonth(6);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setmonth |

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

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

参见
--

* `Date.prototype.getMonth()`
* `Date.prototype.setUTCMonth()`


Date.prototype.getUTCDate() - JavaScript

Date.prototype.getUTCDate()
===========================

**`getUTCDate()`** 方法以世界时为标准，返回一个指定的日期对象为一个月中的第几天

尝试一下
----

语法
--
```

dateObj.getUTCDate()
```

### 参数

无

### 返回值

`getUTCDate()` 返回一个 1 到 31 的整数值

示例
--

### 示例：使用 `getUTCDate()` 方法

下面的例子是把当前日期的天数部分赋值给变量 `day`.

```js
var today = new Date();
var day = today.getUTCDate();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcdate |

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

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

参见
--

* `Date.prototype.getDate()`
* `Date.prototype.getUTCDay()`
* `Date.prototype.setUTCDate()`


Date.prototype[@@toPrimitive] - JavaScript

Date.prototype[@@toPrimitive]
=============================

**`[@@toPrimitive]()`** 方法可以转换一个 `Date` 对象到一个原始值。

用法
--
```

Date()[Symbol.toPrimitive](hint);
```

### 返回值

给出的 `Date` 的原始值。根据传入参数的不同，可以返回 string 或 number 类型。

说明
--

`Date` 对象的 `[@@toPrimitive]()` 方法可以返回一个原始值，或是 string，或是 number。

如果 `hint` 是 `"string"` 或 `"default"`，`[@@toPrimitive]()` 将会调用 `toString`。如果 `toString` 属性不存在，则调用 `valueOf`。如果 `valueOf` 也不存在，则抛出一个`TypeError`。

如果 `hint` 是 `"number"`，`[@@toPrimitive]()` 会首先尝试 `valueOf`，若失败再尝试 `toString`。

当期望一个原始值却收到一个对象时，JavaScript 可以自动的调用 `[@@toPrimitive]()` 方法来将一个对象转化成原始值，所以你很少会需要自己调用这个方法。

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

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype-@@toprimitive |

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

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

See also
--------

* `Symbol.toPrimitive`


Date.prototype.setMilliseconds() - JavaScript

Date.prototype.setMilliseconds()
================================

`Date` 实例的 **`setMilliseconds()`** 方法会根据本地时间设置一个日期对象的毫秒数。

尝试一下
----

语法
--

```js
setMilliseconds(millisecondsValue)
```

### 参数

`millisecondsValue`

一个在 0 到 999 之间的整数，表示毫秒数。

### 返回值

原地更改 `Date` 对象，并返回新的时间戳。如果 `millisecondsValue` 是 `NaN`（或任何其他经强制转换后得到 `NaN` 的值，如 `undefined`），日期会被设置为无效日期，并返回 `NaN`。

描述
--

如果指定的数字超出了合理范围，则 `Date` 对象的时间信息会被相应地更新。例如，如果指定了 1005，则秒数加 1，毫秒数为 5。

示例
--

### 使用 setMilliseconds()

```js
const theBigDay = new Date();
theBigDay.setMilliseconds(100);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setmilliseconds |

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

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

参见
--

* `Date.prototype.getMilliseconds()`
* `Date.prototype.setUTCMilliseconds()`


Date.prototype.setUTCHours() - JavaScript

Date.prototype.setUTCHours()
============================

The **`setUTCHours()`** method sets the hour for a specified date according to universal time, and returns the number of milliseconds since 1 January 1970 00:00:00 UTC until the time represented by the updated `Date` instance.

尝试一下
----

Syntax
------
```

dateObj.setUTCHours(hoursValue[, minutesValue[, secondsValue[, msValue]]])
```

### 参数

`hoursValue`

表示小时的整数，取值 0 到 23 之间。

`minutesValue`

可选参数。表示分钟的整数，取值 0 到 59 之间。

`secondsValue`

可选参数。表示秒数的整数，取值 0 到 59 之间。如果指定了该参数，就要同时指定 `minutesValue` 这个参数。

`msValue`

可选参数。表示毫秒的整数，取值 0 到 999 之间。如果指定了该参数，就要指定 `minutesValue` 和 `secondsValue` 这两个参数。

### 返回值

返回从 1970-01-01 00:00:00 UTC 到更新后的日期所表示时间的毫秒数。

描述
--

If you do not specify the `minutesValue`, `secondsValue`, and `msValue` parameters, the values returned from the `getUTCMinutes()`, `getUTCSeconds()`, and `getUTCMilliseconds()` methods are used.

If a parameter you specify is outside of the expected range, `setUTCHours()` attempts to update the date information in the `Date` object accordingly. For example, if you use 100 for `secondsValue`, the minutes will be incremented by 1 (`minutesValue + 1`), and 40 will be used for seconds.

示例
--

### 使用 `setUTCHours()`

```js
var theBigDay = new Date();
theBigDay.setUTCHours(8);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutchours |

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

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

参见
--

* `Date.prototype.getUTCHours()`
* `Date.prototype.setHours()`


Date.prototype.getTime() - JavaScript

Date.prototype.getTime()
========================

**`getTime()`** 方法返回一个时间的格林威治时间数值。

你可以使用这个方法把一个日期时间赋值给另一个`Date` 对象。这个方法的功能和 `valueOf()` 方法一样。

尝试一下
----

语法
--
```

dateObj.getTime()
```

### 参数

无。

### 返回值

`getTime` 方法的返回值一个数值，表示从 1970 年 1 月 1 日 0 时 0 分 0 秒（UTC，即协调世界时）距离该日期对象所代表时间的毫秒数。

示例
--

### 使用 getTime() 复制日期对象

创建一个拥有相同时间值的日期对象。

```js
var birthday = new Date(1991, 9, 17);
var copy = new Date();
copy.setTime(birthday.getTime());
```

### 测量代码执行时间

连续调用两个新生成的日期对象的 getTime 方法，根据两次调用的返回值求得时间差。这可以用于计算某些操作的执行时间。避免生成不必要的`Date`对象另见`Date.now()`

```js
var end, start, i;

start = new Date();
for (i = 0; i < 1000; i++) {
  Math.sqrt(i);
}
end = new Date();

console.log("Operation took " + (end.getTime() - start.getTime()) + " msec");
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.gettime |

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

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

参见
--

* `Date.prototype.setTime()`
* `Date.prototype.valueOf()`
* `Date.now()`


Date.prototype.setUTCSeconds() - JavaScript

Date.prototype.setUTCSeconds()
==============================

`此 setUTCSeconds()` 方法为一个依据国际通用时间的特定日期设置秒数。

尝试一下
----

语法
--
```

dateObj.setUTCSeconds(secondsValue[, msValue])
```

### 参数

`secondsValue`

一个在 0 到 59 之间的整数，表示秒数。

`msValue`

可选参数。一个 0 到 999 之间的数字，代表毫秒数。

### 返回值

一个毫秒数，表示从国际通用时间 1970 年 00:00:00 到设置的时间值之间的时间跨度。

描述
--

如果你没有设置 msValue 参数的值，那么返回的值来自`getUTCMilliseconds()` 方法。

如果你指定的值超出了范围，`setUTCSeconds()` 因此会更新`Date` 对象中 date 的相关信息 . 举个例子，如果你设置 secondsValue 为 100, `Date` 对象中的分钟数会增加 1，并且秒数会变成 40.

示例
--

### 使用 `setUTCSeconds()`

```js
var theBigDay = new Date();
theBigDay.setUTCSeconds(20);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcseconds |

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

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

另见
--

* `Date.prototype.getUTCSeconds()`
* `Date.prototype.setSeconds()`


Date.UTC() - JavaScript

Date.UTC()
==========

**`Date.UTC()`** 方法接受的参数同 `Date` 构造函数接受最多参数时一样，但该前者会视它们为 UTC 时间，其返回从 1970 年 1 月 1 日 00:00:00 UTC 到指定时间的毫秒数。

尝试一下
----

语法
--

```js
Date.UTC(year)
Date.UTC(year, month)
Date.UTC(year, month, day)
Date.UTC(year, month, day, hour)
Date.UTC(year, month, day, hour, minute)
Date.UTC(year, month, day, hour, minute, second)
Date.UTC(year, month, day, hour, minute, second, millisecond)
```

参数
--

`year`

一个表示年份的整数值。

从 `0` 到 `99` 的值会被映射到 `1900` 至 `1999` 年。其他的值则代表实际的年份。参见示例。

`month` 可选

`0`（一月）到 `11`（十二月）之间的一个整数，表示月份。从 ECMAScript 2017 开始，如果忽略该值，则默认为 `0`。*（直到 ECMAScript 2016，`month` 都是必须的参数。而从 ES2017 开始，它不再是必须的。）*

`date` 可选

`1` 到 `31` 之间的一个整数，表示某月当中的第几天。如果忽略该值，则默认为 `1`。

`hour` 可选

`0` 到 `23` 之间的一个整数，表示小时。如果忽略该值，则默认为 `0`。

`minute` 可选

`0` 到 `59` 之间的一个整数，表示分钟。如果忽略该值，则默认为 `0`。

`second` 可选

`0` 到 `59` 之间的一个整数，表示秒。如果忽略该值，则默认为 `0`。

`millisecond` 可选

`0` 到 `999` 之间的一个整数，表示毫秒。如果忽略该值，则默认为 `0`。

### 返回值

一个数字，表示从 1970 年 1 月 1 日 00:00:00 UTC 到给定时间的毫秒数。

描述
--

`UTC()` 方法接受以逗号隔开的时间参数，返回 1970 年 1 月 1 日 00:00:00 UTC 到指定的时间之间的毫秒数。

如果年份被指定为 `0` 到 `99` 之间，则该方法会将年份转换为 20 世纪的一个年份（即 `1900 + year`），例如，指定为 `95`，则年份为 `1995`。

`UTC()` 方法与 `Date` 构造函数有两点不同：

1. `Date.UTC()` 方法使用协调世界时代替本地时间。
2. `Date.UTC()` 方法返回一个时间数值，而不是一个 `Date` 对象。

如果有一个指定的参数超出其合理范围，则 UTC 方法会通过更新其他参数直到该参数在合理范围内。例如，为月份指定 `15`，则年份将会加 `1`（`year + 1`），然后月份将会使用 `3`。

由于 `UTC()` 是 `Date` 的一个静态方法，所以应该直接调用 `Date.UTC()`，而不要把它作为 `Date` 实例的方法。

示例
--

### 使用 Date.UTC()

下面的语句使用 UTC 时间代替本地时间创建了一个 `Date` 对象。

```js
const utcDate = new Date(Date.UTC(2018, 11, 1, 0, 0, 0));
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.utc |

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

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

### 兼容性备注

#### 少于两个参数的 Date.UTC()

当向 `Date.UTC()` 提供少于两个的参数时，ECMAScript 2017 要求返回 `NaN`。不支持此行为的引擎已被更新（参见 bug 1050755、ecma-262 #642）。

```js
Date.UTC();
Date.UTC(1);

// Safari: NaN
// Chrome/Opera/V8: NaN

// Firefox <54: non-NaN
// Firefox 54+: NaN

// IE: non-NaN
// Edge: NaN
```

参见
--

* `Date.parse()`
* `Date`


Date.prototype.toTimeString() - JavaScript

Date.prototype.toTimeString()
=============================

**`toTimeString()`** 方法以人类易读形式返回一个日期对象时间部分的字符串，该字符串以美式英语格式化。

尝试一下
----

语法
--
```

dateObj.toTimeString()
```

描述
--

`Date` 对象的实例引用一个具体的时间点。调用 `toString` 方法以美式英语和人类易读的形式，返回日期对象的格式化字符串。在 SpiderMonkey 里，该字符串由日期部分（年月日）和其后的时间部分（时分秒和时区）组成。有时会需要获取时间部分的字符串，这可以由 `toTimeString` 方法完成。

The `toTimeString` method is especially useful because compliant engines implementing ECMA-262 (en-US) may differ in the string obtained from `toString` for `Date` objects, as the format is implementation-dependent; simple string slicing approaches may not produce consistent results across multiple engines.

示例
--

### 示例：`toTimeString` 方法的简单使用

```js
var d = new Date(1993, 6, 28, 14, 39, 7);

println(d.toString()); // prints Wed Jul 28 1993 14:39:07 GMT-0600 (PDT)
println(d.toTimeString()); // prints 14:39:07 GMT-0600 (PDT)
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.totimestring |

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

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

参见
--

* `Date.prototype.toLocaleTimeString()`
* `Date.prototype.toDateString()`
* `Date.prototype.toString()`


Date.prototype.getDay() - JavaScript

Date.prototype.getDay()
=======================

**`getDay()`** 方法根据本地时间，返回一个具体日期中一周的第几天，0 表示星期天。对于某个月中的第几天，参考`Date.prototype.getDate()`.

尝试一下
----

语法
--

```js
getDay()
```

### 返回值

根据本地时间，返回一个 0 到 6 之间的整数值，代表星期几：0 代表星期日，1 代表星期一，2 代表星期二，依次类推。

示例
--

### 使用`getDay()`

下面第二条语句，基于`Date`对象 `Xmas95` 的值，把 1 赋值给 `weekday`。也就是说 1995 年 12 月 25 日是星期一。

```js
var Xmas95 = new Date("December 25, 1995 23:15:30");
var weekday = Xmas95.getDay();

console.log(weekday); // 1
```

**备注：** 如果需要，可以使用`Intl.DateTimeFormat`与一个额外的`options` 参数，从而返回这天的全称（如`"Monday"`）.使用此方法，结果会更加国际化：

```js
var options = { weekday: "long" };
console.log(new Intl.DateTimeFormat("en-US", options).format(Xmas95));
// Monday
console.log(new Intl.DateTimeFormat("de-DE", options).format(Xmas95));
// Montag
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getday |

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

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

参见
--

* `Date.prototype.getUTCDate()`
* `Date.prototype.getUTCDay()`
* `Date.prototype.setDate()`


Date.prototype.setDate() - JavaScript

Date.prototype.setDate()
========================

**`setDate()`** 方法根据本地时间来指定一个日期对象的天数。

尝试一下
----

语法
--
```

dateObj.setDate(dayValue)
```

### 参数

`dayValue`

一个整数，表示该月的第几天。

描述
--

如果 `dayValue` 超出了月份的合理范围，`setDate` 将会相应地更新 `Date` 对象。

例如，如果为 `dayValue` 指定 0，那么日期就会被设置为上个月的最后一天。

如果 dayValue 被设置为负数，日期会设置为上个月最后一天往前数这个负数绝对值天数后的日期。-1 会设置为上月最后一天的前一天（译者注：例如当前为 4 月，如果 setDate(-2),则为 3 月 29 日）

示例
--

### 示例：使用`setDate`方法

```js
var theBigDay = new Date(1962, 6, 7); // 1962-07-07
theBigDay.setDate(24); // 1962-07-24
theBigDay.setDate(32); // 1962-08-01
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setdate |

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

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

参见
--

* `Date.prototype.getDate()`
* `Date.prototype.setUTCDate()`


Date.prototype.getSeconds() - JavaScript

Date.prototype.getSeconds()
===========================

**`getSeconds()`** 方法根据本地时间，返回一个指定的日期对象的秒数。

尝试一下
----

语法
--

```js
getSeconds()
```

### 参数

无

### 描述

该方法返回一个 0 到 59 的整数值。

示例
--

### 示例：使用`getSeconds` 方法

下面第二条语句，基于日期对象 `Xmas95` 的值，把 30 赋值给变量 `secs`。

```js
var Xmas95 = new Date("December 25, 1995 23:15:30");
var secs = Xmas95.getSeconds();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getseconds |

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

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

参见
--

* `Date.prototype.getUTCSeconds()`
* `Date.prototype.setSeconds()`


Date.prototype.setFullYear() - JavaScript

Date.prototype.setFullYear()
============================

**`setFullYear()`** 方法根据本地时间为一个日期对象设置年份。

尝试一下
----

语法
--

```js
dateObj.setFullYear(yearValue[, monthValue[, dayValue]])
```

### 参数

`yearValue`

指定年份的整数值，例如 1995。

`monthValue`

一个 0 到 11 之间的整数值，表示从一月到十二月。

`dayValue`

一个 1 到 31 之间的整数值，表示月份中的第几天。如果你指定了 `dayValue` 参数，就必须同时指定 `monthValue`。

描述
--

如果没有指定 `monthValue` 和`dayValue` 参数，将会使用 `getMonth` 和`getDate` 方法的返回值。

如果有一个参数超出了合理的范围，`setFullYear` 方法会更新其他参数值，日期对象的日期值也会被相应更新。例如，为 `monthValue` 指定 15，则年份会加 1，月份值会为 3。

示例
--

### 示例：使用`setFullYear`方法

```js
var theBigDay = new Date();
theBigDay.setFullYear(1997);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setfullyear |

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

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

参见
--

* `Date.prototype.getUTCFullYear()`
* `Date.prototype.setUTCFullYear()`
* `Date.prototype.setYear()`


Date.prototype.getUTCMonth() - JavaScript

Date.prototype.getUTCMonth()
============================

**`getUTCMonth()`** 方法以世界时为标准，返回一个指定的日期对象的月份，它是从 0 开始计数的（0 代表一年的第一个月）。

尝试一下
----

语法
--
```

dateObj.getUTCMonth()
```

### 参数

无。

### 返回值

`getUTCMonth()` 返回一个 0 到 11 的整数，分别对应以下月份：0 代表一月，1 代表二月，2 代表三月，依次类推。

示例
--

### 示例：使用 `getUTCMonth()` 方法

下例将当前时间的月份赋值给变量 `month`。

```js
var today = new Date();
var month = today.getUTCMonth();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcmonth |

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

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

参见
--

* `Date.prototype.getMonth()`
* `Date.prototype.setUTCMonth()`


Date.prototype.getHours() - JavaScript

Date.prototype.getHours()
=========================

**`getHours()`** 方法根据本地时间，返回一个指定的日期对象的小时。

尝试一下
----

语法
--

```js
getHours()
```

### 参数

无

### 返回值

`getHours` 返回一个 0 到 23 之间的整数值。

示例
--

### 示例：使用`getHours`方法

下面第二条语句，基于日期对象 `Xmas95` 的值，把 23 赋值给了变量 `hours`。

```js
var Xmas95 = new Date("December 25, 1995 23:15:00");
var hours = Xmas95.getHours();

alert(hours); // 23
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.gethours |

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

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

参见
--

* `Date.prototype.getUTCHours()`
* `Date.prototype.setHours()`


Date.prototype.setUTCMinutes() - JavaScript

Date.prototype.setUTCMinutes()
==============================

\*\*`setUTCMinutes()`\*\*方法会根据世界协调时（UTC）来设置指定日期的分钟数。

尝试一下
----

语法
--
```

dateObj.setUTCMinutes(minutesValue[, secondsValue[, msValue]])
```

### 参数

`minutesValue`

必填，表示要设置的分钟数，是一个介于 0 和 59 之间的整数。

`secondsValue`

可选参数，表示要设置的秒数，同样也是一个介于 0 和 59 之间的整数，如果你传入了这个参数，那么你就必须要传入上一个参数（**`minutesValue`**）。

`msValue`

可选参数，表示要设置的毫秒数，这是一个介于 0 和 999 之间的数字，如果你传入了这个参数，那么你就必须要传入前面两个参数（**`minutesValue`**和**`secondsValue`**）。

### 返回值

返回从 UTC 时间 1970 年 1 月 1 日 0 时 0 分 0 秒至设置后的时间的毫秒数。

说明
--

如果你没有传入后两个参数（**`minutesValue`**和**`msValue`**），这两个参数会分别使用`getUTCSeconds()`和`getUTCMilliseconds()`这两个方法返回的值。

如果你传入的参数值在上文所述范围之外的话，**`setUTCMinutes()`**方法会尝试修改日期对象中的其他信息，比如说你为 **`secondsValue`** 这个参数传入了 100（译者注：规定范围是 [0, 59]），那么第一个参数（**`minutesValue`**）就会被加 1，而秒数则变成了 40。

示例
--

### 使用 `setUTCMinutes()`

```js
var theBigDay = new Date();
theBigDay.setUTCMinutes(43);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcminutes |

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

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

相关知识
----

* `Date.prototype.getUTCMinutes()`
* `Date.prototype.setMinutes()`


Date() 构造函数 - JavaScript

Date() 构造函数
===========

**`Date()`** 构造函数可以创建一个 `Date` 实例或返回代表当前时间的字符串。

尝试一下
----

语法
--

```js
new Date()
new Date(value)
new Date(dateString)
new Date(dateObject)

new Date(year, monthIndex)
new Date(year, monthIndex, day)
new Date(year, monthIndex, day, hours)
new Date(year, monthIndex, day, hours, minutes)
new Date(year, monthIndex, day, hours, minutes, seconds)
new Date(year, monthIndex, day, hours, minutes, seconds, milliseconds)

Date()
```

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

### 参数

对于 `Date()` 构造函数，有五种基本的形式：

#### 无参数

当没有提供参数时，新创建的 `Date` 对象代表当前的日期和时间。

#### 时间或时间戳值

`value`

一个整数，代表自 UTC 1970 年 1 月 1 日 00:00:00（ECMAScript 纪元，与 UNIX 纪元相同）以来的毫秒数，忽略闰秒。请记住，大多数 UNIX 时间戳函数只精确到最近的秒。

#### 日期字符串

`dateString`

一个代表日期的字符串值，其格式由 `Date.parse()` 方法所识别。（ECMA262 规范规定了 ISO 8601 的简化版本，但其他格式可以由实现者定义，通常包括符合 IETF 的 RFC 2822 时间戳。）

**备注：** 当用 `Date` 构造函数（和 `Date.parse`，它们是等价的）解析日期字符串时，一定要确保输入符合 ISO 8601 格式（`YYYY-MM-DDTHH:mm:ss.ssZ`），其他格式的解析行为是实现定义的，可能无法在所有浏览器上运行。对 RFC 2822 格式字符串的支持只是惯例。如果要适应许多不同的格式，库可以提供帮助。

仅有日期的字符串（例如 `"1970-01-01"`）被视为 UTC，而日期时间的字符串（例如 `"1970-01-01T12:00"`）被视为本地时间。因此，我们也建议你确保这两种类型的输入格式是一致的。

#### 日期对象

`dateObject`

一个现有的 `Date` 对象。这实际上是在现有的 `Date` 对象上复制了一个相同的日期和时间。这等同于 `new Date(dateObject.valueOf())`，除了不调用 `valueOf()` 方法。

当一个参数被传递给 `Date()` 构造函数时，`Date` 实例被特别处理。所有其他的值都被转换为原始值。如果结果是一个字符串，它将被解析为一个日期字符串。否则，产生的会被进一步强制转换为数值，并被视为时间戳。

#### 日期和时间组件的单独值

给出至少一个年份和月份，这种形式的 `Date()` 返回一个 `Date` 对象，其组成部分的值（年、月、日、小时、分钟、秒和毫秒）都来自以下参数。任何缺失的字段都被赋予可能的最低值（`day` 为 `1`，其他所有组件为 `0`）。这些参数值都是根据当地的时区，而不是 UTC 来评估的。

如果任何参数超过其定义的范围，会发生“进位”。例如，如果传入一个大于 `11` 的 `monthIndex`，这些月将导致年的递增；如果传入一个大于 `59` 的 `minutes`，`hours` 将相应递增，等等。因此，`new Date(1990, 12, 1)` 将返回 1991 年 1 月 1 日；`new Date(2020, 5, 19, 25, 65)` 将返回 2020 年 6 月 20 日凌晨 2:05。

类似的，如果任何参数不足其定义的范围，会从高位“借位”。例如，`new Date(2020, 5, 0)` 将返回 2020 年 5 月 31 日。

`year`

表示年的整数。从 `0` 到 `99` 的值映射了 `1900` 到 `1999` 年。其他值对应真实的年份。参见示例。

`monthIndex`

表示月份的整数，从代表一月的 `0` 开始到代表十二月的 `11` 结束。

`day` 可选

表示一个月中第几天的整数。默认为 `1`。

`hours` 可选

表示一天中的小时数的整数值，在 `0` 到 `23` 之间。默认值为 `0`。

`minutes` 可选

表示时间的分钟段的整数值。默认为小时后的 `0` 分钟。

`seconds` 可选

表示时间的秒数段的整数值。默认为分钟后的 `0` 秒。

`milliseconds` 可选

表示时间的毫秒段的整数值。默认为 `0` 毫秒的秒数。

### 返回值

调用 `new Date()`（`Date()` 构造函数）会返回一个 `Date` 对象。如果调用无效的日期字符串，或者如果要构建的日期的 UNIX 时间戳小于 `-8,640,000,000,000` 或大于 `8,640,000,000,000` 毫秒，它会返回一个 `Date` 对象，其 `toString()` 方法返回字面量字符串 `Invalid Date`。

调用 `Date()` 函数（没有 `new` 关键字）会返回当前日期和时间的字符串表示，就像 `new Date().toString()` 那样。调用 `Date()` 函数（没有 `new` 关键字）时给出的任何参数都会被忽略；无论调用的是一个无效的日期字符串，甚至使用任何任意对象或其他原始值作为参数，它总是返回一个当前日期和时间的字符串表示。

示例
--

### 创建 Date 对象的若干方法

以下示例展示了创建 JavaScript 日期的若干方法：

```js
const today = new Date();
const birthday = new Date("December 17, 1995 03:24:00"); // 不被鼓励，可能不会在所有运行时环境起作用
const birthday = new Date("1995-12-17T03:24:00"); // 这是符合 ISO-8601 标准的，将可靠地工作
const birthday = new Date(1995, 11, 17); // 月份是以 0 为索引的
const birthday = new Date(1995, 11, 17, 3, 24, 0);
const birthday = new Date(628021800000); // 传递纪元时间戳参数
```

### 传递非日期、非字符串或非数值

如果 `Date()` 构造函数被调用时有一个参数不是 `Date` 实例，它将被强制转换为原始值，然后检查它是否是一个字符串。例如，`new Date(undefined)` 与 `new Date()` 是不同的：

```js
console.log(new Date(undefined)); // Invalid Date
```

这是因为 `undefined` 已经是一个原始类型值，但不是一个字符串，所以它将被强制转换为一个数值，也就是 `NaN`，因此不是一个有效的时间戳。另一方面，`null` 将被强制转换为 `0`。

```js
console.log(new Date(null)); // 1970-01-01T00:00:00.000Z
```

数组将通过 `Array.prototype.toString()` 转换为字符串，它用逗号连接各元素。然而，任何有一个以上元素的数组所产生的字符串都不是有效的 ISO 8601 日期字符串，所以它的解析行为将由实现定义。**不要将数组传递给 `Date()` 构造函数。**

```js
console.log(new Date(["2020-06-19", "17:13"]));
// Chrome 中会显示 2020-06-19T17:13:00.000Z，因为它可以识别 "2020-06-19,17:13" 这种形式
// Firefox 中会显示 "Invalid Date"
```

规范
--

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

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

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

参见
--

* `Date`


Date.prototype.setUTCFullYear() - JavaScript

Date.prototype.setUTCFullYear()
===============================

**`setUTCFullYear()`** 方法根据世界标准时间为一个具体日期设置年份。

尝试一下
----

语法
--
```

dateObj.setUTCFullYear(yearValue[, monthValue[, dayValue]])
```

### 参数

`yearValue`

指定年份整数值，例如，1995

`monthValue`

可选。指定一个 0-11 之间的整数值，代表从一月到十二月。

`dayValue`

可选。指定一个 1-31 之间的整数值，代表月份中的第几天。如果你指定了 dayValue 参数，那么你必须指定 monthValue 参数。

描述
--

如果你没有指定具体的 `monthValue` 和 `dayValue`，将会使用 `getUTCMonth` 和 `getUTCDate` 方法的返回值。

如果你指定的参数超出了期待范围，`setUTCFullYear()` 方法将会根据 `Date` 对象，更新其他参数和日期信息。例如，如果你将 `monthValue` 设定为 `15`，年份会增加 `1`，月份值则为为 `3`。

示例
--

### 使用 `setUTCFullYear()`

```js
var theBigDay = new Date();
theBigDay.setUTCFullYear(1997);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcfullyear |

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

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

参见
--

* `Date.prototype.getUTCFullYear()`
* `Date.prototype.setFullYear()`


Date.prototype.valueOf() - JavaScript

Date.prototype.valueOf()
========================

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

尝试一下
----

语法
--
```

dateObj.valueOf()
```

### 返回值

从 1970 年 1 月 1 日 0 时 0 分 0 秒（UTC，即协调世界时）到该日期的毫秒数。

描述
--

`valueOf` 方法返回以数值格式表示的一个 `Date` 对象的原始值，从 1970 年 1 月 1 日 0 时 0 分 0 秒（UTC，即协调世界时）到该日期对象所代表时间的毫秒数。

该方法的功能和 `Date.prototype.getTime()` 方法一样。

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

示例
--

### 使用 `valueOf()`

```js
var x = new Date(56, 6, 17);
var myVar = x.valueOf(); // assigns -424713600000 to myVar
```

规范
--

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

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

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

参见
--

* `Object.prototype.valueOf()`
* `Date.prototype.getTime()`


Date.parse() - JavaScript

Date.parse()
============

**`Date.parse()`** 方法解析一个表示某个日期的字符串，并返回从 1970-1-1 00:00:00 UTC 到该日期对象（该日期对象的 UTC 时间）的毫秒数，如果该字符串无法识别，或者一些情况下，包含了不合法的日期数值（如：2015-02-31），则返回值为 NaN。

不推荐在 ES5 之前使用 Date.parse 方法，因为字符串的解析完全取决于实现。直到至今，不同宿主在如何解析日期字符串上仍存在许多差异，因此最好还是手动解析日期字符串（在需要适应不同格式时库能起到很大帮助）。

尝试一下
----

语法
--

显式调用：

```js
Date.parse(dateString)
```

### 参数

`dateString`

一个符合 RFC2822 或 ISO 8601 日期格式的字符串（其他格式也许也支持，但结果可能与预期不符）。

### 返回值

一个表示从 1970-1-1 00:00:00 UTC 到给定日期字符串所表示时间的毫秒数的数值。如果参数不能解析为一个有效的日期，则返回`NaN`。

描述
--

`parse` 方法接受一个日期字符串（例如 "`Dec 25, 1995`"），并返回从 1970-1-1 00:00:00 UTC 到该日期字符串所表示日期的毫秒数。该方法在基于字符串值设置日期值时很有用，例如结合使用`setTime()` 方法和 `Date()` 构造函数。

`parse` 方法接受一个表示时间的字符串，返回相应的时间值。该方法可以接受符合 RFC2822 / IETF 日期语法 (RFC2822 Section 3.3) 的字符串，如 "`Mon, 25 Dec 1995 13:30:00 GMT`"。该方法能够理解美国大陆时区的缩写，但是为了更通用，应该使用时区偏移，如 "`Mon, 25 Dec 1995 13:30:00 +0430`"（格林威治的子午线向东偏移 4 小时 30 分钟）。如果没有指定时区，默认使用本地时区。

GMT 和 UTC 被看作相等。如果 RFC2822 Section 3.3 格式中不包含时区信息时，会以本地时区来解析日期字符串。

由于在解析日期字符串时存在偏差会导致结果不一致，因此推荐始终手动解析日期字符串，特别是不同的 ECMAScript 实现会把诸如“2015-10-12 12:00:00”的字符串解析为 NaN，UTC 或者本地时间。

### ECMAScript 5 ISO-8601 日期格式支持

另外，日期时间字符串也可以使用 ISO 8601 格式。例如，"`2011-10-10`"（仅日期）或 "`2011-10-10T14:48:00`"（日期和时间）能够作为参数被传递和解析。如果参数字符串只包含日期格式，那么将会使用 UTC 时区来解析该参数。而如果是ISO 8601 格式中规定的时间加日期的格式，则将会被作为本地时区处理。

虽然在日期字符串解析过程中会使用时区修饰符，但返回值总会是从由 NaN 表示的 1970-1-1 00:00:00 UTC 到该日期字符串所表示日期的毫秒数。

由于 `parse()` 是 `Date` 的一个静态方法 , 所以应该使用 `Date.parse()` 来调用，而不是作为 `Date` 的实例方法。

### 默认时区的区别

当输入为 "`March 7, 2014`" 时， `parse()` 将默认使用本地时区。但如果使用 ISO 格式如 `"2014-03-07"` ，则会被默认为 UTC (ES5 和 ECMAScript 2015) 时区。因此除非系统本地时区为 UTC，由这些字符串解析出的 `Date` 对象可能会因为 ECMAScript 版本不同而代表不同的时间。这意味着两个看起来等效的字符串可能因为它们的格式不同而被转换成不同的值。

### 引擎相关的日期格式

ECMAScript 规范规定：如果一个字符串不符合标准格式，则函数可以使用任何由引擎决定的策略或解析算法。 `Date.parse()` 对于因包含有无效元素而无法识别的 ISO 格式字符串或者日期应该返回 `NaN` 。

但是，在如 ECMA-262 规范中定义的情况，如果因为无效值而导致日期字符串不能被识别为 ISO 格式时，根据浏览器和给定的值不同，返回值可以是，也可以不是 `NaN` 。比如：

```js
// 包含无效值的非 ISO 格式字符串
new Date("23/25/2014");
```

在 Firefox 30 中会被识别为本地时区的 2015 年 12 月 25 日，而在 Safari 7 中则是无效日期。但是，如果字符串被识别为 ISO 格式并且包含无效值，则在所有遵循 ES5 或者更新标准的浏览器中都会返回 `NaN` 。

```js
// 包含无效值的 ISO 格式字符串
new Date("2014-25-23").toISOString();
// 在所有遵循 ES5 的浏览器中返回 "RangeError: invalid date"
```

SpiderMonkey 的引擎策略可以在 `jsdate.cpp` 中找到。字符串 `"10 06 2014"` 可以作为非 ISO 格式字符串使用自定义处理方式的例子。参见这篇关于解析如何进行的粗略纲要。

```js
new Date("10 06 2014");
```

将会被解析为本地时间 2014 年 10 月 6 日，而不是 6 月 10 日。另一个例子

```js
new Date("foo-bar 2014").toString();
// 返回："Invalid Date"

Date.parse("foo-bar 2014");
// 返回：NaN
```

示例
--

### 示例：使用 `Date.parse()`

如果 `IPOdate` 是一个已经存在的 `Date` 对象，则可以把其设置为本地时间 1995 年 8 月 9 日。如下：

```js
IPOdate.setTime(Date.parse("Aug 9, 1995"));
```

其他一些解析非标准格式日期的例子：

```js
Date.parse("Aug 9, 1995");
```

在时区 GMT-0300 中返回 807937200000，在其他时区中返回另外的值，因为未指定时区并且不是 ISO 格式，所以默认使用本地时区。

```js
Date.parse("Wed, 09 Aug 1995 00:00:00 GMT");
```

因为指定了时区 GMT (UTC)，所以不管本地时区如何，总是返回 `807926400000` 。

```js
Date.parse("Wed, 09 Aug 1995 00:00:00");
```

在时区 GMT-0300 中返回 807937200000，在其他时区中返回另外的值，因为没有时区标志并且不是 ISO 格式，所以作为本地时区处理。

```js
Date.parse("Thu, 01 Jan 1970 00:00:00 GMT");
```

因为指定了时区 GMT (UTC)，所以不管本地时区如何，总是返回 `0` 。

```js
Date.parse("Thu, 01 Jan 1970 00:00:00");
```

在时区 GMT-0400 中返回 `14400000`，在其他时区中返回另外的值，因为未指定时区并且不是 ISO 格式，所以使用本地时区处理。

```js
Date.parse("Thu, 01 Jan 1970 00:00:00 GMT-0400");
```

因为指定了时区 GMT (UTC)，所以不管本地时区如何，总是返回 `14400000` 。

规范
--

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

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

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

参见
--

* `Date.UTC()`


Date.prototype.getDate() - JavaScript

Date.prototype.getDate()
========================

根据本地时间，返回一个指定的日期对象为一个月中的哪一日（从 1--31）。

尝试一下
----

语法
--

```js
getDate()
```

参数
--

无

描述
--

`getDate()` 返回一个 1 到 31 的整数值。

示例
--

### 示例：使用 `getDate()` 方法

下面第二条语句将值 25 赋给 day 变量，该值基于日期对象 `Xmax95`的值。

```js
var Xmas95 = new Date("December 25, 1995 23:15:00");
var day = Xmas95.getDate();

alert(day); // 25
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getdate |

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

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

参见
--

* `Date.prototype.getUTCDate()`
* `Date.prototype.getUTCDay()`
* `Date.prototype.setDate()`


Date.prototype.getTimezoneOffset() - JavaScript

Date.prototype.getTimezoneOffset()
==================================

**`getTimezoneOffset()`** 方法返回协调世界时（UTC）相对于当前时区的时间差值，单位为分钟。

尝试一下
----

语法
--

```js
getTimezoneOffset()
```

### 参数

无

### 返回值

时区偏差（time-zone offset）表示协调世界时（UTC）与本地时区之间的差值，单位为分钟。需要注意的是如果本地时区后于协调世界时，则该差值为正值，如果先于协调世界时则为负值。例如你所在时区为 UTC+10（澳大利亚东部标准时间），将会返回 -600。对于同一个时区，夏令时（Daylight Saving Time）将会改变这个值。

示例
--

### 示例：使用 `getTimezoneOffset` 方法

```js
var x = new Date();
var currentTimeZoneOffsetInHours = x.getTimezoneOffset() / 60;
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.gettimezoneoffset |

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

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


Date.prototype.toLocaleString() - JavaScript

Date.prototype.toLocaleString()
===============================

**`toLocaleString()`** 方法返回该日期对象的字符串，该字符串格式因不同语言而不同。在支持 `Intl.DateTimeFormat` API 的实现中，该方法仅是调用了 `Intl.DateTimeFormat` 方法。

尝试一下
----

语法
--

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

### 参数

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

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

`locales` 可选

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

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

`options` 可选

一个调整输出格式的对象。对应于 `Intl.DateTimeFormat()` 构造函数的 `options` (en-US) 参数。如果其 `dayPeriod`、`hour`、`minute`、`second` 和 `fractionalSecondDigits` 属性全是 undefined，则 `hour`、`minute`、`second` 这三个属性会被设置为 `"numeric"`。

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

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

### 返回值

一个表示给定的 date 对象，且与语言相关的字符串。

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

**备注：** 大多数时候，`toLocaleString()` 返回的格式是一致的。但是，这可能在未来发生变化，且不能保证所有语言都能得到一致的格式。输出的变化因实现而异，而且这种变化是规范所允许的。你不应该将 `toLocaleString()` 的结果与静态值作比较。

示例
--

### 使用 toLocaleString()

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

```js
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

// toLocaleString() 不包含参数，其默认区域和时区取决于实现
console.log(date.toLocaleString());
// "2012/12/12 11:00:00" 如果在 zh-CN 区域以及东八区（北京时间）下运行
```

### 检测 locales 和 options 参数支持情况

`locales` 和 `options` 参数不是所有的浏览器都支持。为了检测一种实现环境（implementation）是否支持它们，可以使用不合法的语言标签，如果实现环境支持该参数，则会抛出 `RangeError` 异常，反之会忽略参数。

```js
function toLocaleStringSupportsLocales() {
  try {
    new Date().toLocaleString("i");
  } catch (e) {
    return e.name === "RangeError";
  }
  return false;
}
```

### 使用 locales

下例展示了本地化日期格式的一些变化。为了在应用的用户界面得到某种语言的日期和时间格式，必须确保使用 `locales` 参数指定了该语言（可能还需要设置某些回退语言）。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 以下格式化输出均假设使用区域的本地时区；
// 对于美国，为 America/Los\_Angeles

// 美式英语，使用 month-day-year 的顺序以及带有 AM/PM 的 12 小时制
console.log(date.toLocaleString("en-US"));
// "12/19/2012, 7:00:00 PM"

// 英式英语，使用 day-month-year 的顺序以及不带有 AM/PM 的 24 小时制
console.log(date.toLocaleString("en-GB"));
// "20/12/2012 03:00:00"

// 韩国，使用 year-month-day 的顺序以及带有 AM/PM 的 12 小时制
console.log(date.toLocaleString("ko-KR"));
// "2012. 12. 20. 오후 12:00:00"

// 大多数阿拉伯国家使用真正的阿拉伯数字
console.log(date.toLocaleString("ar-EG"));
// "٢٠/١٢/٢٠١٢ ٥:٠٠:٠٠ ص"

// 对于日语，应用倾向于使用日本的和历，
// 2012 年是平成时代的第 24 年
console.log(date.toLocaleString("ja-JP-u-ca-japanese"));
// "24/12/20 12:00:00"

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

### 使用 options

可以使用 `options` 参数来自定义 `toLocaleString()` 方法返回的字符串。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 请求参数包含星期，且该参数的值为长整型
const options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};

console.log(date.toLocaleString("de-DE", options));
// "Donnerstag, 20. Dezember 2012"

// 应用程序可能想要使用 UTC 时间，并使其可见
options.timeZone = "UTC";
options.timeZoneName = "short";

console.log(date.toLocaleString("en-US", options));
// "Thursday, December 20, 2012, GMT"

// 有时，区域设置为美国的情况下，也需要使用 24 小时制
console.log(date.toLocaleString("en-US", { hour12: false }));
// "12/19/2012, 19:00:00"
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tolocalestring |
| ECMAScript Internationalization API Specification # sup-date.prototype.tolocalestring |

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

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

参见
--

* `Intl.DateTimeFormat`
* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toLocaleTimeString()`
* `Date.prototype.toString()`


Date.prototype.getUTCSeconds() - JavaScript

Date.prototype.getUTCSeconds()
==============================

**`getUTCSeconds()`** 方法以世界时为标准，返回一个指定的日期对象的秒数。

尝试一下
----

语法
--
```

dateObj.getUTCSeconds()
```

### 参数

无。

### 返回值

`getUTCSeconds()` 返回一个 0 到 59 的整数。

示例
--

### 示例：使用 `getUTCSeconds()` 方法

下例将当前时间的秒数部分赋值给变量 `seconds`。

```js
var today = new Date();
var seconds = today.getUTCSeconds();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcseconds |

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

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

参见
--

* `Date.prototype.getSeconds()`
* `Date.prototype.setUTCSeconds()`


Date.prototype.getMonth() - JavaScript

Date.prototype.getMonth()
=========================

**`getMonth()`** 方法根据本地时间，返回一个指定的日期对象的月份，为基于 0 的值（0 表示一年中的第一月）。

尝试一下
----

语法
--

```js
getMonth()
```

### 参数

无

### 返回值

`getMonth`返回一个 0 到 11 的整数值：0 代表一月份，1 代表二月份，2 代表三月份，依次类推。

示例
--

### 使用 `getMonth()`

下面第二条语句，基于 `Date` 对象 Xmas95 的值，把 11 赋值给变量 `month`。

```js
var Xmas95 = new Date("December 25, 1995 23:15:30");
var month = Xmas95.getMonth();

console.log(month); // 11
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getmonth |

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

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

参见
--

* `Date.prototype.getUTCMonth()`
* `Date.prototype.setMonth()`


Date.prototype.getUTCDay() - JavaScript

Date.prototype.getUTCDay()
==========================

**`getUTCDay()`** 方法以世界时为标准，返回一个指定的日期对象为一星期中的第几天，其中 0 代表星期天。

尝试一下
----

语法
--
```

dateObj.getUTCDay()
```

### 参数

无。

### 返回值

`getUTCDay()` 方法返回一个对应一星期中第几天的整数：0 代表星期天，1 代表星期一，2 代表星期二，依次类推。

示例
--

### 示例：使用 `getUTCDay()` 方法

下面的例子是把当前日期的星期部分赋值给变量 `weekday`。

```js
var today = new Date();
var weekday = today.getUTCDay();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcday |

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

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

参见
--

* `Date.prototype.getUTCDate()`
* `Date.prototype.getDay()`
* `Date.prototype.setUTCDate()`


Date.prototype.setSeconds() - JavaScript

Date.prototype.setSeconds()
===========================

**`setSeconds()`** 方法根据本地时间设置一个日期对象的秒数。

尝试一下
----

语法
--
```

dateObj.setSeconds(secondsValue[, msValue])
```

### JavaScript 1.3 之前版本
```

dateObj.setSeconds(secondsValue)
```

### 参数

`secondsValue`

一个 0 到 59 的整数。

`msValue`

一个 0 到 999 的数字，表示微秒数。

描述
--

如果没有指定 `msValue` 参数，就会使用 `getMilliseconds()` 方法的返回值。

如果一个参数超出了合理范围， `setSeconds` 方法会相应地更新日期对象的时间信息。例如，为 `secondsValue` 指定 100，则日期对象的分钟数会相应地加 1，秒数将会使用 40。

示例
--

### 示例：使用`setSeconds` 方法

```js
var theBigDay = new Date();
theBigDay.setSeconds(30);
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setseconds |

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

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

参见
--

* `Date.prototype.getSeconds()`
* `Date.prototype.setUTCSeconds()`


Date.prototype.getUTCHours() - JavaScript

Date.prototype.getUTCHours()
============================

**`getUTCHours()`** 方法以世界时为标准，返回一个指定的日期对象的小时数。

尝试一下
----

语法
--
```

dateObj.getUTCHours()
```

### 参数

无。

### 返回值

`getUTCHours()` 返回一个 0 到 23 的整数。

示例
--

### 示例：使用 `getUTCHours()` 方法

下例将当前时间的小时部分赋值给变量 `hours`。

```js
var today = new Date();
var hours = today.getUTCHours();
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutchours |

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

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

参见
--

* `Date.prototype.getHours()`
* `Date.prototype.setUTCHours()`


Date.prototype.toDateString() - JavaScript

Date.prototype.toDateString()
=============================

**`toDateString()`** 方法以美式英语和人类易读的形式返回一个日期对象日期部分的字符串。

尝试一下
----

语法
--
```

dateObj.toDateString()
```

描述
--

`Date` 对象实例引用一个具体的时间点。调用 `toString` 方法会以美式英语和人类易读的形式返回日期对象的格式化字符串。在 SpiderMonkey 里，该字符串由日期部分（年月日）和其后的时间部分（时分秒及时区）组成。有时需要获取日期部分的字符串，这可以由 `toDateString` 方法完成。

The `toDateString` method is especially useful because compliant engines implementing ECMA-262 (en-US) may differ in the string obtained from `toString` for `Date` objects, as the format is implementation-dependent and simple string slicing approaches may not produce consistent results across multiple engines.

示例
--

### 示例：`toDateString` 方法的简单使用

```js
var d = new Date(1993, 6, 28, 14, 39, 7);

println(d.toString()); // prints Wed Jul 28 1993 14:39:07 GMT-0600 (PDT)
println(d.toDateString()); // prints Wed Jul 28 1993
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.todatestring |

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

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

参见
--

* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toTimeString()`
* `Date.prototype.toString()`


Date.prototype.toJSON() - JavaScript

Date.prototype.toJSON()
=======================

**`toJSON()`** 方法返回 `Date` 对象的字符串形式。

尝试一下
----

语法
--

```js
toJSON()
```

描述
--

`Date` 实例引用一个具体的时间点。调用 `toJSON()` 返回一个 JSON 格式字符串（使用 `toISOString()`），表示该日期对象的值。默认情况下，这个方法常用于 JSON 序列化 `Date` 对象。

示例
--

### 使用 toJSON()

```js
const jsonDate = new Date(0).toJSON(); // '1970-01-01T00:00:00.000Z'
const backToDate = new Date(jsonDate);

console.log(jsonDate); // 1970-01-01T00:00:00.000Z
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tojson |

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

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

参见
--

* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toTimeString()`
* `Date.prototype.toUTCString()`


Number.prototype.toString() - JavaScript

Number.prototype.toString()
===========================

`Number` 值的 **`toString()`** 方法返回表示该数字值的字符串。

尝试一下
----

语法
--

```js
toString()
toString(radix)
```

### 参数

`radix` 可选

一个整数，范围在 `2` 到 `36` 之间，用于指定表示数字值的基数。默认为 10。

### 返回值

一个表示指定数字值的字符串。

### 异常

`RangeError`

如果 `radix` 小于 2 或大于 36，则抛出该异常。

描述
--

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

对于 10 以上的基数，字母表示大于 9 的数字。例如，对于十六进制数（基数为 16），`a` 到 `f` 用于表示大于 9 的数字。

如果指定的值为负数，则符号会被保留。即使基数为 2，也是如此；返回的字符串是带有 `-` 符号的正数二进制表示，而**不是**数字值的补码表示。

`0` 和 `-0` 都以 `"0"` 作为其字符串表示。`Infinity` 返回 `"Infinity"`，而 `NaN` 返回 `"NaN"`。

如果该数字不是一个整数，则使用小数点 `.` 来分隔小数部分。如果基数为 10，并且数字的大小（忽略符号）大于或等于 1021 或小于 10-6，则使用科学计数法。在这种情况下，返回的字符串总是显式地指定了指数的符号。

```js
console.log((10 \*\* 21.5).toString()); // "3.1622776601683794e+21"
console.log((10 \*\* 21.5).toString(8)); // "526665530627250154000000"
```

`toString` 方法要求 `this` 值是 `Number` 原始值或包装对象。对于其他 `this` 值，不会尝试将它们转换为数字值，而是抛出 `TypeError`。

因为 `Number` 没有 `[@@toPrimitive]()` 方法，当一个 `Number` *对象*在一个期望字符串的上下文中使用时（比如在模板字符串中），JavaScript 会自动调用 `toString()` 方法。然而，`Number` *原始值*不会使用 `toString()` 方法来进行字符串强制转换——相反，它们会直接使用与 `toString()` 初始实现的相同算法进行转换。

```js
Number.prototype.toString = () => "重写了";
console.log(`${1}`); // "1"
console.log(`${new Number(1)}`); // "重写了"
```

示例
--

### 使用 toString()

```js
const count = 10;
console.log(count.toString()); // "10"

console.log((17).toString()); // "17"
console.log((17.2).toString()); // "17.2"

const x = 6;
console.log(x.toString(2)); // "110"
console.log((254).toString(16)); // "fe"
console.log((-10).toString(2)); // "-1010"
console.log((-0xff).toString(2)); // "-11111111"
```

### 转换数字字符串的基数

如果你有一个非十进制的数字的字符串，可以使用 `parseInt()` 和 `toString()` 将其转换为不同的基数。

```js
const hex = "CAFEBABE";
const bin = parseInt(hex, 16).toString(2); // "11001010111111101011101010111110"
```

注意精度损失：如果原始数字字符串太大（比如大于 `Number.MAX_SAFE_INTEGER` ），则应使用 `BigInt` 来替代。然而，`BigInt` 的构造函数仅支持表示数字字面量的字符串（即以 `0b`、`0o` 或 `0x` 开头的字符串）。如果原始基数不是二进制、八进制、十进制或十六进制，则可能需要手工编写基数转换器，或者使用库。

规范
--

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

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

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

参见
--

* `Number.prototype.toFixed()`
* `Number.prototype.toExponential()`
* `Number.prototype.toPrecision()`


Number.EPSILON - JavaScript

Number.EPSILON
==============

**`Number.EPSILON`** 静态数据属性表示 1 与大于 1 的最小浮点数之间的差值。

尝试一下
----

值
-

2-52，或大约 `2.2204460492503130808472633361816E-16`。

| `Number.EPSILON` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |

描述
--

`Number.EPSILON` 是数字中 1 和可表示的比 1 大的最小数字之间的差值，因为双精度浮点格式只有 52 位来表示尾数，并且最低位的有效值为 2-52。

请注意，浮点数的绝对精度随着数字变大而降低，因为指数增长而尾数的精度保持不变。`Number.MIN_VALUE` 是可表示的最小正数，远小于 `Number.EPSILON`。

由于 `EPSILON` 是 `Number` 的静态属性，因此你应该始终将其用作 `Number.EPSILON`，而不是作为数字值的属性。

示例
--

### 相等测试

任何占用位数有限的数字编码系统，无论你选择的是什么基数（例如十进制或二进制），都*必定*无法精确表示所有数字，因为你试图使用有限的内存来表示数轴上无限数量的点。例如，十进制系统无法准确表示 1/3，而二进制系统无法准确表示 `0.1`。因此，例如，`0.1 + 0.2` 并不完全等于 `0.3`：

```js
console.log(0.1 + 0.2); // 0.30000000000000004
console.log(0.1 + 0.2 === 0.3); // false
```

因此，通常建议**不要使用 `===` 比较浮点数**。相反，我们可以认为两个数在彼此之间是*足够接近*的时候它们是相等的。如果算术运算的数量级在 `1` 附近，那么 `Number.EPSILON` 常数通常是一个合理的误差阈值，因为实质上，`EPSILON` 指定了数字“1”的精确度。

```js
function equal(x, y) {
  return Math.abs(x - y) < Number.EPSILON;
}

const x = 0.2;
const y = 0.3;
const z = 0.1;
console.log(equal(x + z, y)); // true
```

然而，对于任何具有更大数量级的算术运算，`Number.EPSILON` 是不适用的。如果你的数据数量级在 103 的范围，那么小数部分的精确度将远远小于`Number.EPSILON`：

```js
function equal(x, y) {
  return Math.abs(x - y) < Number.EPSILON;
}

const x = 1000.1;
const y = 1000.2;
const z = 2000.3;
console.log(x + y); // 2000.3000000000002；误差为 10^-13 而不是 10^-16
console.log(equal(x + y, z)); // false
```

在这种情况下，需要更大的容差。由于进行比较的数字的数量级大约为 `2000`，使用类似于 `2000 * Number.EPSILON` 的乘积可以为此情况提供足够的容差。

```js
function equal(x, y, tolerance = Number.EPSILON) {
  return Math.abs(x - y) < tolerance;
}

const x = 1000.1;
const y = 1000.2;
const z = 2000.3;
console.log(equal(x + y, z, 2000 \* Number.EPSILON)); // true
```

除了数量级之外，考虑输入的*精度*也非常重要。例如，如果数字是从表单输入收集的，并且输入值只能以 `0.1` 的步长调整（即 `<input type="number" step="0.1">` (en-US)），通常可以允许更大的容差，例如 `0.01`，因为数据的精度只有 `0.1`。

**备注：** 重点是：不要简单地将 `Number.EPSILON` 作为相等性测试的阈值。使用适合要比较的数字的数量级和精度的阈值。

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.epsilon |

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

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

参见
--

* `core-js` 中 `Number.EPSILON` 的 polyfill
* `Number`


Number.parseInt() - JavaScript

Number.parseInt()
=================

**`Number.parseInt()`** 静态方法解析一个字符串参数并返回一个指定基数的整数。

尝试一下
----

语法
--

```js
Number.parseInt(string)
Number.parseInt(string, radix)
```

### 参数

`string`

要被解析的值，会被强制转化为字符串。字符串开头的空白符将会被忽略。

`radix` 可选

`2` 到 `36` 之间的整数，表示 `string` 的*基数*（数学记数系统中的基）。

如果 `radix` 为 `undefined` 或 `0`，则 `radix` 将被默认设置为 `10`，除非该数字以码元对 `0x` 或 `0X` 开头，在这种情况下，`radix` 将被默认设置为 `16`。

### 返回值

从给定的 `string` 中解析出的一个整数。

如果 `radix` 小于 `2` 或大于 `36`，或第一个非空白字符不能转换为数字，则返回 `NaN`。

示例
--

### Number.parseInt 与 parseInt 对比

这个方法和全局的 `parseInt()` 函数具有相同的功能：

```js
Number.parseInt === parseInt; // true
```

其目的是对全局变量进行模块化，另见 `parseInt()` 获取更多详情和示例。

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.parseint |

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

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

参见
--

* `core-js` 中 `Number.parseInt` 的 polyfill
* `Number`
* `parseInt()`


Number.isNaN() - JavaScript

Number.isNaN()
==============

**`Number.isNaN()`** 静态方法判断传入的值是否为 `NaN`，如果输入不是数字类型，则返回 `false`。它是全局 `isNaN()` 函数更健壮的版本。

尝试一下
----

语法
--

```js
Number.isNaN(value)
```

### 参数

`value`

要测试是否为 `NaN` 的值。

### 返回值

如果给定值是一个值为 `NaN` 的数字，则返回布尔值 `true`，否则返回 `false`。

描述
--

函数 `Number.isNaN()` 提供了一种方便的方法来检查值是否与 `NaN` 相等。请注意，你不能使用 `==` 或 `===` 运算符来测试值与 `NaN` 的相等性，因为与 JavaScript 中的其他值的比较不同，这些运算符在一个操作数为 `NaN` 时始终返回 `false`，即使另一个操作数也是 `NaN`。

由于在所有可能的 JavaScript 值中，`x !== x` 只有对于 `NaN` 才为真，因此 `Number.isNaN(x)` 也可以替换为 `x !== x`，尽管后者可读性较差。

与全局的 `isNaN()` 函数相反，`Number.isNaN()` 方法不会将参数强制转换为数字。这样可以安全地传入通常会转换为 `NaN` 但实际上与 `NaN` 不同的值。这也意味着只有等于 `NaN` 的 Number 类型的值才会返回 `true`。

示例
--

### 使用 isNaN()

```js
Number.isNaN(NaN); // true
Number.isNaN(Number.NaN); // true
Number.isNaN(0 / 0); // true
Number.isNaN(37); // false
```

### Number.isNaN() 和全局 isNaN() 之间的区别

`Number.isNaN()` 不会尝试将参数转换为数字，因此非数字总是返回 `false`。以下都返回 `false`：

```js
Number.isNaN("NaN");
Number.isNaN(undefined);
Number.isNaN({});
Number.isNaN("blabla");
Number.isNaN(true);
Number.isNaN(null);
Number.isNaN("37");
Number.isNaN("37.37");
Number.isNaN("");
Number.isNaN(" ");
```

全局 `isNaN()` 函数会将参数强制转换为数字：

```js
isNaN("NaN"); // true
isNaN(undefined); // true
isNaN({}); // true
isNaN("blabla"); // true
isNaN(true); // false，强制转换为 1
isNaN(null); // false，强制转换为 0
isNaN("37"); // false，强制转换为 37
isNaN("37.37"); // false，强制转换为 37.37
isNaN(""); // false，强制转换为 0
isNaN(" "); // false，强制转换为 0
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.isnan |

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

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

参见
--

* `core-js` 中 `Number.isNaN` 的 polyfill
* `Number`
* `isNaN()`


Number.isInteger() - JavaScript

Number.isInteger()
==================

**`Number.isInteger()`** 静态方法判断传入值是否为整数。

尝试一下
----

语法
--

```js
Number.isInteger(value)
```

### 参数

`value`

要测试是否为整数的值。

### 返回值

如果给定值是整数，则返回布尔值 `true`。否则为 `false`。

描述
--

如果目标值是一个整数，返回 `true`，否则返回 `false`。如果该值是 `NaN` 或者 `Infinity`，返回 `false`。对于可以表示为整数的浮点数，该方法也将返回 `true`。如果该值不是一个数字，该方法将始终返回 `false`。

请注意，一些数字字面量看起来像是非整数，但实际上却表示整数。这是由于 ECMAScript 浮点数编码（IEEE-754）的精度限制。例如，`5.0000000000000001` 只与 `5` 相差 `1e-16`，这个差值太小了而无法表示。（作为参考，`Number.EPSILON` 存储 1 与大于 1 的下一个可表示的浮点数之间的距离，大约为 `2.22e-16`。）因此，`5.0000000000000001` 将使用与 `5` 相同的编码表示，从而使得 `Number.isInteger(5.0000000000000001)` 返回 `true`。

在类似的意义上，接近 `Number.MAX_SAFE_INTEGER` 大小的数值会因精度损失而使得 `Number.isInteger` 在传入值实际上不是整数的情况下返回 `true`。（实际阈值根据需要表示小数所需的位数而变化——例如，`Number.isInteger(4500000000000000.1)` 为 `true`，但 `Number.isInteger(4500000000000000.5)` 为 `false`。）

示例
--

### 使用 isInteger

```js
Number.isInteger(0); // true
Number.isInteger(1); // true
Number.isInteger(-100000); // true
Number.isInteger(99999999999999999999999); // true

Number.isInteger(0.1); // false
Number.isInteger(Math.PI); // false

Number.isInteger(NaN); // false
Number.isInteger(Infinity); // false
Number.isInteger(-Infinity); // false
Number.isInteger("10"); // false
Number.isInteger(true); // false
Number.isInteger(false); // false
Number.isInteger([1]); // false

Number.isInteger(5.0); // true
Number.isInteger(5.000000000000001); // false
Number.isInteger(5.0000000000000001); // true，因为精度损失
Number.isInteger(4500000000000000.1); // true，因为精度损失
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.isinteger |

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

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

参见
--

* `core-js` 中 `Number.isInteger` 的 polyfill
* `Number`


Number.prototype.toExponential() - JavaScript

Number.prototype.toExponential()
================================

`Number` 值的 **`toExponential()`** 方法返回一个以指数表示法表示该数字的字符串。

尝试一下
----

语法
--

```js
toExponential()
toExponential(fractionDigits)
```

### 参数

`fractionDigits` 可选

可选。一个整数，用来指定小数点后有几位数字。默认设置为完整表示该数字所需要的数字。

### 返回值

一个以指数表示法表示给定 `Number` 对象的的字符串，其小数点前为一位数字，小数点后舍入到 `fractionDigits` 位。

### 异常

`RangeError`

如果 `fractionDigits` 不是介于 `0` 和 `100` 之间（包含两端）的整数，则抛出该错误。

`TypeError`

如果在非 `Number` 对象上调用该方法，则抛出该错误。

描述
--

如果省略了 `fractionDigits` 参数，则小数点后的位数默认为精确表示该值的所需的位数。

如果你为一个没有指数也没有小数点的数字字面量使用 `toExponential()` 方法。请在方法调用之前的点之前留出空格，以防止该点被解释为小数点。

如果一个数字的位数比 `fractionDigits` 参数指定的位数更多，则该数字将被舍入为最接近的数字，请参阅 `toFixed()` 方法的描述中关于舍入的讨论，这也适用于 `toExponential()`。

示例
--

### 使用 toExponential

```js
const numObj = 77.1234;

console.log(numObj.toExponential()); // 7.71234e+1
console.log(numObj.toExponential(4)); // 7.7123e+1
console.log(numObj.toExponential(2)); // 7.71e+1
console.log((77.1234).toExponential()); // 7.71234e+1
console.log((77).toExponential()); // 7.7e+1
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.toexponential |

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

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

参见
--

* `core-js` 中 `Number.prototype.toExponential` 的 polyfill，并对此方法进行了修复
* `Number.prototype.toFixed()`
* `Number.prototype.toPrecision()`
* `Number.prototype.toString()`


Number.parseFloat() - JavaScript

Number.parseFloat()
===================

**`Number.parseFloat()`** 静态方法解析参数并返回浮点数。如果无法从参数中解析出一个数字，则返回 `NaN`。

尝试一下
----

语法
--

```js
Number.parseFloat(string)
```

### 参数

`string`

要解析的值，会被强制转换为字符串。该参数开头的空白会被忽略。

### 返回值

由给定 `string` 解析得到的浮点数。

如果第一个非空白字符不能被转换为数字，则返回 `NaN`。

示例
--

### Number.parseFloat 与 parseFloat 对比

此方法与全局函数 `parseFloat()` 具有相同的功能：

```js
Number.parseFloat === parseFloat; // true
```

其目的是全局的模块化。

有关更多详细信息和示例，请参见 `parseFloat()`。

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.parsefloat |

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

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

参见
--

* `core-js` 中 `Number.parseFloat` 的 polyfill
* `Number`
* `parseFloat()`


Number.MAX_VALUE - JavaScript

Number.MAX\_VALUE
=================

**`Number.MAX_VALUE`** 静态数据属性表示在 JavaScript 中可表示的最大数值。

尝试一下
----

值
-

21024 - 1，或大约 `1.7976931348623157E+308`。

| `Number.MAX_VALUE` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |

描述
--

大于 `MAX_VALUE` 的值表示为 `Infinity` 并将丢失其实际值。

由于 `MAX_VALUE` 是 `Number` 对象的静态属性，你应该始终将其用作 `Number.MAX_VALUE`，而不是作为一个数字值的属性。

示例
--

### 使用 MAX\_VALUE

下面的代码对两个数值进行乘法运算。如果结果小于或等于 `MAX_VALUE`，则调用函数 `func1`；否则，调用函数 `func2`。

```js
if (num1 \* num2 <= Number.MAX\_VALUE) {
  func1();
} else {
  func2();
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.max\_value |

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

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

参见
--

* `Number.MIN_VALUE`
* `Number`


Number.MAX_SAFE_INTEGER - JavaScript

Number.MAX\_SAFE\_INTEGER
=========================

**`Number.MAX_SAFE_INTEGER`** 静态数据属性表示在 JavaScript 中最大的安全整数（253 – 1）。

对于更大的整数，请考虑使用 `BigInt`。

尝试一下
----

值
-

`9007199254740991`（9,007,199,254,740,991，或者约 9 千万亿）。

| `Number.MAX_SAFE_INTEGER` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |

描述
--

双精度浮点格式只有 52 位用于表示尾数，因此它只能安全地表示介于 -(253 – 1) 和 253 – 1 之间的整数。本文中，“安全”指的是能够精确表示整数并正确比较它们。例如，`Number.MAX_SAFE_INTEGER + 1 === Number.MAX_SAFE_INTEGER + 2` 的结果将为真，这在数学上是不正确的。有关更多信息，请参阅 `Number.isSafeInteger()`。

由于 `MAX_SAFE_INTEGER` 是 `Number` 的静态属性，你应该始终将其使用为 `Number.MAX_SAFE_INTEGER`，而不是一个数字值的属性。

示例
--

### MAX\_SAFE\_INTEGER 的返回值

```js
Number.MAX\_SAFE\_INTEGER; // 9007199254740991
```

### MAX\_SAFE\_INTEGER 和 EPSILON 之间的关系

`Number.EPSILON` 是 2-52，而 `MAX_SAFE_INTEGER` 是 253 – 1，它们都源自尾数的宽度，即 53 位（最高位始终为 1）。将它们相乘会得到一个非常接近但不等于 2 的值。

```js
Number.MAX\_SAFE\_INTEGER \* Number.EPSILON; // 1.9999999999999998
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.max\_safe\_integer |

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

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

参见
--

* `core-js` 中 `Number.MAX_SAFE_INTEGER` 的 polyfill
* `Number.MIN_SAFE_INTEGER`
* `Number.isSafeInteger()`
* `BigInt`


Number.NaN - JavaScript

Number.NaN
==========

**`Number.NaN`** 静态数据属性表示非数字值，等同于 `NaN`。有关 `NaN` 的行为的更多信息，请参阅全局属性的描述。

尝试一下
----

值
-

数字值 `NaN`。

| `Number.NaN` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |

描述
--

由于 `NaN` 是 `Number` 的静态属性，你应该始终将其用作 `Number.NaN`，而不是作为一个数字值的属性。

示例
--

### 检查值是否为数字

```js
function sanitize(x) {
  if (isNaN(x)) {
    return Number.NaN;
  }
  return x;
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.nan |

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

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

参见
--

* `NaN`
* `Number.isNaN()`


Number.POSITIVE_INFINITY - JavaScript

Number.POSITIVE\_INFINITY
=========================

**`Number.POSITIVE_INFINITY`** 静态数据属性表示正无穷大值。

尝试一下
----

值
-

与全局属性 `Infinity` 的值相同。

| `Number.POSITIVE_INFINITY` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |

描述
--

`Number.POSITIVE_INFINITY` 的表现同数学上的无穷大略有不同：

* 任何正值，包括 `POSITIVE_INFINITY`，乘以 `POSITIVE_INFINITY` 等于 `POSITIVE_INFINITY`。
* 任何负值，包括 `NEGATIVE_INFINITY`，除以 `POSITIVE_INFINITY` 等于 `NEGATIVE_INFINITY`。
* 任何正数除以 `POSITIVE_INFINITY` 都是正零（正如 IEEE 754 中所定义的）。
* 任何负数除以 `POSITIVE_INFINITY` 都是负零（正如 IEEE 754 中所定义的）。
* 零乘以 `POSITIVE_INFINITY` 等于 `NaN`。
* `NaN` 乘以 `POSITIVE_INFINITY` 等于 `NaN`。
* `POSITIVE_INFINITY`，除以任何负值（除了 `NEGATIVE_INFINITY`）都等于 `NEGATIVE_INFINITY`。
* `POSITIVE_INFINITY`，除以任何正值（除了 `POSITIVE_INFINITY`）都等于 `POSITIVE_INFINITY`。
* `POSITIVE_INFINITY`，除以 `NEGATIVE_INFINITY` 或 `POSITIVE_INFINITY`，都等于 `NaN`。
* `Number.POSITIVE_INFINITY > x` 对于任何不是 `POSITIVE_INFINITY` 的数字 *x* 都为真。

你可以使用 `Number.POSITIVE_INFINITY` 属性来表示成功时返回有限数值的错误条件。不过，`NaN` 更适合于这种情况。

由于 `POSITIVE_INFINITY` 是 `Number` 的静态属性，你应该始终将其用作 `Number.POSITIVE_INFINITY`，而不是作为一个数字值的属性。

示例
--

### 使用 POSITIVE\_INFINITY

在下面的例子中，变量 `bigNumber` 被赋值为比最大值更大的数值。当 `if` 语句执行时，`bigNumber` 的值为 `Infinity`，所以在继续之前，`bigNumber` 被设置为一个更易于管理的值。

```js
let bigNumber = Number.MAX\_VALUE \* 2;

if (bigNumber === Number.POSITIVE\_INFINITY) {
  bigNumber = returnFinite();
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.positive\_infinity |

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

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

参见
--

* `Number.NEGATIVE_INFINITY`
* `Number.isFinite()`
* `Infinity`
* `isFinite()`


Number.prototype.toLocaleString() - JavaScript

Number.prototype.toLocaleString()
=================================

`Number` 值的 **`toLocaleString()`** 方法返回这个数字特定于语言环境的表示字符串。在具有 `Intl.NumberFormat` API 支持的实现中，此方法仅仅简单调用了 `Intl.NumberFormat`。

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

尝试一下
----

语法
--

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

### 参数

`locales` 和 `options` 参数让应用程序可以指定要进行格式转换的语言，并且定制函数的行为。

在使用具有 `Intl.NumberFormat` API 支持的实现时，这些参数与 `Intl.NumberFormat()` (en-US) 构造函数的参数相同。不支持 `Intl.NumberFormat` 时，会忽略参数，使得使用的区域设置和返回的字符串格式完全由实现决定。

`locales` 可选

缩写语言代码（BCP 47 language tag）的字符串或者这些字符串组成的数组。与 `Intl.NumberFormat()` 构造函数的 `locales` (en-US) 参数相同。

在无 `Intl.NumberFormat` 支持的实现中，往往使用主机的区域设置，这个参数是忽略的。

`options` 可选

调整输出格式的对象。与 `Intl.NumberFormat()` 构造函数的 `options` (en-US) 参数相同。

在无 `Intl.NumberFormat` 支持的实现中，这个参数是被忽略的。

请查阅 `Intl.NumberFormat()` 构造函数 (en-US)以了解这些参数的详细信息，以及如何使用它们。

### 返回值

返回一个语言环境下的表示字符串。

在使用 `Intl.NumberFormat` 的实现中，这与 `new Intl.NumberFormat(locales, options).format(number)` 调用等价。

示例
--

### 使用 toLocaleString()

在没有指定区域的基本使用时，返回使用默认的语言环境和默认选项格式化的字符串。

```js
const number = 3500;

console.log(number.toLocaleString()); // "3,500"，如果区域设置为美国英语
```

### 检查 locales 和 options 参数的支持

`locales` 和 `options` 参数可能不被所有实现支持，因为国际化 API 的支持是可选的，一些系统可能没有必要的数据。对于没有国际化支持的实现，`toLocaleString()` 总是使用系统的区域设置，这可能不是你想要的。因为任何支持 `locales` 和 `options` 参数的实现必须支持 `Intl` API，你可以检查后者的存在来确定是否支持：

```js
function toLocaleStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.NumberFormat === "function"
  );
}
```

### 使用 locales

这个示例展示了不同地区数字格式的差异。为了设置你的应用程序界面下使用的语言格式，请确保使用 `locales` 参数指定了使用的语言（可能还有一些备用语言）：

```js
const number = 123456.789;

// 德国使用逗号作为小数分隔符，分位周期为千位
console.log(number.toLocaleString("de-DE"));
// → 123.456,789

// 在大多数阿拉伯语国家使用阿拉伯语数字
console.log(number.toLocaleString("ar-EG"));
// → ١٢٣٤٥٦٫٧٨٩

// 印度使用千位/拉克（十万）/克若尔（千万）分隔
console.log(number.toLocaleString("en-IN"));
// → 1,23,456.789

// nu 扩展字段要求编号系统，e.g. 中文十进制
console.log(number.toLocaleString("zh-Hans-CN-u-nu-hanidec"));
// → 一二三,四五六.七八九

// 当请求不支持的语言时，例如巴厘语，加入一个备用语言，比如印尼语
console.log(number.toLocaleString(["ban", "id"]));
// → 123.456,789
```

### 使用 options

通过 `toLocaleString` 返回的结果可以通过 `options` 参数进行定制：

```js
const number = 123456.789;

// 要求货币格式
console.log(
  number.toLocaleString("de-DE", { style: "currency", currency: "EUR" }),
);
// → 123.456,79 €

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

// 限制三位有效数字
console.log(number.toLocaleString("en-IN", { maximumSignificantDigits: 3 }));
// → 1,23,000

// 使用带选项的主机默认语言进行数字格式化
const num = 30000.65;
console.log(
  num.toLocaleString(undefined, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  }),
);
// → "30,000.65" 英语为默认语言
// → "30.000,65" 德语为默认语言
// → "30 000,65" 法语为默认语言
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.tolocalestring |
| ECMAScript Internationalization API Specification # sup-number.prototype.tolocalestring |

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

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

参见
--

* `Number.prototype.toString()`


Number.isSafeInteger() - JavaScript

Number.isSafeInteger()
======================

**`Number.isSafeInteger()`** 静态方法判断提供的值是否是一个*安全整数*。

尝试一下
----

语法
--

```js
Number.isSafeInteger(testValue)
```

### 参数

`testValue`

要测试是否为安全整数的值。

### 返回值

如果给定的值是一个安全整数，则返回布尔值 `true`。否则返回 `false`。

描述
--

安全整数由 -(253 - 1) 到 253 - 1 的所有整数组成，包含（±9,007,199,254,740,991）。安全整数是符合以下条件的整数：

* 可以精确地表示为 IEEE-754 双精度数，并且
* 其 IEEE-754 表示形式不能是舍入任何其他整数以适应 IEEE-754 表示形式的结果。

例如，253 - 1 是一个安全整数：它可以精确地表示，并且在任何 IEEE-754 舍入模式下都没有其他整数舍入结果为该整数。相比之下，253 *不是*一个安全整数：它可以在 IEEE-754 中精确地表示，但整数 253 + 1 不能直接在 IEEE-754 中表示，而是采用就近舍入和向零舍入时，会舍入到 253。

处理大约 9 千万亿左右的值时，需要使用任意精度算术库来实现完全精确性。有关浮点数表示的更多信息，请参阅程序员需要了解的浮点数算术知识。

对于更大的整数，请考虑使用 `BigInt` 类型。

示例
--

### 使用 isSafeInteger()

```js
Number.isSafeInteger(3); // true
Number.isSafeInteger(2 \*\* 53); // false
Number.isSafeInteger(2 \*\* 53 - 1); // true
Number.isSafeInteger(NaN); // false
Number.isSafeInteger(Infinity); // false
Number.isSafeInteger("3"); // false
Number.isSafeInteger(3.1); // false
Number.isSafeInteger(3.0); // true
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.issafeinteger |

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

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

参见
--

* `core-js` 中 `Number.isSafeInteger` 的 polyfill
* `Number`
* `Number.MIN_SAFE_INTEGER`
* `Number.MAX_SAFE_INTEGER`
* `BigInt`


Number.prototype.toPrecision() - JavaScript

Number.prototype.toPrecision()
==============================

`Number` 值的 **`toPrecision()`** 方法返回一个以指定精度表示该数字的字符串。

尝试一下
----

语法
--

```js
toPrecision()
toPrecision(precision)
```

### 参数

`precision` 可选

一个指定有效位数的整数。

### 返回值

一个以定点表示法或指数表示法表示 `Number` 对象的字符串，该字符串四舍五入到 `precision` 个有效数字。有关四舍五入的讨论，请参阅 `Number.prototype.toFixed()` 方法的描述，其也适用于 `toPrecision()`。

如果 `precision` 参数被省略，则与 `Number.prototype.toString()` 行为相同。如果 `precision` 参数不是整数，则将其四舍五入到最近的整数。

### 异常

`RangeError`

如果 `precision` 不在 `1` 和 `100` 之间（包含两端），则抛出该错误。

示例
--

### 使用 `toPrecision`

```js
let numObj = 5.123456;

console.log(numObj.toPrecision()); // 输出 '5.123456'
console.log(numObj.toPrecision(5)); // 输出 '5.1235'
console.log(numObj.toPrecision(2)); // 输出 '5.1'
console.log(numObj.toPrecision(1)); // 输出 '5'

numObj = 0.000123;

console.log(numObj.toPrecision()); // 输出 '0.000123'
console.log(numObj.toPrecision(5)); // 输出 '0.00012300'
console.log(numObj.toPrecision(2)); // 输出 '0.00012'
console.log(numObj.toPrecision(1)); // 输出 '0.0001'

// 请注意，在某些情况下可能会返回指数表示法字符串
console.log((1234.5).toPrecision(2)); // 输出 '1.2e+3'
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.toprecision |

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

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

参见
--

* `Number.prototype.toFixed()`
* `Number.prototype.toExponential()`
* `Number.prototype.toString()`


Number.prototype.toFixed() - JavaScript

Number.prototype.toFixed()
==========================

`Number` 值的 **`toFixed()`** 方法使用定点表示法来格式化该数值。

尝试一下
----

语法
--

```js
toFixed()
toFixed(digits)
```

### 参数

`digits` 可选

小数点后的位数。应该是一个介于 `0` 和 `100` 之间的值，包括 `0` 和 `100`。如果这个参数被省略，则被视为 `0`。

### 返回值

使用定点表示法表示给定数字的字符串。

### 异常

`RangeError`

如果 `digits` 不是介于 `0` 和 `100` 之间（含两端）的值，则抛出该异常。

`TypeError`

如果不是在 `Number` 上调用该方法，则抛出该异常。

描述
--

`toFixed()` 方法返回一个表示 `numObj` 的字符串，但不使用指数计数法，并且小数点后有精确到 `digits` 位的数字。如果需要截断，则将数字四舍五入；如果小数位数不足，则小数部分用零填充，以使其具有指定长度。

如果 `numObj` 的绝对值大于或等于 1021，则该方法使用与 `Number.prototype.toString()` 相同的算法，并以指数计数法返回字符串。如果 `numObj` 的值不是有限的，则 `toFixed()` 会返回 `"Infinity"`、`"NaN"` 或 `"-Infinity"`。

`toFixed()` 对于某些值可能具有比 `toString` 更加精确的输出，因为 `toString()` 只输出足够的有效数字来区分该数值与邻近的数值。例如：

```js
(1000000000000000128).toString(); // '1000000000000000100'
(1000000000000000128).toFixed(0); // '1000000000000000128'
```

然而，选择一个过高的 `digits` 精度会导致意外的结果，因为小数部分的数字不能精确地表示成浮点数。例如：

```js
(0.3).toFixed(50); // '0.29999999999999998889776975374843459576368331909180'
```

示例
--

### 使用 toFixed()

```js
const numObj = 12345.6789;

numObj.toFixed(); // '12346'；四舍五入，没有小数部分
numObj.toFixed(1); // '12345.7'；向上舍入
numObj.toFixed(6); // '12345.678900'；用零补足位数
(1.23e20).toFixed(2); // '123000000000000000000.00'
(1.23e-10).toFixed(2); // '0.00'
(2.34).toFixed(1); // '2.3'
(2.35).toFixed(1); // '2.4'；向上舍入
(2.55).toFixed(1); // '2.5'
// 它向下舍入，因为它无法用浮点数精确表示，并且最接近的可表示浮点数较小
(2.449999999999999999).toFixed(1); // '2.5'
// 向上舍入，因为它与 2.45 的差值小于 Number.EPSILON。
// 这个字面量实际上编码和 2.45 相同的数值

(6.02 \* 10 \*\* 23).toFixed(50); // 6.019999999999999e+23；大数仍然使用指数表示法
```

### 对负数使用 toFixed()

由于成员访问的优先级高于一元减号，你需要将负数表达式组合以获得一个字符串。

```js
-2.34.toFixed(1); // -2.3，数字
(-2.34).toFixed(1); // '-2.3'
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.prototype.tofixed |

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

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

参见
--

* `Number.prototype.toExponential()`
* `Number.prototype.toPrecision()`
* `Number.prototype.toString()`
* `Number.EPSILON`


Number() 构造函数 - JavaScript

Number() 构造函数
=============

**`Number()`** 构造函数创建 `Number` 对象。当作为函数调用时，它返回 Number 类型的原始值。

语法
--

```js
new Number(value)
Number(value)
```

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

### 参数

`value`

所创建对象的数值。

### 返回值

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

当 `Number` 作为普通函数调用时，它将参数强制转换为数字原始值。BigInt 被转换为数字。如果值不能转换，则返回 `NaN`。

**警告：** 你会发现你很少会使用 `Number` 作为构造函数。

示例
--

### 创建 Number 对象

```js
const a = new Number("123"); // a === 123 为 false
const b = Number("123"); // b === 123 为 true
a instanceof Number; // 为 true
b instanceof Number; // 为 false
typeof a; // "object"
typeof b; // "number"
```

### 使用 Number() 将 BigInt 转换为数字

`Number()` 是唯一可以将 BigInt 转换为数字而不抛出错误的情况，因为这是完全显式的转换。

```js
+1n; // TypeError: Cannot convert a BigInt value to a number
0 + 1n; // TypeError: Cannot mix BigInt and other types, use explicit conversions
```

```js
Number(1n); // 1
```

注意，如果 BigInt 非常大，以至于不能安全地表示它，这种转换可能会损失精度。

```js
BigInt(Number(2n \*\* 54n + 1n)) === 2n \*\* 54n + 1n; // false
```

规范
--

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

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

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

参见
--

* `core-js` 中现代 `Number` 行为（支持二进制和八进制字面量）的 Polyfill
* `NaN`
* `Math`
* `BigInt`


Number.prototype.valueOf() - JavaScript

Number.prototype.valueOf()
==========================

`Number` 值的 **`valueOf()`** 方法返回该数字的值。

尝试一下
----

语法
--

```js
valueOf()
```

### 参数

无。

### 返回值

一个表示指定 `Number` 对象的原始值的数字。

描述
--

该方法通常由 JavaScript 在内部调用，而非在 Web 代码中显式调用。

示例
--

### 使用 valueOf

```js
const numObj = new Number(10);
console.log(typeof numObj); // object

const num = numObj.valueOf();
console.log(num); // 10
console.log(typeof num); // number
```

规范
--

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

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

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

参见
--

* `Object.prototype.valueOf()`


Number.isFinite() - JavaScript

Number.isFinite()
=================

**`Number.isFinite()`** 静态方法判断传入值是否是一个有限数——也就是说，它检查给定值是一个数字，且该数字既不是正的 `Infinity`，也不是负的 `Infinity` 或 `NaN`。

尝试一下
----

语法
--

```js
Number.isFinite(value)
```

### 参数

`value`

要测试有限性的值。

### 返回值

如果给定值是有限数，则返回布尔值 `true`。否则为 `false`。

示例
--

### 使用 isFinite()

```js
Number.isFinite(Infinity); // false
Number.isFinite(NaN); // false
Number.isFinite(-Infinity); // false

Number.isFinite(0); // true
Number.isFinite(2e64); // true
```

### Number.isFinite() 和全局 isFinite() 之间的不同

与全局 `isFinite()` 函数相比，此方法不会先将参数转换为数字，这意味着只有类型为数字*且*为有限数的值才返回 `true`，而非数字的值始终返回 `false`。

```js
isFinite("0"); // true；强制转换为数字 0
Number.isFinite("0"); // false
isFinite(null); // true；强制转换为数字 0
Number.isFinite(null); // false
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.isfinite |

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

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

参见
--

* `core-js` 中 `Number.isFinite` 的 polyfill
* `Number`
* `isFinite()`


Number.MIN_VALUE - JavaScript

Number.MIN\_VALUE
=================

**`Number.MIN_VALUE`** 静态数据属性表示在 JavaScript 中可表示的最小正数值。

尝试一下
----

值
-

2-1074，或 `5E-324`。

| `Number.MIN_VALUE` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |

描述
--

`Number.MIN_VALUE` 是能够在浮点精度范围内表示的最小正数（不是最小负数），换句话说，它是最接近 0 的数。ECMAScript 规范并没有定义引擎实现必须支持的精确值，而是规定：*“必须是实现实际上可以表示的最小非零正值”*。这是因为小的 IEEE-754 浮点数是非正规数，但是实现并不要求支持这种表示方式，这种情况下 `Number.MIN_VALUE` 可能会更大。

在实践中，在主流引擎（如 Chrome、Edge、Node.js 使用的 V8 引擎，Firefox 使用的 SpiderMonkey 引擎，以及 Safari 使用的 JavaScriptCore 引擎）中，`Number.MIN_VALUE` 的精确值为 2-1074，即 `5E-324`。

由于 `MIN_VALUE` 是 `Number` 对象的静态属性，你应该始终将其用作 `Number.MIN_VALUE`，而不是作为一个数字值的属性。

示例
--

### 使用 MIN\_VALUE

下面的代码对两个数值进行除法运算。如果结果大于或等于 `MIN_VALUE`，则调用函数 `func1`；否则，调用函数 `func2`。

```js
if (num1 / num2 >= Number.MIN\_VALUE) {
  func1();
} else {
  func2();
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.min\_value |

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

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

参见
--

* `Number.MAX_VALUE`


Number.MIN_SAFE_INTEGER - JavaScript

Number.MIN\_SAFE\_INTEGER
=========================

**`Number.MIN_SAFE_INTEGER`** 静态数据属性代表在 JavaScript 中最小的安全整数（-253 – 1）。

要表示比这小的整数，请考虑使用 `BigInt`。

尝试一下
----

值
-

`-9007199254740991`（-9,007,199,254,740,991，或大约 -9 千万亿）。

| `Number.MIN_SAFE_INTEGER` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |

描述
--

双精度浮点格式只有 52 位用于表示尾数，因此它只能安全地表示介于 -(253 – 1) 和 253 – 1 之间的整数。本文中，“安全”指的是能够精确表示整数并正确比较它们。例如，`Number.MIN_SAFE_INTEGER - 1 === Number.MIN_SAFE_INTEGER - 2` 的结果将为真，这在数学上是不正确的。有关更多信息，请参阅 `Number.isSafeInteger()`。

由于 `MIN_SAFE_INTEGER` 是 `Number` 的静态属性，你应该始终将其使用为 `Number.MIN_SAFE_INTEGER`，而不是一个数字值的属性。

示例
--

### 使用 MIN\_SAFE\_INTEGER

```js
Number.MIN\_SAFE\_INTEGER; // -9007199254740991
-(2 \*\* 53 - 1); // -9007199254740991
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.min\_safe\_integer |

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

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

参见
--

* `core-js` 中 `Number.MIN_SAFE_INTEGER` 的 polyfill
* `Number.MAX_SAFE_INTEGER`
* `Number.isSafeInteger()`
* `BigInt`


Number.NEGATIVE_INFINITY - JavaScript

Number.NEGATIVE\_INFINITY
=========================

**`Number.NEGATIVE_INFINITY`** 静态数据属性表示负无穷值。

尝试一下
----

值
-

与全局属性 `Infinity` 的负值相同。

| `Number.NEGATIVE_INFINITY` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 否 |

描述
--

`Number.NEGATIVE_INFINITY` 的表现同数学上的无穷大略有不同：

* 任何正值，包括 `POSITIVE_INFINITY`，乘以 `NEGATIVE_INFINITY` 等于 `NEGATIVE_INFINITY`。
* 任何负值，包括 `NEGATIVE_INFINITY`，乘以 `POSITIVE_INFINITY` 等于 `POSITIVE_INFINITY`。
* 任何正值除以 `NEGATIVE_INFINITY` 都是负零（正如 IEEE 754 中所定义的）。
* 任何负值除以 `NEGATIVE_INFINITY` 都是正零（正如 IEEE 754 中所定义的）。
* 零除以 `NEGATIVE_INFINITY` 等于 `NaN`。
* `NaN` 乘以 `NEGATIVE_INFINITY` 等于 `NaN`。
* `NEGATIVE_INFINITY`，除以任何负值（除了 `NEGATIVE_INFINITY`），都等于 `POSITIVE_INFINITY`。
* `POSITIVE_INFINITY`，除以任何正值（除了 `POSITIVE_INFINITY`），都等于 `NEGATIVE_INFINITY`。
* `NEGATIVE_INFINITY`，除以 `NEGATIVE_INFINITY` 或 `POSITIVE_INFINITY`，都等于 `NaN`。
* `x > Number.NEGATIVE_INFINITY` 对于任何不是 `NEGATIVE_INFINITY` 的数字 *x* 都为真。

你可以使用 `Number.NEGATIVE_INFINITY` 属性来表示成功时返回有限数值的错误条件。不过，`NaN` 更适合于这种情况。

由于 `NEGATIVE_INFINITY` 是 `Number` 的静态属性，你应该始终将其用作 `Number.NEGATIVE_INFINITY`，而不是作为一个数字值的属性。

示例
--

### 使用 NEGATIVE\_INFINITY

在下面的例子中，变量 `smallNumber` 被赋值为比最小值更小的数值。当 `if` 语句执行时，`smallNumber` 的值为 `-Infinity`，所以在继续之前，`smallNumber` 被设置为一个更易于管理的值。

```js
let smallNumber = -Number.MAX\_VALUE \* 2;

if (smallNumber === Number.NEGATIVE\_INFINITY) {
  smallNumber = returnFinite();
}
```

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-number.negative\_infinity |

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

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

参见
--

* `Number.POSITIVE_INFINITY`
* `Number.isFinite()`
* `Infinity`
* `isFinite()`


Function.displayName - JavaScript

Function.displayName
====================

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

`Function` 实例的 **`displayName`** 可选属性指定函数的显示名称。

值
-

`displayName` 属性最初在任何函数上都不存在，它是由代码作者添加的。出于显示的目的，它应该是一个字符串。

描述
--

如果存在 `displayName` 属性，其可能会被控制台和性能分析工具优先选择，作为函数的名称显示。

在各种浏览器中，只有 Firefox 控制台使用该属性。React 开发者工具在显示组件树时也使用 `displayName` 属性。

Firefox 对可能由匿名 JavaScript 函数命名约定算法生成的 `displayName` 进行了一些基本的解码尝试。以下模式可以被检测到：

* 如果 `displayName` 以一系列字母数字字符、`_` 和 `$` 结尾，最长的这种后缀将被显示。
* 如果 `displayName` 以一系列以 `[]` 包围的字符结尾，该序列将被显示，但不包括方括号。
* 如果 `displayName` 以一系列字母数字字符和 `_`，后面跟着一些 `/`、`.` 或 `<` 结尾，将返回该序列，但不包括尾部的 `/`、`.` 或 `<` 字符。
* 如果 `displayName` 以一系列字母数字字符和 `_`，后面跟着 `(^)` 结尾，该序列将被显示，但不包括 `(^)`。

如果以上模式都不匹配，则显示整个 `displayName`。

示例
--

### 设置 displayName

通过在 Firefox 控制台中输入以下内容，它应该显示为类似 `function MyFunction()` 的内容：

```js
const a = function () {};
a.displayName = "MyFunction";

a; // function MyFunction()
```

### 动态更改 displayName

你可以动态更改函数的 `displayName`：

```js
const object = {
  // anonymous
  someMethod: function someMethod(value) {
    someMethod.displayName = `someMethod (${value})`;
  },
};

console.log(object.someMethod.displayName); // undefined

object.someMethod("123");
console.log(object.someMethod.displayName); // "someMethod (123)"
```

### 清理 displayName

Firefox 开发者工具会在显示 `displayName` 属性之前清理一些常见的模式。

```js
function foo() {}

function testName(name) {
  foo.displayName = name;
  console.log(foo);
}

testName("$foo$"); // function $foo$()
testName("foo bar"); // function bar()
testName("Foo.prototype.add"); // function add()
testName("foo ."); // function foo .()
testName("foo <"); // function foo <()
testName("foo?"); // function foo?()
testName("foo()"); // function foo()()

testName("[...]"); // function ...()
testName("foo<"); // function foo()
testName("foo..."); // function foo()
testName("foo(^)"); // function foo()
```

规范
--

不属于任何规范。

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

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

参见
--

* `Function.prototype.name`


Function.name - JavaScript

Function.name
=============

`Function` 实例的 **`name`** 数据属性表示函数在创建时指定的名称，或者如果函数是匿名函数，则名称可以是 `anonymous` 或 `''`（空字符串）。

尝试一下
----

值
-

一个字符串。

| `Function.name` 的属性特性 |
| --- |
| 可写 | 否 |
| 可枚举 | 否 |
| 可配置 | 是 |

**备注：** 在非标准的、ES2015 之前的实现中，`configurable` 属性也是 `false`。

描述
--

函数的 `name` 属性可用于在调试工具或错误消息中标识该函数。它对语言本身没有任何意义。

`name` 属性是只读的，不能用赋值运算符修改：

```js
function someFunction() {}

someFunction.name = "otherFunction";
console.log(someFunction.name); // someFunction
```

想要改变它，请使用 `Object.defineProperty()`。

`name` 属性通常是从函数的定义方式推断出来的。在下面的部分中，我们将描述推断它的各种方法。

### 函数声明

`name` 属性会返回函数声明的名称。

```js
function doSomething() {}
doSomething.name; // "doSomething"
```

### 默认导出的函数声明

一个 `export default` 声明将函数作为声明导出，而不是表达式。如果声明是匿名的，则名称为 `"default"`。

```js
// -- someModule.js --
export default function () {}

// -- main.js --
import someModule from "./someModule.js";

someModule.name; // "default"
```

### 构造函数

使用 `Function()` 构造函数创建的函数的名称是“anonymous”。

```js
new Function().name; // "anonymous"
```

### 函数表达式

如果函数表达式被命名，则该名称将用作 `name` 属性的值。

```js
const someFunction = function someFunctionName() {};
someFunction.name; // "someFunctionName"
```

使用关键字 `function` 或箭头函数创建的匿名函数表达式将以 `""`（空字符串）作为名称。

```js
(function () {}).name; // ""
(() => {}).name; // ""
```

然而，这种情况很少见——通常，为了在其他地方引用表达式，函数表达式在创建时会附加到一个标识符上（例如在变量声明中）。在这种情况下，名称可以被推断出来，正如下面的几个小节所示。

一个实际情况是，从另一个函数返回的函数无法推断其名称：

```js
function getFoo() {
  return () => {};
}
getFoo().name; // ""
```

### 变量声明和方法

变量和方法可以从其语法位置推断出匿名函数的名称。

```js
const f = function () {};
const object = {
  someMethod: function () {},
};

console.log(f.name); // "f"
console.log(object.someMethod.name); // "someMethod"
```

这同样适用于赋值：

```js
let f;
f = () => {};
f.name; // "f"
```

### 初始化器和默认值

在解构赋值、默认参数、类字段等的初始化器（默认值）中的函数，将继承绑定标识符的名称作为它们的 `name`。

```js
const [f = () => {}] = [];
f.name; // "f"

const { someMethod: m = () => {} } = {};
m.name; // "m"

function foo(f = () => {}) {
  console.log(f.name);
}
foo(); // "f"

class Foo {
  static someMethod = () => {};
}
Foo.someMethod.name; // someMethod
```

### 简写方法

```js
const o = {
  foo() {},
};
o.foo.name; // "foo";
```

### 绑定函数

`Function.prototype.bind()` 所创建的函数将会在函数的名称前加上“bound”。

```js
function foo() {}
foo.bind({}).name; // "bound foo"
```

### getter 和 setter

当使用 `get` 和 `set` 访问器属性时，函数名称中将出现“get”或“set”。

```js
const o = {
  get foo() {},
  set foo(x) {},
};

const descriptor = Object.getOwnPropertyDescriptor(o, "foo");
descriptor.get.name; // "get foo"
descriptor.set.name; // "set foo";
```

### 类

类的名称遵循与函数声明和表达式相同的算法。

```js
class Foo {}
Foo.name; // "Foo"
```

**警告：** JavaScript 只会在函数没有自有的 `name` 属性时才设置函数的 `name` 属性。然而，类的静态成员将被设置为类构造函数的自有属性，从而阻止内置的 `name` 属性生效。请参阅下面的示例。

### 以 Symbol 为函数名称

如果使用一个 `Symbol` 作为函数名，并且该 symbol 有一个描述，那么该方法的名称将是方括号中的描述。

```js
const sym1 = Symbol("foo");
const sym2 = Symbol();

const o = {
  [sym1]() {},
  [sym2]() {},
};

o[sym1].name; // "[foo]"
o[sym2].name; // "[]"
```

### 私有属性

私有字段和私有方法的名称中包含哈希符号（`#`）。

```js
class Foo {
  #field = () => {};
  #method() {}
  getNames() {
    console.log(this.#field.name);
    console.log(this.#method.name);
  }
}

new Foo().getNames();
// "#field"
// "#method"
```

示例
--

### 获取对象的构造函数名称

你可以使用 `obj.constructor.name` 来检查对象的“类”名。

```js
function Foo() {} // 或：class Foo {}

const fooInstance = new Foo();
console.log(fooInstance.constructor.name); // "Foo"
```

然而，由于静态成员将成为类的自有属性，我们几乎无法获取具有静态方法属性 `name()` 的任何类的类名：

```js
class Foo {
  constructor() {}
  static name() {}
}
```

使用 `static name()` 方法后，`Foo.name` 不再保存实际的类名，而是一个对 `name()` 函数对象的引用。尝试通过 `fooInstance.constructor.name` 获取 `fooInstance` 的类名将无法得到类名，而是得到一个对静态类方法的引用。示例：

```js
const fooInstance = new Foo();
console.log(fooInstance.constructor.name); // ƒ name() {}
```

由于静态字段的存在，`name` 也可能不是一个函数。

```js
class Foo {
  static name = 123;
}
console.log(new Foo().constructor.name); // 123
```

如果类有一个静态属性名为 `name`，它也将变为*可写的*。在没有自定义静态定义的情况下，内置定义是*只读的*:

```js
Foo.name = "Hello";
console.log(Foo.name); // 如果 Foo 类有一个静态的“name”属性，则为“Hello”；但如果没有，则为“Foo”。
```

因此，你可能不会依赖内置的 `name` 属性来始终保存类的名称。

### JavaScript 压缩器和缩小器

**警告：** 在使用 JavaScript 压缩器（缩小器）或混淆器等源码转换工具时，要小心使用 `name` 属性。这些工具通常作为 JavaScript 构建流程的一部分使用，以减小程序在部署到生产环境之前的大小。此类转换通常会在构建时更改函数的名称。

例如有这样的一段源码：

```js
function Foo() {}
const foo = new Foo();

if (foo.constructor.name === "Foo") {
  console.log("“foo”是“Foo”一个的实例");
} else {
  console.log("Oops!");
}
```

可以压缩为：

```js
function a() {}
const b = new a();
if (b.constructor.name === "Foo") {
  console.log("“foo”是“Foo”一个的实例");
} else {
  console.log("Oops!");
}
```

在未压缩的版本中，程序进入了真值分支并打印了 "“foo”是“Foo”一个的实例"。而在压缩后的版本中，它的行为不同，并进入了 else 分支。如果你依赖于 `name` 属性，就像上面的示例一样，请确保你的构建流程不会更改函数名称，或者不要假设函数具有特定的名称。

规范
--

| Specification |
| --- |
| ECMAScript Language Specification # sec-function-instances-name |

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

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

参见
--

* `core-js` 中 `Function: name` 的 polyfill
* `Function`