useRouter
了解更多关于 Next.js Router 的 API,以及如何使用 useRouter hook 在页面中访问 router 实例。
如果你想在应用的任何函数组件中访问 router 对象,可以使用 useRouter hook,请看以下示例:
import { useRouter } from 'next/router'
function ActiveLink({ children, href }) {
const router = useRouter()
const style = {
marginRight: 10,
color: router.asPath === href ? 'red' : 'black',
}
const handleClick = (e) => {
e.preventDefault()
router.push(href)
}
return (
<a href={href} onClick={handleClick} style={style}>
{children}
</a>
)
}
export default ActiveLink
useRouter是一个 React Hook,这意味着它不能与类一起使用。你可以使用 withRouter,或者将你的类包裹在函数组件中。
router 对象#
以下是 useRouter 和 withRouter 返回的 router 对象的定义:
pathname:String- 当前路由文件位于/pages之后的路径。因此,不包含basePath、locale和尾部斜杠(trailingSlash: true)。query:Object- 解析为对象的查询字符串,包括动态路由参数。如果页面未使用服务端渲染,则在预渲染期间它将是空对象。默认值为{}asPath:String- 浏览器中显示的路径,包括搜索参数,并遵循trailingSlash配置。不包含basePath和locale。isFallback:boolean- 当前页面是否处于回退模式。basePath:String- 当前生效的 basePath(如果已启用)。locale:String- 当前生效的区域设置(如果已启用)。locales:String[]- 所有支持的区域设置(如果已启用)。defaultLocale:String- 当前的默认区域设置(如果已启用)。domainLocales:Array<{domain, defaultLocale, locales}>- 已配置的任何域名区域设置。isReady:boolean- router 字段是否已在客户端更新并可供使用。只应在useEffect方法中使用,不应用于在服务器端进行条件渲染。有关自动静态优化页面的用例,请参阅相关文档。isPreview:boolean- 应用程序当前是否处于预览模式。
如果页面使用服务端渲染或自动静态优化进行渲染,使用
asPath字段可能会导致客户端与服务端不匹配。在isReady字段为true之前,避免使用asPath。
router 中包含以下方法:
router.push#
处理客户端过渡,此方法适用于 next/link 不够用的情况。
router.push(url, as, options)url:UrlObject | String- 要导航到的 URL(有关UrlObject属性,请参阅 Node.js URL 模块文档)。as:UrlObject | String- 可选修饰符,用于设置浏览器地址栏中显示的路径。在 Next.js 9.5.3 之前,它用于动态路由。options- 可选对象,包含以下配置选项:scroll- 可选的布尔值,控制导航后是否滚动到页面顶部。默认值为trueshallow: 更新当前页面的路径,而不重新运行getStaticProps、getServerSideProps或getInitialProps。默认值为falselocale- 可选字符串,表示新页面的区域设置
对于外部 URL,你不需要使用
router.push。window.location 更适合这些情况。
导航到预定义路由 pages/about.js:
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.push('/about')}>
Click me
</button>
)
}导航到动态路由 pages/post/[pid].js:
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.push('/post/abc')}>
Click me
</button>
)
}将用户重定向到 pages/login.js,适用于认证之后的页面:
import { useEffect } from 'react'
import { useRouter } from 'next/router'
// 在这里获取并返回用户
const useUser = () => ({ user: null, loading: false })
export default function Page() {
const { user, loading } = useUser()
const router = useRouter()
useEffect(() => {
if (!(user || loading)) {
router.push('/login')
}
}, [user, loading])
return <p>Redirecting...</p>
}导航后重置状态#
在 Next.js 中导航到同一页面时,页面状态默认不会被重置,因为除非父组件发生变化,否则 React 不会卸载组件。
import Link from 'next/link'
import { useState } from 'react'
import { useRouter } from 'next/router'
export default function Page(props) {
const router = useRouter()
const [count, setCount] = useState(0)
return (
<div>
<h1>Page: {router.query.slug}</h1>
<p>Count: {count}</p>
<button onClick={() => setCount(count + 1)}>Increase count</button>
<Link href="/one">one</Link> <Link href="/two">two</Link>
</div>
)
}在上面的示例中,在 /one 和 /two 之间导航不会重置计数。useState 在渲染之间得以保持,因为顶层的 React 组件 Page 是相同的。
如果你不希望出现这种行为,有几种选择:
- 使用
useEffect手动确保每个状态都得到更新。在上面的示例中,可以是这样:
```jsx useEffect(() => {
setCount(0)}, [router.query.slug]) ```
- 使用 React
key来告诉 React 重新挂载组件。要对所有页面执行此操作,可以使用自定义 App:
```jsx filename="pages/_app.js" import { useRouter } from 'next/router'
export default function MyApp({ Component, pageProps }) {
const router = useRouter()
return <Component key={router.asPath} {...pageProps} />} ```
使用 URL 对象#
你可以像在 next/link 中一样使用 URL 对象。url 和 as 参数都适用:
import { useRouter } from 'next/router'
export default function ReadMore({ post }) {
const router = useRouter()
return (
<button
type="button"
onClick={() => {
router.push({
pathname: '/post/[pid]',
query: { pid: post.id },
})
}}
>
Click here to read more
</button>
)
}如果省略 pathname,查询将应用于浏览器中显示的 URL(asPath),而不是当前页面的路由(pathname)。这样可以保持重写完好无损:在由重写提供服务的页面上,仅包含查询的导航会保留访问者请求的 URL,而不会暴露重写目标。
当你使用 as 参数自行屏蔽 URL 时,这两个值也会有所不同。在这种情况下,请显式传递 pathname,否则查询将应用于被屏蔽的 URL,并可能解析到另一个页面:
// 在 `/` 页面上,URL 被屏蔽为 `/p/1`
router.push({ pathname: '/', query: { photoId: 2 } }, '/p/2', { shallow: true })router.replace#
与 next/link 中的 replace 属性类似,router.replace 会阻止向 history 栈添加新的 URL 条目。
router.replace(url, as, options)router.replace的 API 与router.push的 API 完全相同。
请看以下示例:
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.replace('/home')}>
Click me
</button>
)
}router.prefetch#
预取页面以加快客户端过渡。此方法仅适用于不使用 next/link 的导航,因为 next/link 会自动处理页面预取。
这是仅适用于生产环境的功能。Next.js 在开发环境中不会预取页面。
router.prefetch(url, as, options)url- 要预取的 URL,包括显式路由(例如/dashboard)和动态路由(例如/product/[id])as-url的可选修饰符。在 Next.js 9.5.3 之前,它用于预取动态路由。options- 可选对象,包含以下允许的字段:locale- 允许提供与当前区域设置不同的区域设置。如果为false,则url必须包含区域设置,因为不会使用当前区域设置。
假设你有一个登录页面,登录后会将用户重定向到仪表盘。在这种情况下,我们可以预取仪表盘页面以实现更快的过渡,如下例所示:
import { useCallback, useEffect } from 'react'
import { useRouter } from 'next/router'
export default function Login() {
const router = useRouter()
const handleSubmit = useCallback((e) => {
e.preventDefault()
fetch('/api/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
/* 表单数据 */
}),
}).then((res) => {
// 快速过渡到已经预取的仪表盘页面
if (res.ok) router.push('/dashboard')
})
}, [])
useEffect(() => {
// 预取仪表盘页面
router.prefetch('/dashboard')
}, [router])
return (
<form onSubmit={handleSubmit}>
<button type="submit">Login</button>
</form>
)
}router.beforePopState#
在某些情况下(例如使用自定义服务器时),你可能希望监听 popstate,并在 router 对其执行操作之前做一些处理。
router.beforePopState(cb)cb- 在收到popstate事件时运行的函数。该函数以对象形式接收事件状态,包含以下属性:url:String- 新状态的路由。这通常是page的名称as:String- 将在浏览器中显示的 urloptions:Object- 由 router.push 发送的其他选项
如果 cb 返回 false,Next.js router 将不会处理 popstate,此时你需要自行处理。请参阅禁用文件系统路由。
你可以使用 beforePopState 来操纵请求,或强制进行 SSR 刷新,如下例所示:
import { useEffect } from 'react'
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
useEffect(() => {
router.beforePopState(({ url, as, options }) => {
// 我只想允许这两个路由!
if (as !== '/' && as !== '/other') {
// 让 SSR 将错误路由渲染为 404。
window.location.href = as
return false
}
return true
})
}, [router])
return <p>Welcome to the page</p>
}router.back#
在历史记录中向后导航。相当于点击浏览器的后退按钮。它执行 window.history.back()。
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.back()}>
Click here to go back
</button>
)
}router.reload#
重新加载当前 URL。相当于点击浏览器的刷新按钮。它执行 window.location.reload()。
import { useRouter } from 'next/router'
export default function Page() {
const router = useRouter()
return (
<button type="button" onClick={() => router.reload()}>
Click here to reload
</button>
)
}router.events#
你可以监听 Next.js Router 中发生的各种事件。以下是支持的事件列表:
routeChangeStart(url, { shallow })- 路由开始变化时触发routeChangeComplete(url, { shallow })- 路由完全变化后触发routeChangeError(err, url, { shallow })- 切换路由时出错或路由加载被取消时触发err.cancelled- 指示导航是否被取消
beforeHistoryChange(url, { shallow })- 在更改浏览器历史记录之前触发hashChangeStart(url, { shallow })- 当 hash 即将变化但页面不变时触发hashChangeComplete(url, { shallow })- 当 hash 已变化但页面不变时触发
小知识:这里的
url是浏览器中显示的 URL,包括basePath。
例如,要监听 router 事件 routeChangeStart,请打开或创建 pages/_app.js 并订阅该事件,如下所示:
import { useEffect } from 'react'
import { useRouter } from 'next/router'
export default function MyApp({ Component, pageProps }) {
const router = useRouter()
useEffect(() => {
const handleRouteChange = (url, { shallow }) => {
console.log(
`App is changing to ${url} ${
shallow ? 'with' : 'without'
} shallow routing`
)
}
router.events.on('routeChangeStart', handleRouteChange)
// 如果组件被卸载,请使用 `off` 方法取消订阅该事件:
return () => {
router.events.off('routeChangeStart', handleRouteChange)
}
}, [router])
return <Component {...pageProps} />
}我们在本例中使用自定义 App(
pages/_app.js)来订阅该事件,因为它在页面导航时不会被卸载,不过你可以在应用的任何组件中订阅 router 事件。
Router 事件应在组件挂载时注册(useEffect 或 componentDidMount / componentWillUnmount),或者在事件发生时以命令式方式注册。
如果路由加载被取消(例如,连续快速点击两个链接),将触发 routeChangeError。此时传入的 err 会包含一个值为 true 的 cancelled 属性,如下例所示:
import { useEffect } from 'react'
import { useRouter } from 'next/router'
export default function MyApp({ Component, pageProps }) {
const router = useRouter()
useEffect(() => {
const handleRouteChangeError = (err, url) => {
if (err.cancelled) {
console.log(`Route to ${url} was cancelled!`)
}
}
router.events.on('routeChangeError', handleRouteChangeError)
// 如果组件被卸载,请使用 `off` 方法取消订阅该事件:
return () => {
router.events.off('routeChangeError', handleRouteChangeError)
}
}, [router])
return <Component {...pageProps} />
}next/compat/router 导出#
这是同一个 useRouter hook,但可以在 app 和 pages 目录中使用。
它与 next/router 的不同之处在于,当 pages router 未挂载时它不会抛出错误,而是返回类型为 NextRouter | null。 这使开发者在向 app router 过渡时,可以将组件转换为同时支持在 app 和 pages 中运行。
以前像这样的组件:
import { useRouter } from 'next/router'
const MyComponent = () => {
const { isReady, query } = useRouter()
// ...
}在改为使用 next/compat/router 时会报错,因为无法对 null 进行解构。取而代之的是,开发者可以利用新的 hook:
import { useEffect } from 'react'
import { useRouter } from 'next/compat/router'
import { useSearchParams } from 'next/navigation'
const MyComponent = () => {
const router = useRouter() // 可能为 null 或 NextRouter 实例
const searchParams = useSearchParams()
useEffect(() => {
if (router && !router.isReady) {
return
}
// 在 `app/` 中,searchParams 会立即带有值就绪,而在
// `pages/` 中,它会在 router 就绪后可用。
const search = searchParams.get('search')
// ...
}, [router, searchParams])
// ...
}现在该组件可以在 pages 和 app 目录中工作。当该组件不再用于 pages 时,你可以移除对 compat router 的引用:
import { useSearchParams } from 'next/navigation'
const MyComponent = () => {
const searchParams = useSearchParams()
// 由于该组件仅用于 `app/`,因此可以移除 compat router。
const search = searchParams.get('search')
// ...
}在 pages 中于 Next.js 上下文之外使用 useRouter#
另一个特定用例是在 Next.js 应用上下文之外渲染组件,例如在 pages 目录的 getServerSideProps 中。在这种情况下,可以使用 compat router 来避免错误:
import { renderToString } from 'react-dom/server'
import { useRouter } from 'next/compat/router'
const MyComponent = () => {
const router = useRouter() // 可能为 null 或 NextRouter 实例
// ...
}
export async function getServerSideProps() {
const renderedComponent = renderToString(<MyComponent />)
return {
props: {
renderedComponent,
},
}
}可能出现的 ESLint 错误#
router 对象上可访问的某些方法会返回 Promise。如果你启用了 ESLint 规则 no-floating-promises,可以考虑全局禁用它,或仅对相关行禁用。
如果你的应用需要此规则,你可以对 Promise 使用 void,或者使用 async 函数、await 该 Promise,然后对函数调用使用 void。当方法是在 onClick 处理函数中调用时,这不适用。
受影响的方法有:
router.pushrouter.replacerouter.prefetch
可能的解决方案#
import { useEffect } from 'react'
import { useRouter } from 'next/router'
// 在这里获取并返回用户
const useUser = () => ({ user: null, loading: false })
export default function Page() {
const { user, loading } = useUser()
const router = useRouter()
useEffect(() => {
// 禁用下一行的 lint 检查 - 这是最简洁的解决方案
// eslint-disable-next-line no-floating-promises
router.push('/login')
// 对 router.push 返回的 Promise 使用 void
if (!(user || loading)) {
void router.push('/login')
}
// 或者使用 async 函数,await 该 Promise,然后对函数调用使用 void
async function handleRouteChange() {
if (!(user || loading)) {
await router.push('/login')
}
}
void handleRouteChange()
}, [user, loading])
return <p>Redirecting...</p>
}withRouter#
如果 useRouter 不适合你,withRouter 也可以将相同的 router 对象添加到任何组件中。
用法#
import { withRouter } from 'next/router'
function Page({ router }) {
return <p>{router.pathname}</p>
}
export default withRouter(Page)TypeScript#
要将类组件与 withRouter 一起使用,该组件需要接受一个 router prop:
import React from 'react'
import { withRouter, NextRouter } from 'next/router'
interface WithRouterProps {
router: NextRouter
}
interface MyComponentProps extends WithRouterProps {}
class MyComponent extends React.Component<MyComponentProps> {
render() {
return <p>{this.props.router.pathname}</p>
}
}
export default withRouter(MyComponent)