NextJS中文文档 - Page

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

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

export default function Page({ params, searchParams }) {
  return <h1>我的页面</h1>
}

页面是服务器组件，但可以设置为客户端组件。

须知：

• 页面始终是路由子树的叶子节点。
• 除非嵌套在 pages 目录内，否则 .js、.jsx 或 .tsx 文件扩展名可用于页面。
• 允许使用 page.js 文件创建专用 UI，但不是必需的。特殊文件 可以独立存在。

Props

params（可选）

表示从根布局到当前页面的动态路由参数对象。

例如，如果文件路径是 app/shop/[slug]/[item]/page.js，对应的 URL 是 /shop/shoes/nike-air-max-97，那么 params 对象将是：

{ slug: 'shoes', item: 'nike-air-max-97' }

了解更多关于动态路由分段的信息。

searchParams（可选）

包含当前 URL 的搜索参数。

例如，对于 URL /shop?a=1&b=2，searchParams 将是：

{ a: '1', b: '2' }

其他例子：

URL	searchParams 对象
/shop	{}
/shop?a=1	{ a: '1' }
/shop?a=1&b=2	{ a: '1', b: '2' }
/shop?a=1&a=2	{ a: ['1', '2'] }

须知：

• searchParams 等同于通过解析 URL.search 得到的对象，但 Next.js 提供了自动解析。
• 与 params 不同，searchParams 包含当前 URL 的所有搜索参数，而不仅仅是当前段。
• 像其他页面 props 一样，你也可以使用 TypeScript 来设置 searchParams 的类型。

良好实践

页面间共享组件

当你在不同页面之间共享 UI 时，你可以创建自己的组件并在多个页面之间导入它们。

export default function Button() {
  return <button>点击我</button>
}

export default function Button() {
  return <button>点击我</button>
}

参考

Props

params（可选）

一个会解析成包含从根段到该页面的动态路由参数的对象的 Promise。

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
}

export default async function Page({ params }) {
  const { slug } = await params
}

示例路由	URL	params
app/shop/[slug]/page.js	/shop/1	Promise<{ slug: '1' }>
app/shop/[category]/[item]/page.js	/shop/1/2	Promise<{ category: '1', item: '2' }>
app/shop/[...slug]/page.js	/shop/1/2	Promise<{ slug: ['1', '2'] }>

• 由于 params 属性是一个 Promise，你必须使用 async/await 或 React 的 use 函数来访问其值。
  • 在版本 14 及更早版本中，params 是一个同步属性。为了帮助向后兼容，在 Next.js 15 中你仍然可以同步访问它，但这种行为将在未来被废弃。

searchParams（可选）

一个会解析成包含当前 URL 的搜索参数的对象的 Promise。例如：

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

export default async function Page({ searchParams }) {
  const filters = (await searchParams).filters
}

示例 URL	searchParams
/shop?a=1	Promise<{ a: '1' }>
/shop?a=1&b=2	Promise<{ a: '1', b: '2' }>
/shop?a=1&a=2	Promise<{ a: ['1', '2'] }>

• 由于 searchParams 属性是一个 Promise，你必须使用 async/await 或 React 的 use 函数来访问其值。
  • 在版本 14 及更早版本中，searchParams 是一个同步属性。为了帮助向后兼容，在 Next.js 15 中你仍然可以同步访问它，但这种行为将在未来被废弃。
• searchParams 是一个**动态 API，其值无法提前知道。使用它将使页面在请求时选择动态渲染**。
• searchParams 是一个普通的 JavaScript 对象，而不是 URLSearchParams 实例。

示例

基于 params 显示内容

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

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  return <h1>博客文章: {slug}</h1>
}

export default async function Page({ params }) {
  const { slug } = await params
  return <h1>博客文章: {slug}</h1>
}

使用 searchParams 处理筛选

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

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

  return (
    <div>
      <h1>产品列表</h1>
      <p>搜索查询: {query}</p>
      <p>当前页面: {page}</p>
      <p>排序顺序: {sort}</p>
    </div>
  )
}

export default async function Page({ searchParams }) {
  const { page = '1', sort = 'asc', query = '' } = await searchParams

  return (
    <div>
      <h1>产品列表</h1>
      <p>搜索查询: {query}</p>
      <p>当前页面: {page}</p>
      <p>排序顺序: {sort}</p>
    </div>
  )
}

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

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

'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)
}

'use client'

import { use } from 'react'

export default function Page({ params, searchParams }) {
  const { slug } = use(params)
  const { query } = use(searchParams)
}

版本历史

版本	变更
v15.0.RC	params 和 searchParams 现在是 Promise。提供了代码转换工具。
v13.0.0	引入 page。