recursal/MDN huggingface dataset:
HTMLMediaElement: playing
=========================

`playing` 事件在播放准备开始时（之前被暂停或者由于数据缺乏被暂缓）被触发。

|  |  |
| --- | --- |
| 是否冒泡 | 否 |
| 是否可取消 | 否 |
| 接口 | `Event` |
| 目标 | 元素 |
| 默认行为 | 无 |
| 事件处理器属性 | `GlobalEventHandlers.onplaying` |

示例
--

以下示例展示了如何为媒体元素的 `playing` 事件添加一个事件监听器，以在该事件触发时发送一条消息。

使用 `addEventListener()`：


```js
const video = document.querySelector("video");

video.addEventListener("playing", (event) => {
  console.log("Video is no longer paused");
});
```


使用 `onplaying` 事件处理器属性：


```js
const video = document.querySelector("video");

video.onplaying = (event) => {
  console.log("Video is no longer paused.");
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-media-playing |
| HTML Standard # handler-onplaying |

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

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

相关事件
----

* 媒体元素 `playing` 事件
* 媒体元素 `waiting` (en-US) 事件
* 媒体元素 `seeking` (en-US) 事件
* 媒体元素 `seeked` (en-US) 事件
* 媒体元素 `ended` 事件
* 媒体元素 `loadedmetadata` 事件
* 媒体元素 `loadeddata` 事件
* 媒体元素 `canplay` 事件
* 媒体元素 `canplaythrough` 事件
* 媒体元素 `durationchange` 事件
* 媒体元素 `timeupdate` 事件
* 媒体元素 `play` 事件
* 媒体元素 `pause` 事件
* 媒体元素 `ratechange` (en-US) 事件
* 媒体元素 `volumechange` (en-US) 事件
* 媒体元素 `suspend` (en-US) 事件
* 媒体元素 `emptied` (en-US) 事件
* 媒体元素 `stalled` (en-US) 事件
参见
--

* `HTMLAudioElement`
* `HTMLVideoElement`
* `<audio>`
* `<video>`
HTMLMediaElement: timeupdate
============================

当`currentTime`更新时会触发`timeupdate`事件。

这个事件的触发频率由系统决定，但是会保证每秒触发 4-66 次（前提是每次事件处理不会超过 250ms）。鼓励用户代理根据系统的负载和处理事件的平均成本来改变事件的频率，保证 UI 更新不会影响视频的解码。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `Event` |
| Target | Element |
| Default Action | None |
| Event handler property | `GlobalEventHandlers.ontimeupdate` |
| Specification | HTML5 media |

示例
--

These examples add an event listener for the HTMLMediaElement's `timeupdate` event, then post a message when that event handler has reacted to the event firing. Remember, the event frequency is dependant on the system load.

Using `addEventListener()`:


```js
const video = document.querySelector("video");

video.addEventListener("timeupdate", (event) => {
  console.log("The currentTime attribute has been updated. Again.");
});
```


Using the `ontimeupdate` event handler property:


```js
const video = document.querySelector("video");

