Menu

page.js

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

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

值得注意的是

  • .js、.jsx 或 .tsx 文件扩展名都可以用于 page。
  • page 始终是路由子树的叶子节点。
  • 需要 page 文件才能使路由段公开访问。
  • Pages 默认是 Server Components，但可以设置为 Client Component。

参考

Props

params（可选）

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

app/shop/[slug]/page.tsx
TypeScript
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 函数来访问值。
    • 在版本 14 及更早版本中，params 是一个同步 prop。为了帮助向后兼容，你仍然可以在 Next.js 15 中同步访问它，但此行为将在未来被弃用。

searchParams（可选）

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

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

Client Component pages 也可以使用 React 的 use hook 访问 searchParams：

app/shop/page.tsx
TypeScript
'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 函数来访问值。
    • 在版本 14 及更早版本中，searchParams 是一个同步 prop。为了帮助向后兼容，你仍然可以在 Next.js 15 中同步访问它，但此行为将在未来被弃用。
  • searchParams 是一个**动态 API，其值无法提前知道。使用它将使页面在请求时选择动态渲染**。
  • searchParams 是一个普通的 JavaScript 对象，而不是 URLSearchParams 实例。

Page Props Helper

你可以使用 PageProps 为页面添加类型，从路由字面量获取强类型的 params 和 searchParams。PageProps 是一个全局可用的 helper。

app/blog/[slug]/page.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>
}

值得注意的是

  • 使用字面量路由（例如 '/blog/[slug]'）可以为 params 启用自动完成和严格的键。
  • 静态路由将 params 解析为 {}。
  • 类型在 next dev、next build 或使用 next typegen 时生成。
  • 类型生成后，PageProps helper 全局可用。它不需要被导入。

示例

根据 params 显示内容

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

app/blog/[slug]/page.tsx
TypeScript
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  return <h1>Blog Post: {slug}</h1>
}

使用 searchParams 处理过滤

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

app/shop/page.tsx
TypeScript
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>
  )
}

在 Client Components 中读取 searchParams 和 params

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

app/page.tsx
TypeScript
'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)
}

版本历史

版本变更
v15.0.0-RCparams 和 searchParams 现在是 promises。可用的 codemod。
v13.0.0引入 page。