NNext.js 中文网 GitHub

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 对象。

layout.tsx | page.tsx
import type { Viewport } from 'next'

export const viewport: Viewport = {
  themeColor: 'black',
}

export default function Page() {}
layout.jsx | page.jsx
export const viewport = {
  themeColor: 'black',
}

export default function Page() {}

generateViewport 函数#

generateViewport 应返回一个包含一个或多个 viewport 字段的 Viewport 对象。

layout.tsx | page.tsx
export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

在 TypeScript 中,根据 generateViewport 的定义位置,params 参数可以通过 PageProps<'/route'> 或 LayoutProps<'/route'> 来指定类型。

layout.js | page.js
export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

小知识:

  • 如果 viewport 不依赖请求信息,应使用静态的 viewport 对象而非 generateViewport 来定义它。

Viewport 字段#

Viewport 字段用于配置 viewport、主题颜色和配色方案的 meta 标签。

themeColor#

themeColor 设置 theme-color meta 标签。使用媒体查询为不同条件提供不同的颜色。

了解更多关于 theme-color 的信息。

简单的主题颜色

layout.tsx | page.tsx
import type { Viewport } from 'next'

export const viewport: Viewport = {
  themeColor: 'black',
}
layout.jsx | page.jsx
export const viewport = {
  themeColor: 'black',
}
<head> output
<meta name="theme-color" content="black" />

带 media 属性

layout.tsx | page.tsx
import type { Viewport } from 'next'

export const viewport: Viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}
layout.jsx | page.jsx
export const viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}
<head> output
<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。

layout.tsx | page.tsx
import type { Viewport } from 'next'

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
}
layout.jsx | page.jsx
export const viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
}
<head> output
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
/>

Next.js 接受这些布局字段。有关指令含义和浏览器支持情况,请参阅viewport 参考。

字段可接受的输入
width, heightstring 或 number
initialScale, minimumScale, maximumScalenumber
userScalableboolean(发出 yes 或 no)
viewportFit'auto'、'contain' 或 'cover'
interactiveWidget'resizes-visual'、'resizes-content' 或 'overlays-content'

viewportFit#

viewportFit 在 viewport meta 标签中设置 viewport-fit 指令。

使用 'cover' 填满设备显示屏。使用 CSS 安全区域内嵌变量使内容避开屏幕挖孔区域。

layout.tsx | page.tsx
import type { Viewport } from 'next'

export const viewport: Viewport = {
  viewportFit: 'cover',
}
layout.jsx | page.jsx
export const viewport = {
  viewportFit: 'cover',
}

保留默认的 width 和 initialScale 值:

<head> output
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, viewport-fit=cover"
/>

colorScheme#

colorScheme 设置 color-scheme meta 标签。

了解更多关于 color-scheme 的信息。

layout.tsx | page.tsx
import type { Viewport } from 'next'

export const viewport: Viewport = {
  colorScheme: 'dark',
}
layout.jsx | page.jsx
export const viewport = {
  colorScheme: 'dark',
}
<head> output
<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:

app/layout.tsx
export async function generateViewport() {
  'use cache'
  const { width, initialScale } = await db.query('viewport-size')
  return { width, initialScale }
}

如果 viewport 确实需要运行时数据,请将文档 <body> 包裹在 <Suspense> 边界中,以表明整条路由应为动态。shell 会立即发送,文档会在 viewport 解析完成后流式传入:

app/layout.tsx
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 让该片段退出即时导航验证。该路由会在每个请求上渲染,导航会阻塞直到渲染完成:

app/dashboard/layout.tsx
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 对象#

tsx
import type { Viewport } from 'next'

export const viewport: Viewport = {
  themeColor: 'black',
}

generateViewport 函数#

普通函数#

tsx
import type { Viewport } from 'next'

export function generateViewport(): Viewport {
  return {
    themeColor: 'black',
  }
}

带片段 props#

tsx
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 来添加类型安全。

js
/** @type {import("next").Viewport} */
export const viewport = {
  themeColor: 'black',
}

版本历史#

版本更改
v14.0.0引入 viewport 和 generateViewport。
Next.js 中文网