video.ontimeupdate = (event) => {
  console.log("The currentTime attribute has been updated. Again.");
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-media-timeupdate |
| HTML Standard # handler-ontimeupdate |

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

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

相关事件
----

* `HTMLMediaElement: playing event`
* `HTMLMediaElement: waiting event` (en-US)
* `HTMLMediaElement: seeking event` (en-US)
* `HTMLMediaElement: seeked event` (en-US)
* `HTMLMediaElement: ended event`
* `HTMLMediaElement: loadedmetadata event`
* `HTMLMediaElement: loadeddata event`
* `HTMLMediaElement: canplay event`
* `HTMLMediaElement: canplaythrough event`
* `HTMLMediaElement: durationchange event`
* `HTMLMediaElement: timeupdate event`
* `HTMLMediaElement: play event`
* `HTMLMediaElement: pause event`
* `HTMLMediaElement: ratechange event` (en-US)
* `HTMLMediaElement: volumechange event` (en-US)
* `HTMLMediaElement: suspend event` (en-US)
* `HTMLMediaElement: emptied event` (en-US)
* `HTMLMediaElement: stalled event` (en-US)
更多
--

* `HTMLAudioElement`
* `HTMLVideoElement`
* `<audio>`
* `<video>`
HTMLMediaElement: ended 事件
==========================

`ended` 事件会在媒体回放或者媒体流因达到了媒体的未尾或者没有更多可用的数据而停止时被触发。

该事件会在回放或媒体文件播放结束时，在`媒体元素`（`<audio>` 和 `<video>`）上触发。

|  |  |
| --- | --- |
| 是否冒泡 | 否 |
| 是否可取消 | 否 |
| 接口 | `Event` |
| 目标 | 元素 |
| 默认行为 | 无 |
| 事件处理器属性 | `GlobalEventHandlers.onended` |

**备注：** 该事件也在媒体捕捉与媒体流和 Web Audio 这两个 API 中定义。

示例
--

以下示例展示了如何为媒体元素的 `ended` 事件添加一个事件监听器，以在该事件触发时发送一条消息。

使用 `addEventListener()`：


```js
const video = document.querySelector("video");

video.addEventListener("ended", (event) => {
  console.log(
    "Video stopped either because 1) it was over, " +
      "or 2) no further data is available.",
  );
});
```


使用 `onended` 事件处理器属性：


```js
const video = document.querySelector("video");

video.onended = (event) => {
  console.log(
    "Video stopped either because 1) it was over, " +
      "or 2) no further data is available.",
  );
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-media-ended |
| HTML Standard # handler-onended |

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

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

相关事件
----

* 媒体元素 `playing` 事件
* 媒体元素 `waiting` (en-US) 事件
* 媒体元素 `seeking` (en-US) 事件
* 媒体元素 `seeked` (en-US) 事件
* 媒体元素 `ended` 事件
* 媒体元素 `loadedmetadata` 事件
* 媒体元素 `loadeddata` 事件
* 媒体元素 `canplay` 事件
* 媒体元素 `canplaythrough` 事件
* 媒体元素 `durationchange` 事件
* 媒体元素 `timeupdate` 事件
* 媒体元素 `play` 事件
* 媒体元素 `pause` 事件
* 媒体元素 `ratechange` (en-US) 事件
* 媒体元素 `volumechange` (en-US) 事件
* 媒体元素 `suspend` (en-US) 事件
* 媒体元素 `emptied` (en-US) 事件
* 媒体元素 `stalled` (en-US) 事件
参见
--

* `HTMLAudioElement`
* `HTMLVideoElement`
* `<audio>`
* `<video>`
* 媒体捕捉与媒体流
    + 媒体捕捉与媒体流：ended 事件 (en-US)
* Web Audio API
    + Web audio API: ended 事件 (en-US)
HTMLMediaElement.currentSrc
===========================

**`HTMLMediaElement.currentSrc`** 属性包含所选媒体源的绝对 URL 路径。例如当程序会根据用户显示器分辨率选择不同媒体文件时会用到这个属性，显然它是只读的。当 **`networkState`** 值为 **`EMPTY`** 时，本属性值为空字符串（empty string）.

语法
--
```

var mediaUrl = audioObject.currentSrc;
```

### 值

一个 `DOMString` 对象包含所选媒体源的绝对 URL 路径。当 `networkState` ＝＝ `EMPTY 时，其值为空字符串（empty string）`; 否则，它会是 `HTMLSourceElement` (en-US) 所包含媒体列表中的一个，或者是 `<source>` 标签的 src 值。

示例
--


```js
var obj = document.createElement("video");
console.log(obj.currentSrc); // ""
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-media-currentsrc-dev |

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

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

参考
--

* The interface defining it, `HTMLMediaElement`.
HTMLMediaElement.videoTracks
============================

**`videoTracks`** 为 `HTMLMediaElement` 的只读属性，它是一个 `VideoTrackList` (en-US) 列表，列表中包含相应媒体元素的视频轨，视频轨为`VideoTrack` (en-US) 类型对象。

它是一个实时列表; 当相应的媒体元素增加或删除视频轨时，返回列表会发生动态的改变。由此你可以监控和检测视频轨发生的变化。学习 VideoTrackList 事件 (en-US)可以获得更多关于 media element 视频轨的知识。

Syntax
------
```

var videoTracks = mediaElement.videoTracks;
```

### 返回值

返回的是一个`VideoTrackList` (en-US) 类型值，为相应媒体元素的视频轨列表。可以用访问数组的方法访问这个值，或 `getTrackById()` (en-US) 方法访问它。

列表中包含的每一个 `VideoTrack` (en-US) 代表其中的一个视频轨。

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

| Specification |
| --- |
| HTML Standard # dom-media-videotracks-dev |

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

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

See also
--------

* The interface defining it, `HTMLMediaElement`.
* `<video>`
* `VideoTrack` (en-US) and `VideoTrackList` (en-US)
srcObject
=========

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

`HTMLMediaElement` 接口的 **`srcObject`** 属性设定或返回一个对象，这个对象提供了一个与`HTMLMediaElement`关联的媒体源，这个对象通常是 `MediaStream` ，但根据规范可以是 `MediaSource`， `Blob` 或者 `File`。

**备注：** 截至 2020 年 3 月，只有 Safari 支持设置 `MediaStream` 之外的对象。在其他浏览器跟上之前，对`MediaSource`, `Blob` 和 `File`, 请考虑返回创建具有{domxref("URL.createObjectURL()")}} 的 URL，并将其赋值给`HTMLMediaElement.src` 有关示例，请参阅下文。

