nextjs-navigation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Link Component Prefetching Behavior

Link组件预取行为

Understanding prefetch Prop Values

理解prefetch属性值

The

prefetch

prop on Next.js

<Link>

components has three distinct behaviors in App Router:

prefetch={false}
- Completely disables prefetching, including on hover. This is a breaking change from Pages Router, where

prefetch={false}

would still prefetch on hover. Use this when you want to prevent any prefetching whatsoever.

tsx

<Link href="/dashboard" prefetch={false}>
  Dashboard
</Link>

prefetch={undefined}
(default) - Only prefetches static routes. Dynamic routes are not prefetched until navigation occurs. Use this default behavior when you have a mix of static and dynamic routes and want to optimize initial load performance.

prefetch={true}
- Prefetches both static and dynamic routes. Use this for critical navigation paths where you want to ensure the fastest possible navigation experience, even for dynamic content.

tsx

<Link href="/profile/[id]" prefetch={true}>
  User Profile
</Link>

Next.js

<Link>

组件的

prefetch

属性在App Router中有三种不同的行为：

prefetch={false}
- 完全禁用预取功能，包括悬停时的预取。这与Pages Router中的行为是破坏性变更，在Pages Router中

prefetch={false}

仍会在悬停时进行预取。当你想要完全阻止任何预取操作时使用此设置。

tsx

<Link href="/dashboard" prefetch={false}>
  Dashboard
</Link>

prefetch={undefined}
（默认值）- 仅对静态路由进行预取。动态路由在导航发生前不会被预取。当你同时拥有静态和动态路由，且希望优化初始加载性能时，使用此默认行为。

prefetch={true}
- 对静态和动态路由都进行预取。将其用于关键导航路径，以确保即使是动态内容也能获得最快的导航体验。

tsx

<Link href="/profile/[id]" prefetch={true}>
  User Profile
</Link>

Suspense Boundaries and Search Params

Suspense边界与搜索参数

Same-Page Navigation Issue

同页面导航问题

When navigating on the same page with only search parameter changes, Suspense boundaries do not re-trigger their loading states by default. This can create a poor user experience where the UI appears frozen during data refetching.

当仅修改搜索参数进行同页面导航时，Suspense边界默认不会重新触发其加载状态。这可能会导致在数据重新获取期间UI看起来处于冻结状态，带来不佳的用户体验。

Solution: Key-Based Suspense

解决方案：基于Key的Suspense配置

Force Suspense boundaries to show loading states during search param changes by providing a unique

key

prop that includes the changing search parameter:

tsx

// app/search/page.tsx
export default function SearchPage({ 
  searchParams 
}: { 
  searchParams: { q?: string } 
}) {
  return (
    <Suspense 
      key={searchParams.q} 
      fallback={<LoadingSpinner />}
    >
      <SearchResults query={searchParams.q} />
    </Suspense>
  )
}

The key change ensures React treats the Suspense boundary as a new instance, properly displaying the fallback during the transition.

通过提供包含变化搜索参数的唯一

key

属性，强制Suspense边界在搜索参数变化时显示加载状态：

tsx

// app/search/page.tsx
export default function SearchPage({ 
  searchParams 
}: { 
  searchParams: { q?: string } 
}) {
  return (
    <Suspense 
      key={searchParams.q} 
      fallback={<LoadingSpinner />}
    >
      <SearchResults query={searchParams.q} />
    </Suspense>
  )
}

该key的变更确保React将Suspense边界视为新实例，在过渡期间正确显示回退内容。

Type Safety

类型安全

Typing Page Props

为页面属性添加类型

Use the

PageProps

helper type to correctly type page component props in App Router:

tsx

import type { PageProps } from 'next'

export default function Page({ params, searchParams }: PageProps) {
  // params and searchParams are properly typed
}

This helper provides accurate types for the

params

and

searchParams

objects passed to page components, improving type safety and developer experience.

使用

PageProps

辅助类型为App Router中的页面组件属性正确添加类型：

tsx

import type { PageProps } from 'next'

export default function Page({ params, searchParams }: PageProps) {
  // params和searchParams已被正确添加类型
}

此辅助类型为传递给页面组件的

params

和

searchParams

对象提供准确的类型，提升类型安全性和开发者体验。

Component State Preservation

组件状态保留

cacheComponents Flag

cacheComponents实验性标志

When the

cacheComponents

experimental flag is enabled, Next.js leverages React's

<Activity>

component to maintain component state across client-side navigations:

tsx

// next.config.js
module.exports = {
  experimental: {
    cacheComponents: true
  }
}

This preserves component state (such as form inputs, scroll position, or local component state) when users navigate away and return, creating a more native app-like experience. The

<Activity>

component handles the state preservation automatically without requiring manual state management.

当启用

cacheComponents

实验性标志时，Next.js会利用React的

<Activity>

组件在客户端导航期间保持组件状态：

tsx

// next.config.js
module.exports = {
  experimental: {
    cacheComponents: true
  }
}

这会在用户离开并返回页面时保留组件状态（如表单输入、滚动位置或本地组件状态），创造更接近原生应用的体验。

<Activity>

组件会自动处理状态保留，无需手动进行状态管理。