导航：navigate() 方法

有限可用性

此功能不是基线功能，因为它在一些使用最广泛的浏览器中不起作用。

实验性：这是一个实验性技术
在生产环境中使用此功能之前，请仔细查看浏览器兼容性表。

navigate() 是 Navigation 接口的方法，用于导航到特定的 URL，并更新历史记录条目列表中提供的任何状态。

语法

js
navigate(url)
navigate(url, options)

参数

url

要导航到的目标 URL。请注意，当在另一个窗口的 navigation 对象上调用 navigate() 时，URL 将相对于目标窗口的 URL 解析，而不是调用窗口的 URL。这与 历史记录 API 的行为一致，但与 位置 API 的行为不一致。

options 可选

包含以下属性的选项对象

state 可选

开发人员定义的信息，将在导航完成后存储在关联的 NavigationHistoryEntry 中，可以通过 getState() 检索。这可以是任何数据类型。例如，您可能希望存储页面访问次数以用于分析目的，或存储 UI 状态详细信息，以便可以完全按照用户上次离开时的状态显示视图。存储在 state 中的任何数据都必须是 结构化可克隆的。

info 可选

开发人员定义的信息，将传递给 navigate 事件，在 NavigateEvent.info 中可用。这可以是任何数据类型。例如，您可能希望根据导航到的方式（向左滑动、向右滑动或返回主页）以不同的动画显示新导航的内容。指示要使用哪个动画的字符串可以作为 info 传递。

history 可选

设置此导航历史行为的枚举值。可用值如下：

  • auto：默认值；通常执行 push 导航，但在特殊情况下会执行 replace 导航（请参阅下面的 NotSupportedError 说明）。
  • push：将新的 NavigationHistoryEntry 推送到条目列表中，或在特殊情况下失败（请参阅下面的 NotSupportedError 说明）。
  • replace：将替换当前的 NavigationHistoryEntry。

返回值

具有以下属性的对象

committed

一个 Promise，当可见 URL 更改且创建了新的 NavigationHistoryEntry 时，此 Promise 将完成。

finished

一个 Promise，当 intercept() 处理程序返回的所有 Promise 都已完成时，此 Promise 将完成。这等效于 NavigationTransition.finished Promise 完成时，以及 navigatesuccess 事件触发时。

如果导航由于某种原因失败，则这两个 Promise 之一将被拒绝。

异常

DataCloneError DOMException

如果 state 参数中包含的值不是结构化可克隆的，则会抛出此异常。

SyntaxError DOMException

如果 url 参数不是有效的 URL，则会抛出此异常。

NotSupportedError DOMException

如果 history 选项设置为 push，并且以下任何特殊情况为真，则会抛出此异常

  • 浏览器当前显示初始 about:blank 文档。
  • url 的方案是 javascript。

示例

设置主页按钮

js
function initHomeBtn() {
  // Get the key of the first loaded entry
  // so the user can always go back to this view.
  const { key } = navigation.currentEntry;
  backToHomeButton.onclick = () => {
    navigation.traverseTo(key);
  };
}
// Intercept navigate events, such as link clicks, and
// replace them with single-page navigations
navigation.addEventListener("navigate", (event) => {
  event.intercept({
    async handler() {
      // Navigate to a different view,
      // but the "home" button will always work.
    },
  });
});

智能后退按钮

页面提供的“后退”按钮即使在重新加载后也可以带您返回，方法是检查先前的历史记录条目

js
backButtonEl.addEventListener("click", () => {
  if (
    navigation.entries()[navigation.currentEntry.index - 1]?.url ===
    "/product-listing"
  ) {
    navigation.back();
  } else {
    // If the user arrived here in some other way
    // e.g. by typing the URL directly:
    navigation.navigate("/product-listing", { history: "replace" });
  }
});

使用 info 和 state

js
async function navigateHandler() {
  await navigation.navigate(url, {
    info: { animation: "swipe-right" },
    state: { infoPaneOpen: true },
  }).finished;

  // Update application state
  // ...
}

规范

规范
HTML 标准
# dom-navigation-navigate-dev

浏览器兼容性

BCD 表仅在启用 JavaScript 的浏览器中加载。

另请参阅