语法
--
```

var mediaStream = HTMLMediaElement.srcObject
HTMLMediaElement.srcObject = mediaStream
```

### 值

一个 `MediaStream`，`MediaSource`，`Blob` 或者 `File` 对象（具体支持请参见兼容表）。

规范
--

| Specification |
| --- |
| HTML Standard # dom-media-srcobject-dev |

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

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

**`HTMLMediaElement.readyState`** 属性返回音频/视频的当前就绪状态。

语法
--
```

var readyState = audioOrVideo.readyState;
```

### 返回值

无符号整型 An `unsigned short`.

| Constant | Value | Description |
| --- | --- | --- |
| HAVE\_NOTHING | 0 | 没有关于音频/视频是否就绪的信息 |
| HAVE\_METADATA | 1 | 音频/视频已初始化 |
| HAVE\_CURRENT\_DATA | 2 | 数据已经可以播放 (当前位置已经加载) 但没有数据能播放下一帧的内容 |
| HAVE\_FUTURE\_DATA | 3 | 当前及至少下一帧的数据是可用的 (换句话来说至少有两帧的数据) |
| HAVE\_ENOUGH\_DATA | 4 | 可用数据足以开始播放 - 如果网速得到保障 那么视频可以一直播放到底 |

实例
--

这个例子会监听 id 为 example 的 audio 的数据。他会检查当前位置是否可以播放，会的话执行播放。


```html
<audio id="example" preload="auto">
  <source src="sound.ogg" type="audio/ogg" />
</audio>
```



```js
var obj = document.getElementById("example");

obj.addEventListener("loadeddata", function () {
  if (obj.readyState >= 2) {
    obj.play();
  }
});
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-media-readystate-dev |

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

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

你或许还可以看看
--------

* The interface defining it, `HTMLMediaElement`.
HTMLMediaElement: progress event
================================

**`progress`** 事件在浏览器加载一个资源的时候周期性触发。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `Event` |
| Event handler property | `onprogress` |

示例
--

### HTML


```html
<div class="example">
  <button type="button">Load video</button>
  <video controls width="250"></video>

  <div class="event-log">
    <label>Event log:</label>
    <textarea readonly class="event-log-contents"></textarea>
  </div>
</div>
```


```
.event-log-contents {
  width: 18rem;
  height: 5rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
}

.example {
  display: grid;
  grid-template-areas:
    "button log"
    "video log";
}

button {
  grid-area: button;
  width: 10rem;
  margin: 0.5rem 0;
}

video {
  grid-area: video;
}

.event-log {
  grid-area: log;
}

.event-log > label {
  display: block;
}
```

### JavaScript


```js
const loadVideo = document.querySelector("button");
const video = document.querySelector("video");
const eventLog = document.querySelector(".event-log-contents");
let source = null;

function handleEvent(event) {
  eventLog.textContent = eventLog.textContent + `${event.type}\n`;
}

