Navigation API
Navigation API 的 NavigateEvent 接口是 Navigation/navigate_event 事件的事件对象,该事件会在任何类型的导航启动时触发(这包括使用History API 的特性,如 History.go())。NavigateEvent 对象提供对该导航信息的访问,并允许开发人员拦截和控制导航处理。
构造函数
- NavigateEvent.NavigateEvent
- : 创建一个新的
NavigateEvent对象实例。
- : 创建一个新的
实例属性
从其父接口 Event 继承属性。
- NavigateEvent.canIntercept
- : 如果导航可以被拦截,则返回
true,否则返回false(例如,你无法拦截跨源导航)。
- : 如果导航可以被拦截,则返回
- NavigateEvent.destination
- : 返回一个 NavigationDestination 对象,表示要导航到的目标。
- NavigateEvent.downloadRequest
- : 如果是下载导航(例如,具有
download属性的 a 或 area 元素),则返回请求下载的文件的文件名,否则返回null。
- : 如果是下载导航(例如,具有
- NavigateEvent.formData
- : 如果是
POST表单提交,则返回表示已提交数据的 FormData 对象,否则返回null。
- : 如果是
- NavigateEvent.hashChange
- : 如果导航是片段导航(即导航到同一文档中的片段标识符),则返回
true,否则返回false。
- : 如果导航是片段导航(即导航到同一文档中的片段标识符),则返回
- NavigateEvent.hasUAVisualTransition
- : 如果用户代理在派发此事件之前为此导航执行了用户可见的视图过渡,则返回
true,否则返回false。
- : 如果用户代理在派发此事件之前为此导航执行了用户可见的视图过渡,则返回
- NavigateEvent.info
- : 返回由启动导航操作(例如 Navigation.back() 或 Navigation.navigate())传递的
info数据值,如果没有传递info数据,则返回undefined。
- : 返回由启动导航操作(例如 Navigation.back() 或 Navigation.navigate())传递的
- NavigateEvent.navigationType
- : 返回导航类型——
push、reload、replace或traverse。
- : 返回导航类型——
- NavigateEvent.signal
- : 返回 AbortSignal,如果取消导航(例如,用户按下浏览器的“停止”按钮,或者另一个导航启动并因此取消正在进行的导航),该信号将中止。
- NavigateEvent.userInitiated
- : 如果导航是由用户发起的(例如,通过单击链接、提交表单或按浏览器的“后退”/“前进”按钮),则返回
true,否则返回false。
- : 如果导航是由用户发起的(例如,通过单击链接、提交表单或按浏览器的“后退”/“前进”按钮),则返回
实例方法
从其父接口 Event 继承方法。
- NavigateEvent.intercept
- : 拦截此导航,将其转换为指向 NavigationDestination.url URL 的同一文档导航。它可以接受定义导航处理行为应该是什么的处理器函数,以及
focusReset和scroll选项以根据需要控制行为。
- : 拦截此导航,将其转换为指向 NavigationDestination.url URL 的同一文档导航。它可以接受定义导航处理行为应该是什么的处理器函数,以及
- NavigateEvent.scroll
- : 如果你希望在导航处理完成之前发生,可以调用它来手动触发响应导航而发生的浏览器驱动的滚动行为。
示例
使用 intercept() 处理导航
navigation.addEventListener("navigate", (event) => {
// 如果此导航不应被拦截,则提前退出,例如,如果导航是跨源的,或者是下载请求
if (shouldNotIntercept(event)) return;
const url = new URL(event.destination.url);
if (url.pathname.startsWith("/articles/")) {
event.intercept({
async handler() {
// URL 已更改,因此在获取新内容时显示占位符,例如旋转图标或加载页面
renderArticlePagePlaceholder();
// 获取新内容并在准备就绪时显示
const articleContent = await getArticleContent(url.pathname);
renderArticlePage(articleContent);
},
});
}
});
[!NOTE] 在导航 API 可用之前,要执行类似操作,你必须监听链接上的所有点击事件,运行
e.preventDefault(),执行适当的 History.pushState() 调用,然后根据新 URL 设置页面视图。而且这无法处理所有导航——只能处理用户发起的链接点击。
使用 scroll() 处理滚动
在这个拦截导航的例子中,handler() 函数首先获取并呈现一些文章内容,然后获取并呈现一些次要内容。尽快将页面滚动到主要文章内容以便用户与其交互是有意义的,而不是等到次要内容也呈现后再滚动。为了实现这一点,我们在两者之间添加了 NavigateEvent.scroll 调用。
navigation.addEventListener("navigate", (event) => {
if (shouldNotIntercept(navigateEvent)) return;
const url = new URL(event.destination.url);
if (url.pathname.startsWith("/articles/")) {
event.intercept({
async handler() {
const articleContent = await getArticleContent(url.pathname);
renderArticlePage(articleContent);
event.scroll();
const secondaryContent = await getSecondaryContent(url.pathname);
addSecondaryContent(secondaryContent);
},
});
}
});
规范
浏览器兼容性
参见
- 现代客户端路由:导航 API
- 导航 API 说明
- Domenic Denicola 的导航 API 在线演示
来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。
