NNext.js 中文网 GitHub

useRouter

了解更多关于 Next.js Router 的 API,以及如何使用 useRouter hook 在页面中访问 router 实例。

如果你想在应用的任何函数组件中访问 router 对象,可以使用 useRouter hook,请看以下示例:

jsx
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 不够用的情况。

js
router.push(url, as, options)
  • url:UrlObject | String - 要导航到的 URL(有关 UrlObject 属性,请参阅 Node.js URL 模块文档)。
  • as:UrlObject | String - 可选修饰符,用于设置浏览器地址栏中显示的路径。在 Next.js 9.5.3 之前,它用于动态路由。
  • options - 可选对象,包含以下配置选项:
    • scroll - 可选的布尔值,控制导航后是否滚动到页面顶部。默认值为 true
    • shallow: 更新当前页面的路径,而不重新运行 getStaticProps、getServerSideProps 或 getInitialProps。默认值为 false
    • locale - 可选字符串,表示新页面的区域设置

对于外部 URL,你不需要使用 router.push。window.location 更适合这些情况。

导航到预定义路由 pages/about.js:

jsx
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:

jsx
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,适用于认证之后的页面:

jsx
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 不会卸载组件。

pages/[slug].js
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]) ```

```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 参数都适用:

jsx
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,并可能解析到另一个页面:

jsx
// 在 `/` 页面上,URL 被屏蔽为 `/p/1`
router.push({ pathname: '/', query: { photoId: 2 } }, '/p/2', { shallow: true })

router.replace#

与 next/link 中的 replace 属性类似,router.replace 会阻止向 history 栈添加新的 URL 条目。

js
router.replace(url, as, options)
  • router.replace 的 API 与 router.push 的 API 完全相同。

请看以下示例:

jsx
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 在开发环境中不会预取页面。

js
router.prefetch(url, as, options)
  • url - 要预取的 URL,包括显式路由(例如 /dashboard)和动态路由(例如 /product/[id])
  • as - url 的可选修饰符。在 Next.js 9.5.3 之前,它用于预取动态路由。
  • options - 可选对象,包含以下允许的字段:
    • locale - 允许提供与当前区域设置不同的区域设置。如果为 false,则 url 必须包含区域设置,因为不会使用当前区域设置。

假设你有一个登录页面,登录后会将用户重定向到仪表盘。在这种情况下,我们可以预取仪表盘页面以实现更快的过渡,如下例所示:

jsx
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 对其执行操作之前做一些处理。

js
router.beforePopState(cb)
  • cb - 在收到 popstate 事件时运行的函数。该函数以对象形式接收事件状态,包含以下属性:
    • url:String - 新状态的路由。这通常是 page 的名称
    • as:String - 将在浏览器中显示的 url
    • options:Object - 由 router.push 发送的其他选项

如果 cb 返回 false,Next.js router 将不会处理 popstate,此时你需要自行处理。请参阅禁用文件系统路由。

你可以使用 beforePopState 来操纵请求,或强制进行 SSR 刷新,如下例所示:

jsx
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()。

jsx
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()。

jsx
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 并订阅该事件,如下所示:

jsx
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 属性,如下例所示:

jsx
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 中运行。

以前像这样的组件:

jsx
import { useRouter } from 'next/router'
const MyComponent = () => {
  const { isReady, query } = useRouter()
  // ...
}

在改为使用 next/compat/router 时会报错,因为无法对 null 进行解构。取而代之的是,开发者可以利用新的 hook:

jsx
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 的引用:

jsx
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 来避免错误:

jsx
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.push
  • router.replace
  • router.prefetch

可能的解决方案#

jsx
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 对象添加到任何组件中。

用法#

jsx
import { withRouter } from 'next/router'

function Page({ router }) {
  return <p>{router.pathname}</p>
}

export default withRouter(Page)

TypeScript#

要将类组件与 withRouter 一起使用,该组件需要接受一个 router prop:

tsx
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)
Next.js 中文网