video.addEventListener("loadstart", handleEvent);
video.addEventListener("progress", handleEvent);
video.addEventListener("canplay", handleEvent);
video.addEventListener("canplaythrough", handleEvent);

loadVideo.addEventListener("click", () => {
  if (source) {
    document.location.reload();
  } else {
    loadVideo.textContent = "Reset example";
    source = document.createElement("source");
    source.setAttribute(
      "src",
      "https://mdn.github.io/learning-area/html/multimedia-and-embedding/video-and-audio-content/rabbit320.mp4",
    );
    source.setAttribute("type", "video/mp4");

    video.appendChild(source);
  }
});
```

### 结果

规范
--

| Specification |
| --- |
| HTML Standard # event-media-progress |
| HTML Standard # handler-onprogress |

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

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

参见
--

* `HTMLAudioElement`
* `HTMLVideoElement`
* `<audio>`
* `<video>`
HTMLMediaElement：error 事件
=========================

**`error`** 事件会在因为一些错误（如网络连接错误）导致无法加载资源的时候触发。

事件不可取消也不会冒泡。

语法
--

在类似 `addEventListener()` 这样的方法中使用事件名称，或设置事件处理器属性。


```js
addEventListener("error", (event) => {});

onerror = (event) => {};
```

事件类型
----

一个通用的 `Event`。

示例
--


```js
const video = document.querySelector("video");
const videoSrc = "https://path/to/video.webm";

video.addEventListener("error", () => {
  console.error(`Error loading: ${videoSrc}`);
});

video.setAttribute("src", videoSrc);
```

规范
--

| Specification |
| --- |
| HTML Standard # event-media-error |
| HTML Standard # handler-window-onmessageerror |

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

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

参见
--

* `HTMLAudioElement`
* `HTMLVideoElement`
* `<audio>`
* `<video>`
HTMLMediaElement: durationchange 事件
===================================

`durationchange` 事件会在 `duration` 属性更新时被触发。

|  |  |
| --- | --- |
| Bubbles | No |
| Cancelable | No |
| Interface | `Event` |
| Target | Element |
| Default Action | None |
| Event handler property | `GlobalEventHandlers.ondurationchange` (en-US) |
| Specification | HTML5 media |

例子
--

下面的例子为 HTMLMediaElement 的 `durationchange` 事件添加事件监听器，然后在事件触发时发送一个消息。

使用 `addEventListener()`:


```js
const video = document.querySelector("video");

video.addEventListener("durationchange", (event) => {
  console.log("Not sure why, but the duration of the video has changed.");
});
```


使用 `ondurationchange` 事件处理器属性：


```js
const video = document.querySelector("video");

video.ondurationchange = (event) => {
  console.log("Not sure why, but the duration of the video has changed.");
};
```

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

| Specification |
| --- |
| HTML Standard # event-media-durationchange |
| HTML Standard # handler-ondurationchange |

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

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

Related Events
--------------

* `HTMLMediaElement: playing event`
* `HTMLMediaElement: waiting event` (en-US)
* `HTMLMediaElement: seeking event` (en-US)
* `HTMLMediaElement: seeked event` (en-US)
* `HTMLMediaElement: ended event`
* `HTMLMediaElement: loadedmetadata event`
* `HTMLMediaElement: loadeddata event`
* `HTMLMediaElement: canplay event`
* `HTMLMediaElement: canplaythrough event`
* `HTMLMediaElement: durationchange event`
* `HTMLMediaElement: timeupdate event`
* `HTMLMediaElement: play event`
* `HTMLMediaElement: pause event`
* `HTMLMediaElement: ratechange event` (en-US)
* `HTMLMediaElement: volumechange event` (en-US)
* `HTMLMediaElement: suspend event` (en-US)
* `HTMLMediaElement: emptied event` (en-US)
* `HTMLMediaElement: stalled event` (en-US)
See Also
--------

* `HTMLAudioElement`
* `HTMLVideoElement`
* `<audio>`
* `<video>`
HTMLMediaElement: canplay
=========================

`canplay` 事件在终端可以播放媒体文件时（但估计还没有加载足够的数据来播放媒体直到其结束，即后续可能需要停止以进一步缓冲内容）被触发。

|  |  |
| --- | --- |
| 是否冒泡 | 否 |
| 是否可取消 | 否 |
| 接口 | `Event` |
| 目标 | 元素 |
| 默认行为 | 无 |
| 事件处理器属性 | `GlobalEventHandlers.oncanplay` |

示例
--

以下示例展示了如何为媒体元素的 `canplay` 事件添加一个事件监听器，以在该事件触发时发送一条消息。

使用 `addEventListener()`：


```js
const video = document.querySelector("video");

