NNext.js 中文网 GitHub

useLinkStatus

useLinkStatus hook 的 API 参考。

useLinkStatus hook 允许你跟踪 <Link> 的等待(pending)状态。当导航完成时,你可以用它提供细微的行内反馈,例如在被点击的链接上显示微光效果。更推荐的做法是使用 loading.js 提供路由级别的回退,并使用预取来实现即时切换。

在以下情况下,useLinkStatus 很有用:

  • 预取被禁用或正在进行中,意味着导航被阻塞。
  • 目标路由是动态的,并且没有包含允许即时导航的 loading.js 文件。
app/hint.tsx
'use client'

import Link from 'next/link'
import { useLinkStatus } from 'next/link'

function Hint() {
  const { pending } = useLinkStatus()
  return (
    <span aria-hidden className={`link-hint ${pending ? 'is-pending' : ''}`} />
  )
}

export default function Header() {
  return (
    <header>
      <Link href="/dashboard" prefetch={false}>
        <span className="label">Dashboard</span> <Hint />
      </Link>
    </header>
  )
}
app/hint.js
'use client'

import Link from 'next/link'
import { useLinkStatus } from 'next/link'

function Hint() {
  const { pending } = useLinkStatus()
  return (
    <span aria-hidden className={`link-hint ${pending ? 'is-pending' : ''}`} />
  )
}

export default function Header() {
  return (
    <header>
      <Link href="/dashboard" prefetch={false}>
        <span className="label">Dashboard</span> <Hint />
      </Link>
    </header>
  )
}

小知识:

  • useLinkStatus 必须在 Link 组件的后代组件中使用
  • 当 Link 组件上设置了 prefetch={false} 时,该 hook 最有用
  • 如果链接的路由已被预取,等待状态会被跳过
  • 快速连续点击多个链接时,只显示最后一个链接的等待状态
  • Pages Router 不支持该 hook,它始终返回 { pending: false }
  • 行内指示器很容易引起布局偏移。最好使用固定大小、始终渲染的提示元素并切换其不透明度,或者使用动画。

你可能不需要 useLinkStatus#

在添加行内反馈之前,请考虑:

  • 目标是否在生产环境中是静态的且已被预取,因此等待阶段可能会被跳过。
  • 路由是否有 loading.js 文件,从而通过路由级别的回退实现即时切换。

导航通常很快。当你发现某个切换较慢时,可以用 useLinkStatus 作为快速补救措施,然后迭代改进,通过预取或 loading.js 回退来解决根本原因。

参数#

tsx
const { pending } = useLinkStatus()

useLinkStatus 不接受任何参数。

返回值#

useLinkStatus 返回一个只包含一个属性的对象:

属性类型描述
pendingboolean在历史记录更新前为 true,更新后为 false

示例#

行内链接提示#

添加一个细微的、固定大小且不影响布局的提示,以便在预取尚未完成时确认点击。

app/components/loading-indicator.tsx
'use client'

import { useLinkStatus } from 'next/link'

export default function LoadingIndicator() {
  const { pending } = useLinkStatus()
  return (
    <span aria-hidden className={`link-hint ${pending ? 'is-pending' : ''}`} />
  )
}
app/components/loading-indicator.js
'use client'

import { useLinkStatus } from 'next/link'

export default function LoadingIndicator() {
  const { pending } = useLinkStatus()
  return (
    <span aria-hidden className={`link-hint ${pending ? 'is-pending' : ''}`} />
  )
}
app/shop/layout.tsx
import Link from 'next/link'
import LoadingIndicator from './components/loading-indicator'

const links = [
  { href: '/shop/electronics', label: 'Electronics' },
  { href: '/shop/clothing', label: 'Clothing' },
  { href: '/shop/books', label: 'Books' },
]

function Menubar() {
  return (
    <div>
      {links.map((link) => (
        <Link key={link.label} href={link.href}>
          <span className="label">{link.label}</span> <LoadingIndicator />
        </Link>
      ))}
    </div>
  )
}

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <Menubar />
      {children}
    </div>
  )
}
app/shop/layout.js
import Link from 'next/link'
import LoadingIndicator from './components/loading-indicator'

const links = [
  { href: '/shop/electronics', label: 'Electronics' },
  { href: '/shop/clothing', label: 'Clothing' },
  { href: '/shop/books', label: 'Books' },
]

function Menubar() {
  return (
    <div>
      {links.map((link) => (
        <Link key={link.label} href={link.href}>
          <span className="label">{link.label}</span> <LoadingIndicator />
        </Link>
      ))}
    </div>
  )
}

export default function Layout({ children }) {
  return (
    <div>
      <Menubar />
      {children}
    </div>
  )
}

优雅处理快速导航#

如果到新路由的导航很快,用户可能会看到提示不必要地闪烁一下。改善用户体验、只在导航需要时间完成时才显示提示的一种方法是添加初始动画延迟(例如 100ms),并让动画以不可见状态开始(例如 opacity: 0)。

app/styles/global.css
.link-hint {
  display: inline-block;
  width: 0.6em;
  height: 0.6em;
  margin-left: 0.25rem;
  border-radius: 9999px;
  background: currentColor;
  opacity: 0;
  visibility: hidden; /* 保留空间但不显示提示 */
}

.link-hint.is-pending {
  /* 动画 1:100ms 后淡入并保持最终透明度 */
  /* 动画 2:等待时的细微脉冲效果 */
  visibility: visible;
  animation-name: fadeIn, pulse;
  animation-duration: 200ms, 1s;
  /* 仅在导航确实需要时间时才出现 */
  animation-delay: 100ms, 100ms;
  animation-timing-function: ease, ease-in-out;
  animation-iteration-count: 1, infinite;
  animation-fill-mode: forwards, none;
}

@keyframes fadeIn {
  to {
    opacity: 0.35;
  }
}
@keyframes pulse {
  50% {
    opacity: 0.15;
  }
}

版本历史#

版本变更
v15.3.0引入 useLinkStatus。
Next.js 中文网