generateViewport
generateViewport 函数的 API 参考。
你可以使用静态的 viewport 对象或动态的 generateViewport 函数来自定义页面的初始 viewport。
小知识:
viewport对象和generateViewport函数的导出仅在 Server Components 中受支持。- 你不能从同一个路由片段中同时导出
viewport对象和generateViewport函数。- 如果你是从迁移
metadata导出过来的,可以使用 metadata-to-viewport-export codemod 来更新你的更改。
viewport 对象#
要定义 viewport 选项,请从 layout.jsx 或 page.jsx 文件中导出一个 viewport 对象。
import type { Viewport } from 'next'
export const viewport: Viewport = {
themeColor: 'black',
}
export default function Page() {}export const viewport = {
themeColor: 'black',
}
export default function Page() {}generateViewport 函数#
generateViewport 应返回一个包含一个或多个 viewport 字段的 Viewport 对象。
export function generateViewport({ params }) {
return {
themeColor: '...',
}
}在 TypeScript 中,根据 generateViewport 的定义位置,params 参数可以通过 PageProps<'/route'> 或 LayoutProps<'/route'> 来指定类型。
export function generateViewport({ params }) {
return {
themeColor: '...',
}
}小知识:
- 如果 viewport 不依赖请求信息,应使用静态的
viewport对象而非generateViewport来定义它。
Viewport 字段#
Viewport 字段用于配置 viewport、主题颜色和配色方案的 meta 标签。
themeColor#
themeColor 设置 theme-color meta 标签。使用媒体查询为不同条件提供不同的颜色。
了解更多关于 theme-color 的信息。
简单的主题颜色
import type { Viewport } from 'next'
export const viewport: Viewport = {
themeColor: 'black',
}export const viewport = {
themeColor: 'black',
}<meta name="theme-color" content="black" />带 media 属性
import type { Viewport } from 'next'
export const viewport: Viewport = {
themeColor: [
{ media: '(prefers-color-scheme: light)', color: 'cyan' },
{ media: '(prefers-color-scheme: dark)', color: 'black' },
],
}export const viewport = {
themeColor: [
{ media: '(prefers-color-scheme: light)', color: 'cyan' },
{ media: '(prefers-color-scheme: dark)', color: 'black' },
],
}<meta name="theme-color" media="(prefers-color-scheme: light)" content="cyan" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black" />themeColor 接受颜色字符串、{ color: string, media?: string } 描述符,或描述符数组。
width、initialScale、maximumScale 和 userScalable#
Next.js 默认设置 width: 'device-width' 和 initialScale: 1。viewport 导出或 generateViewport 返回值仅覆盖其提供的字段。省略的字段保留继承值或默认值。要移除默认的 initial-scale 指令,请设置 initialScale: undefined。
import type { Viewport } from 'next'
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
maximumScale: 1,
userScalable: false,
}export const viewport = {
width: 'device-width',
initialScale: 1,
maximumScale: 1,
userScalable: false,
}<meta
name="viewport"
content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
/>Next.js 接受这些布局字段。有关指令含义和浏览器支持情况,请参阅viewport 参考。
| 字段 | 可接受的输入 |
|---|---|
width, height | string 或 number |
initialScale, minimumScale, maximumScale | number |
userScalable | boolean(发出 yes 或 no) |
viewportFit | 'auto'、'contain' 或 'cover' |
interactiveWidget | 'resizes-visual'、'resizes-content' 或 'overlays-content' |
viewportFit#
viewportFit 在 viewport meta 标签中设置 viewport-fit 指令。
使用 'cover' 填满设备显示屏。使用 CSS 安全区域内嵌变量使内容避开屏幕挖孔区域。
import type { Viewport } from 'next'
export const viewport: Viewport = {
viewportFit: 'cover',
}export const viewport = {
viewportFit: 'cover',
}保留默认的 width 和 initialScale 值:
<meta
name="viewport"
content="width=device-width, initial-scale=1, viewport-fit=cover"
/>colorScheme#
colorScheme 设置 color-scheme meta 标签。
了解更多关于 color-scheme 的信息。
import type { Viewport } from 'next'
export const viewport: Viewport = {
colorScheme: 'dark',
}export const viewport = {
colorScheme: 'dark',
}<meta name="color-scheme" content="dark" />colorScheme 接受 'normal'、'light'、'dark'、'light dark'、'dark light' 或 'only light'。
配合 Cache Components 使用#
当启用 Cache Components 时,generateViewport 遵循与其他组件相同的规则。如果 viewport 访问运行时数据(cookies()、headers()、params、searchParams)或执行未缓存的数据获取,则会推迟到请求时处理。
与 metadata 不同,viewport 无法流式传输,因为它会影响页面初始加载的 UI。如果 generateViewport 推迟到请求时处理,页面将需要阻塞等待其解析完成。
如果 viewport 依赖外部数据但不依赖运行时数据,请使用 use cache:
export async function generateViewport() {
'use cache'
const { width, initialScale } = await db.query('viewport-size')
return { width, initialScale }
}如果 viewport 确实需要运行时数据,请将文档 <body> 包裹在 <Suspense> 边界中,以表明整条路由应为动态。shell 会立即发送,文档会在 viewport 解析完成后流式传入:
import { Suspense } from 'react'
import { cookies } from 'next/headers'
export async function generateViewport() {
const cookieJar = await cookies()
return {
themeColor: cookieJar.get('theme-color')?.value,
}
}
export default function RootLayout({ children }) {
return (
<Suspense>
<html>
<body>{children}</body>
</html>
</Suspense>
)
}或者,使用 instant = false 让该片段退出即时导航验证。该路由会在每个请求上渲染,导航会阻塞直到渲染完成:
import { cookies } from 'next/headers'
export const instant = false
export async function generateViewport() {
const cookieJar = await cookies()
return {
themeColor: cookieJar.get('theme-color')?.value,
}
}
export default function DashboardLayout({ children }) {
return <section>{children}</section>
}设置 instant = false 只会让导出它的片段退出。后代片段仍会按全局默认值进行验证。有关完整的修复选项、权衡以及子树范围的退出方式,请参阅 Next.js 在 generateViewport() 中遇到运行时数据。
小知识:使用多个根布局将完全动态的 viewport 隔离到特定路由,同时仍让应用程序中的其他路由生成静态 shell。
类型#
你可以使用 Viewport 类型为 viewport 对象添加类型安全。如果你在 IDE 中使用内置 TypeScript 插件,则无需手动添加该类型,但如果需要,仍可以显式添加。
viewport 对象#
import type { Viewport } from 'next'
export const viewport: Viewport = {
themeColor: 'black',
}generateViewport 函数#
普通函数#
import type { Viewport } from 'next'
export function generateViewport(): Viewport {
return {
themeColor: 'black',
}
}带片段 props#
import type { Viewport } from 'next'
type Props = {
params: Promise<{ id: string }>
searchParams: Promise<{ [key: string]: string | string[] | undefined }>
}
export function generateViewport({ params, searchParams }: Props): Viewport {
return {
themeColor: 'black',
}
}
export default function Page({ params, searchParams }: Props) {}JavaScript 项目#
对于 JavaScript 项目,你可以使用 JSDoc 来添加类型安全。
/** @type {import("next").Viewport} */
export const viewport = {
themeColor: 'black',
}版本历史#
| 版本 | 更改 |
|---|---|
v14.0.0 | 引入 viewport 和 generateViewport。 |