video.addEventListener("canplay", (event) => {
  console.log("Video can start, but not sure it will play through.");
});
```


使用 `oncanplay` 事件处理器属性：


```js
const video = document.querySelector("video");

video.oncanplay = (event) => {
  console.log("Video can start, but not sure it will play through.");
};
```

规范
--

| Specification |
| --- |
| HTML Standard # event-media-canplay |
| HTML Standard # handler-oncanplay |

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

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

相关事件
----

* 媒体元素 `playing` 事件
* 媒体元素 `waiting` (en-US) 事件
* 媒体元素 `seeking` (en-US) 事件
* 媒体元素 `seeked` (en-US) 事件
* 媒体元素 `ended` 事件
* 媒体元素 `loadedmetadata` 事件
* 媒体元素 `loadeddata` 事件
* 媒体元素 `canplay` 事件
* 媒体元素 `canplaythrough` 事件
* 媒体元素 `durationchange` 事件
* 媒体元素 `timeupdate` 事件
* 媒体元素 `play` 事件
* 媒体元素 `pause` 事件
* 媒体元素 `ratechange` (en-US) 事件
* 媒体元素 `volumechange` (en-US) 事件
* 媒体元素 `suspend` (en-US) 事件
* 媒体元素 `emptied` (en-US) 事件
* 媒体元素 `stalled` (en-US) 事件
参见
--

* `HTMLAudioElement`
* `HTMLVideoElement`
* `<audio>`
* `<video>`
HTMLMediaElement: loadstart event
=================================

**`loadstart`** 事件当浏览器开始载入一个资源文件时 fired.

|  |  |
| --- | --- |
| Bubbles | No |
| 可撤销 | No |
| Interface | `Event` |
| Event handler property | `onloadstart` |

Examples
--------

### Live example

#### HTML


```html
<div class="example">
  <button type="button">Load video</button>
  <video controls width="250"></video>

  <div class="event-log">
    <label>Event log:</label>
    <textarea readonly class="event-log-contents"></textarea>
  </div>
</div>
```


```
.event-log-contents {
  width: 18rem;
  height: 5rem;
  border: 1px solid black;
  margin: 0.2rem;
  padding: 0.2rem;
}

.example {
  display: grid;
  grid-template-areas:
    "button log"
    "video log";
}

button {
  grid-area: button;
  width: 10rem;
  margin: 0.5rem 0;
}

video {
  grid-area: video;
}

.event-log {
  grid-area: log;
}

.event-log > label {
  display: block;
}
```


#### JS


```js
const loadVideo = document.querySelector("button");
const video = document.querySelector("video");
const eventLog = document.querySelector(".event-log-contents");
let source = null;

function handleEvent(event) {
  eventLog.textContent = eventLog.textContent + `${event.type}\n`;
}

video.addEventListener("loadstart", handleEvent);
video.addEventListener("progress", handleEvent);
video.addEventListener("canplay", handleEvent);
video.addEventListener("canplaythrough", handleEvent);

loadVideo.addEventListener("click", () => {
  if (source) {
    document.location.reload();
  } else {
    loadVideo.textContent = "Reset example";
    source = document.createElement("source");
    source.setAttribute(
      "src",
      "https://interactive-examples.mdn.mozilla.net/media/examples/flower.webm",
    );
    source.setAttribute("type", "video/webm");

    video.appendChild(source);
  }
});
```


#### Result

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

| Specification |
| --- |
| HTML Standard # event-media-loadstart |
| HTML Standard # handler-onloadstart |

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

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

See also
--------

* `HTMLAudioElement`
* `HTMLVideoElement`
* `<audio>`
* `<video>`
forward()
=========

在会话历史中向前移动一页。它与使用`delta`参数为 1 时调用 `history.go(delta)`的效果相同。

语法
--


```js
window.history.forward();
```

示例
--

下述例子创建了一个按钮，该按钮会在会话历史中向前移动一步。

### HTML


```html
<button id="go-forward">Go Forward!</button>
```

### JavaScript


```js
window.onload = function (e) {
  document.getElementById("go-forward").addEventListener("click", (e) => {
    window.history.forward();
  });
};
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-history-forward-dev |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
back()
======

