Next.js 中文网

主题

page.js ​

page 文件允许你定义特定于路由的 UI。你可以通过默认从文件导出组件来创建页面：

¥The page file allows you to define UI that is unique to a route. You can create a page by default exporting a component from the file:

tsx
export default function Page({
  params,
  searchParams,
}: {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  return <h1>My Page</h1>
}

很高兴知道 ​

¥Good to know

  • .js、.jsx 或 .tsx 文件扩展名可用于 page。

    ¥The .js, .jsx, or .tsx file extensions can be used for page.

  • page 始终是路由子树的叶子。

    ¥A page is always the leaf of the route subtree.

  • 需要 page 文件才能公开访问路段。

    ¥A page file is required to make a route segment publicly accessible.

  • 默认情况下，页面为 服务器组件，但可以设置为 客户端组件。

    ¥Pages are Server Components by default, but can be set to a Client Component.

参考 ​

¥Reference

属性 ​

¥Props

params（可选） ​

¥params (optional)

从根段到该页面解析为包含 动态路由参数 的对象的 promise。

¥A promise that resolves to an object containing the dynamic route parameters from the root segment down to that page.

tsx
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
}
示例路由URLparams
app/shop/[slug]/page.js/shop/1Promise<{ slug: '1' }>
app/shop/[category]/[item]/page.js/shop/1/2Promise<{ category: '1', item: '2' }>
app/shop/[...slug]/page.js/shop/1/2Promise<{ slug: ['1', '2'] }>

  • 由于 params prop 是一个 promise，你必须使用 async/await 或 React 的 use 函数来访问这些值。

    ¥Since the params prop is a promise, you must use async/await or React's use function to access the values.

    • 在版本 14 及更早版本中，params 是一个同步 prop。为了帮助向后兼容，你仍然可以在 Next.js 15 中同步访问它，但此行为将来会被弃用。

      ¥In version 14 and earlier, params was a synchronous prop. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future.

searchParams（可选） ​

¥searchParams (optional)

解析为包含当前 URL 的 搜索参数 的对象的 promise。例如：

¥A promise that resolves to an object containing the search parameters of the current URL. For example:

tsx
export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const filters = (await searchParams).filters
}

客户端组件页面也可以使用 React 的 use 钩子访问 searchParams：

¥Client Component pages can also access searchParams using React’s use hook:

tsx
'use client'
import { use } from 'react'

export default function Page({
  searchParams,
}: {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const filters = use(searchParams).filters
}
示例 URLsearchParams
/shop?a=1Promise<{ a: '1' }>
/shop?a=1&b=2Promise<{ a: '1', b: '2' }>
/shop?a=1&a=2Promise<{ a: ['1', '2'] }>

  • 由于 searchParams prop 是一个 promise。你必须使用 async/await 或 React 的 use 函数来访问值。

    ¥Since the searchParams prop is a promise. You must use async/await or React's use function to access the values.

    • 在版本 14 及更早版本中，searchParams 是一个同步 prop。为了帮助向后兼容，你仍然可以在 Next.js 15 中同步访问它，但此行为将来会被弃用。

      ¥In version 14 and earlier, searchParams was a synchronous prop. To help with backwards compatibility, you can still access it synchronously in Next.js 15, but this behavior will be deprecated in the future.

  • searchParams 是一个 动态 API，其值无法提前得知。使用它会在请求时将页面选择为 动态渲染。

    ¥searchParams is a Dynamic API whose values cannot be known ahead of time. Using it will opt the page into dynamic rendering at request time.

  • searchParams 是一个普通的 JavaScript 对象，而不是 URLSearchParams 实例。

    ¥searchParams is a plain JavaScript object, not a URLSearchParams instance.

页面属性助手 ​

¥Page Props Helper

你可以使用 PageProps 键入页面，以从路由文字中获取强类型 params 和 searchParams。PageProps 是一个全局可用的辅助函数。

¥You can type pages with PageProps to get strongly typed params and searchParams from the route literal. PageProps is a globally available helper.

tsx
export default async function Page(props: PageProps<'/blog/[slug]'>) {
  const { slug } = await props.params
  const query = await props.searchParams
  return <h1>Blog Post: {slug}</h1>
}

很高兴知道

¥Good to know

  • 使用文字路由（例如 '/blog/[slug]'）会为 params 启用自动补齐和严格键值。

    ¥Using a literal route (e.g. '/blog/[slug]') enables autocomplete and strict keys for params.

  • 静态路由将 params 解析为 {}。

    ¥Static routes resolve params to {}.

  • 类型在 next dev、next build 或 next typegen 期间生成。

    ¥Types are generated during next dev, next build, or with next typegen.

示例 ​

¥Examples

基于 params 显示内容 ​

¥Displaying content based on params

使用 动态路由段，你可以根据 params 属性显示或获取页面的特定内容。

¥Using dynamic route segments, you can display or fetch specific content for the page based on the params prop.

tsx
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  return <h1>Blog Post: {slug}</h1>
}

使用 searchParams 处理过滤 ​

¥Handling filtering with searchParams

你可以使用 searchParams 属性根据 URL 的查询字符串处理过滤、分页或排序。

¥You can use the searchParams prop to handle filtering, pagination, or sorting based on the query string of the URL.

tsx
export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const { page = '1', sort = 'asc', query = '' } = await searchParams

  return (
    <div>
      <h1>Product Listing</h1>
      <p>Search query: {query}</p>
      <p>Current page: {page}</p>
      <p>Sort order: {sort}</p>
    </div>
  )
}

在客户端组件中读取 searchParams 和 params ​

¥Reading searchParams and params in Client Components

要在客户端组件（不能是 async）中使用 searchParams 和 params，你可以使用 React 的 use 函数来读取 promise：

¥To use searchParams and params in a Client Component (which cannot be async), you can use React's use function to read the promise:

tsx
'use client'

import { use } from 'react'

export default function Page({
  params,
  searchParams,
}: {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
  const { slug } = use(params)
  const { query } = use(searchParams)
}

版本历史 ​

¥Version History

版本更改
v15.0.0-RCparams 和 searchParams 现在是 promise。codemod 可用。
v13.0.0page 已引入。