生成视口 | DevRefinery

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

须知：

viewport 对象和 generateViewport 函数的导出仅在服务端组件中支持。

您不能在同一个路由段中同时导出 viewport 对象和 generateViewport 函数。

如果您是从迁移 metadata 导出过来的，可以使用 metadata-to-viewport-export codemod 来更新您的更改。

`viewport` 对象

要定义视口选项，请从 layout.jsx 或 page.jsx 文件中导出一个 viewport 对象。

tsx

import type { Viewport } from 'next'

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

export default function Page() {}

jsx

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

export default function Page() {}

`generateViewport` 函数

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

tsx

export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

在 TypeScript 中，params 参数可以通过 PageProps<'/route'> 或 LayoutProps<'/route'> 进行类型定义，具体取决于 generateViewport 的定义位置。

jsx

export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

须知：

如果视口不依赖运行时信息，则应使用静态 viewport 对象而非 generateViewport 来定义它。

视口字段

`themeColor`

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

简单的主题颜色

tsx

import type { Viewport } from 'next'

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

jsx

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

html

<meta name="theme-color" content="black" />

带 media 属性

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' },
  ],
}

jsx

export const viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}

html

<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 标签是自动设置的，通常不需要手动配置，因为默认值已足够。然而，提供此信息是为了内容的完整性。

tsx

import type { Viewport } from 'next'

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // Also supported but less commonly used
  // interactiveWidget: 'resizes-visual',
}

jsx

export const viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // Also supported but less commonly used
  // interactiveWidget: 'resizes-visual',
}

html

<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
/>

`colorScheme`

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

tsx

import type { Viewport } from 'next'

export const viewport: Viewport = {
  colorScheme: 'dark',
}

jsx

export const viewport = {
  colorScheme: 'dark',
}

html

<meta name="color-scheme" content="dark" />

类型

您可以使用 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',
  }
}

带分段属性

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

javascript

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

版本历史

版本	更改
`v14.0.0`	引入了 `viewport` 和 `generateViewport`。

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

须知：

viewport 对象和 generateViewport 函数的导出仅在服务端组件中支持。

您不能在同一个路由段中同时导出 viewport 对象和 generateViewport 函数。

如果您是从迁移 metadata 导出过来的，可以使用 metadata-to-viewport-export codemod 来更新您的更改。

`viewport` 对象

要定义视口选项，请从 layout.jsx 或 page.jsx 文件中导出一个 viewport 对象。

tsx

import type { Viewport } from 'next'

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

export default function Page() {}

jsx

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

export default function Page() {}

`generateViewport` 函数

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

tsx

export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

在 TypeScript 中，params 参数可以通过 PageProps<'/route'> 或 LayoutProps<'/route'> 进行类型定义，具体取决于 generateViewport 的定义位置。

jsx

export function generateViewport({ params }) {
  return {
    themeColor: '...',
  }
}

须知：

如果视口不依赖运行时信息，则应使用静态 viewport 对象而非 generateViewport 来定义它。

视口字段

`themeColor`

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

简单的主题颜色

tsx

import type { Viewport } from 'next'

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

jsx

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

html

<meta name="theme-color" content="black" />

带 media 属性

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' },
  ],
}

jsx

export const viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: 'cyan' },
    { media: '(prefers-color-scheme: dark)', color: 'black' },
  ],
}

html

<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 标签是自动设置的，通常不需要手动配置，因为默认值已足够。然而，提供此信息是为了内容的完整性。

tsx

import type { Viewport } from 'next'

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // Also supported but less commonly used
  // interactiveWidget: 'resizes-visual',
}

jsx

export const viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // Also supported but less commonly used
  // interactiveWidget: 'resizes-visual',
}

html

<meta
  name="viewport"
  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
/>

`colorScheme`

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

tsx

import type { Viewport } from 'next'

export const viewport: Viewport = {
  colorScheme: 'dark',
}

jsx

export const viewport = {
  colorScheme: 'dark',
}

html

<meta name="color-scheme" content="dark" />

类型

`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',
  }
}

带分段属性

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

javascript

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

版本历史

版本	更改
`v14.0.0`	引入了 `viewport` 和 `generateViewport`。

文档导航

viewport 对象

generateViewport 函数

视口字段

themeColor

width、initialScale、maximumScale 和 userScalable

colorScheme

类型

viewport 对象

generateViewport 函数

常规函数

带分段属性

JavaScript 项目

版本历史

viewport 对象

generateViewport 函数

视口字段

themeColor

width、initialScale、maximumScale 和 userScalable

colorScheme

类型

viewport 对象

generateViewport 函数

常规函数

带分段属性

JavaScript 项目

版本历史

`viewport` 对象

`generateViewport` 函数

`themeColor`

`width`、`initialScale`、`maximumScale` 和 `userScalable`

`colorScheme`

`viewport` 对象

`generateViewport` 函数

`viewport` 对象

`generateViewport` 函数

`themeColor`

`width`、`initialScale`、`maximumScale` 和 `userScalable`

`colorScheme`

`viewport` 对象

`generateViewport` 函数