`back()`方法会在会话历史记录中向后移动一页。如果没有上一页，则此方法调用不执行任何操作。

语法
--


```js
back()
```

示例
--

下述简短示例使页面上的按钮导航页面至会话历史的后一项。

### HTML


```html
<button id="go-back">Go back!</button>
```

### JavaScript


```js
window.onload = function (e) {
  document.getElementById("go-back").addEventListener("click", (e) => {
    window.history.back();
  });
};
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-history-back-dev |

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

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

History.length 是一个只读属性，返回当前 session 中的 history 个数，包含当前页面在内。举个例子，对于新开一个 tab 加载的页面当前属性返回值 1。

语法
--
```

length = history.length;
```

例子
--


```js
var result = window.history.length; // 返回当前 session 中的 history 个数
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-history-length-dev |

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

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

参考
--

* The `History` interface it belongs to.
History.scrollRestoration
=========================

`History` 的接口——\*\*`滚动恢复属性`\*\*允许 web 应用程序在历史导航上显式地设置默认滚动恢复行为

语法
--
```

const scrollRestore = history.scrollRestoration
```

### 值

`auto`

将恢复用户已滚动到的页面上的位置。

`manual`

未还原页上的位置。用户必须手动滚动到该位置。

案例
--

### 查看当前页面滚动恢复行为


```js
const scrollRestoration = history.scrollRestoration;
if (scrollRestoration === "manual") {
  console.log(
    "The location on the page is not restored, user will need to scroll manually.",
  );
}
```

### 防止自动恢复页面位置


```js
if (history.scrollRestoration) {
  history.scrollRestoration = "manual";
}
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-history-scroll-restoration-dev |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
go()
====

`go()`方法从会话历史记录中加载特定页面。你可以使用它在历史记录中前后移动，具体取决于`delta`参数的值。

语法
--


```js
window.history.go(delta);
```

### 参数

`delta` 可选

相对于当前页面你要去往历史页面的位置。负值表示向后移动，正值表示向前移动。因此，例如：`history.go(2)`向前移动两页，`history.go(-2)`则向后移动两页。如果未向该函数传参或`delta`相等于 0，则该函数与调用`location.reload()`具有相同的效果。

**备注：** 相等于 0 是采用宽松相等进行比较的。另外，JavaScript 值古怪的隐式转换在这里也是可用的。

示例
--

向后移动一页（等价于调用`back()`）：


```js
window.history.go(-1);
```


向前移动一页，就像调用了`forward()`：


```js
window.history.go(1);
```


向前移动两页：


```js
window.history.go(2);
```


向后移动两页：


```js
window.history.go(-2);
```


最后，以下任意一条语句都会重新加载当前页面：


```js
window.history.go();
window.history.go(0);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-history-go-dev |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
History：replaceState() 方法
=========================

`History` 接口的 **`replaceState()`** 方法使用状态对象和 URL 作为参数来修改当前的历史记录条目。当你想要更新当前历史记录条目的状态对象或者 URL 来响应用户的动作时，这个方法非常有用。

语法
--


```js
replaceState(state, unused)
replaceState(state, unused, url)
```

### 参数

`state`

一个与传递给 `replaceState()` 方法的历史记录条目相关联的对象。状态对象可以是 `null`。

`unused`

该参数由于历史原因而存在，不能省略；传递空字符串是传统的做法，也可以安全地应对未来对该方法的变更。

`url` 可选

历史记录条目的 URL。新的 URL 跟当前的 URL 必须同源；否则 `replaceState()` 方法将抛出异常。

### 返回值

无（`undefined`）。

### 异常

`SecurityError` `DOMException`

如果关联的文档没有完全激活，或者提供的 `url` 参数不是有效的 URL，则抛出该异常。

`DataCloneError` `DOMException`

如果提供的 `state` 参数不可序列化，则抛出该异常。

