跳到主要内容

generateViewport

你可以使用静态 viewport 对象或动态 generateViewport 函数来自定义页面的初始视口。

提示：

  • viewport 对象和 generateViewport 函数的导出仅在服务端组件中支持。
  • 你不能从同一路由段导出 viewport 对象和 generateViewport 函数。
  • 如果你正在从迁移 metadata 导出，可以使用 metadata-to-viewport-export codemod 来更新你的更改。

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

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

提示：

  • 如果视口不依赖于运行时信息，应该使用静态 viewport 对象 而不是 generateViewport 来定义。

视口字段​

themeColor​

了解更多关于 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" />

带媒体属性

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" />

width、initialScale、maximumScale 和 userScalable​

提示：viewport meta 标签会自动设置，通常不需要手动配置，因为默认值就足够了。但是，为了完整性提供了这些信息。

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

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // 也支持但较少使用
  // interactiveWidget: 'resizes-visual',
}
layout.jsx | page.jsx
export const viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // 也支持但较少使用
  // interactiveWidget: 'resizes-visual',
}
<head> output
<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
/>

colorScheme​

了解更多关于 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" />

类型​

你可以通过使用 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。
最后于 更新