page.js
page.js 文件的 API 参考。
page 文件允许你定义对某个路由唯一的 UI。你可以通过从文件中默认导出一个组件来创建页面:
app/blog/[slug]/page.tsx
export default function Page({
params,
searchParams,
}: {
params: Promise<{ slug: string }>
searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
return <h1>My Page</h1>
}app/blog/[slug]/page.js
export default function Page({ params, searchParams }) {
return <h1>My Page</h1>
}小知识#
page可以使用.js、.jsx或.tsx文件扩展名。page始终是路由子树的叶子节点。- 要使路由段可公开访问,必须有
page文件。 - 页面默认是 Server Components,但可以设置为 Client Component。
- 在组件层级中,
page.js是最内层的 file convention。在同一段中,它被loading.js(Suspense 边界)、error.js(错误边界)、template.js和layout.js包裹。
参考#
Props#
params(可选)#
一个 promise,解析为一个对象,其中包含从根段到该页面的动态路由参数。
app/shop/[slug]/page.tsx
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
}app/shop/[slug]/page.js
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'] }> |
- 由于
paramsprop 是一个 promise,你必须使用async/await或 React 的use函数来访问这些值。- 在版本 14 及更早版本中,
params是同步 prop。为了帮助向后兼容,在 Next.js 15 中你仍然可以同步访问它,但此行为将来会被弃用。
- 在版本 14 及更早版本中,
searchParams(可选)#
一个 promise,解析为一个对象,其中包含当前 URL 的搜索参数。例如:
app/shop/page.tsx
export default async function Page({
searchParams,
}: {
searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
const filters = (await searchParams).filters
}app/shop/page.js
export default async function Page({ searchParams }) {
const filters = (await searchParams).filters
}Client Component 页面也可以使用 React 的 use Hook 访问 searchParams:
app/shop/page.tsx
'use client'
import { use } from 'react'
export default function Page({
searchParams,
}: {
searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}) {
const filters = use(searchParams).filters
}app/page.jsx
'use client'
import { use } from 'react'
export default function Page({ searchParams }) {
const filters = use(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'] }> |
- 由于
searchParamsprop 是一个 promise。你必须使用async/await或 React 的use函数来访问这些值。- 在版本 14 及更早版本中,
searchParams是同步 prop。为了帮助向后兼容,在 Next.js 15 中你仍然可以同步访问它,但此行为将来会被弃用。
- 在版本 14 及更早版本中,
searchParams是一个 Request-time API,其值无法提前得知。使用它会让页面在请求时选择 dynamic rendering。- 使用 Cache Components 时,在组件树中访问
searchParams的位置决定了页面中有多少内容可以预渲染。请参阅最大化静态外壳。 searchParams是一个普通的 JavaScript 对象,不是URLSearchParams实例。
Page Props 辅助工具#
你可以使用 PageProps 为页面定义类型,从路由字面量中获得强类型的 params 和 searchParams。PageProps 是一个全局可用的辅助工具。
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辅助工具即可全局使用。无需导入。
示例#
基于 params 显示内容#
使用动态路由段,你可以根据 params prop 为页面显示或获取特定内容。
app/blog/[slug]/page.tsx
export default async function Page({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
return <h1>Blog Post: {slug}</h1>
}app/blog/[slug]/page.js
export default async function Page({ params }) {
const { slug } = await params
return <h1>Blog Post: {slug}</h1>
}使用 searchParams 处理过滤#
你可以使用 searchParams prop 根据 URL 的查询字符串处理过滤、分页或排序。
app/shop/page.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>
)
}app/shop/page.js
export default async function Page({ searchParams }) {
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
'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)
}app/page.js
'use client'
import { use } from 'react'
export default function Page({ params, searchParams }) {
const { slug } = use(params)
const { query } = use(searchParams)
}版本历史#
| 版本 | 变更 |
|---|---|
v15.0.0-RC | params 和 searchParams 现在是 promise。可以使用 codemod。 |
v13.0.0 | 引入 page。 |