示例
--

假设 `https://www.mozilla.org/foo.html` 执行了以下 JavaScript 代码：


```js
const stateObj = { foo: "bar" };
history.pushState(stateObj, "", "bar.html");
```


在下一个页面，你可以使用 `history.state` 来访问刚刚添加的 `stateObj`。

上面这两行的解释可以在使用历史记录 API 一文中找到。然后假设 `https://www.mozilla.org/bar.html` 执行了下面的 JavaScript 代码：


```js
history.replaceState(stateObj, "", "bar2.html");
```


这会让 URL 栏显示 `https://www.mozilla.org/bar2.html`，但是不会加载 `bar2.html` 页面，甚至不会检查 `bar2.html` 是否存在。

假设用户跳转到 `https://www.microsoft.com`，然后点击返回按钮。这时，URL 栏将会显示 `https://www.mozilla.org/bar2.html`。如果用户此时再次点击返回按钮，URL 栏将会显示 `https://www.mozilla.org/foo.html` 页面，而完全绕过了 bar.html 页面。

规范
--

| Specification |
| --- |
| HTML Standard # dom-history-replacestate-dev |

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

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
History：pushState() 方法
======================

在 HTML 文档中，**`history.pushState()`** 方法向浏览器的会话历史栈增加了一个条目。

该方法是异步的。为 `popstate` 事件增加监听器，以确定导航何时完成。`state` 参数将在其中可用。

语法
--


```js
pushState(state, unused)
pushState(state, unused, url)
```

### 参数

`state`

`state` 对象是一个 JavaScript 对象，其与通过 `pushState()` 创建的新历史条目相关联。每当用户导航到新的 `state`，都会触发 `popstate` 事件，并且该事件的 `state` 属性包含历史条目 `state` 对象的副本。

`state` 对象可以是任何可以序列化的对象。因为 Firefox 将 `state` 对象保存到用户的磁盘上，以便用户重启浏览器可以恢复，我们对 `state` 对象序列化的表示施加了 16 MiB 的限制。如果你传递的 `state` 对象的序列化表示超出了 `pushState()` 可接受的大小，该方法将抛出异常。如果你需要更多的空间，建议使用 `sessionStorage` 和/或 `localStorage`。

`unused`

由于历史原因，该参数存在且不能忽略；传递一个空字符串是安全的，以防将来对该方法进行更改。

`url` 可选

新历史条目的 URL。请注意，浏览器不会在调用 `pushState()` 之后尝试加载该 URL，但是它可能会在以后尝试加载该 URL，例如，在用户重启浏览器之后。新 URL 可以不是绝对路径；如果它是相对的，它将相对于当前的 URL 进行解析。新的 URL 必须与当前 URL 同源；否则，`pushState()` 将抛出异常。如果该参数没有指定，则将其设置为当前文档的 URL。

### 返回值

无（`undefined`）。

描述
--

从某种程度来说，调用 `pushState()` 类似于 `window.location = "#foo"`，它们都会在当前的文档中创建和激活一个新的历史条目。但是 `pushState()` 有以下优势：

* 新的 URL 可以是任何和当前 URL 同源的 URL。然而，如果你仅修改 hash，将其设置到 `window.location`，将使你留在同一文档中。
* 改变页面的 URL 是可选的。相反，设置 `window.location = "#foo";` 仅仅会在当前 hash 不是 `#foo` 情况下，创建一条新的历史条目。
* 你可以使用你的新历史条目关联任意数据。使用基于 hash 的方式，你需要将所有相关的数据编码为一个短字符串。

注意，`pushState()` 从未引起 `hashchange` 事件的触发，即使新 URL 与旧 URL 仅在 hash 上不同。

示例
--

该示例通过设置 *state* 和 *url* 创建一条新的历史条目。

### JavaScript


```js
const state = { page\_id: 1, user\_id: 5 };
const url = "hello-world.html";

history.pushState(state, "", url);
```

### 改变查询参数


```js
const url = new URL(location);
url.searchParams.set("foo", "bar");
history.pushState({}, "", url);
```

规范
--

| Specification |
| --- |
| HTML Standard # dom-history-pushstate-dev |

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

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

参见
--

* 使用 History API
* Window：popstate 事件