NextJS中文文档 - Generate Viewport
你可以使用静态的 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() {}
1
2
3
4
5
6
7
2
3
4
5
6
7
jsx
export const viewport = {
themeColor: 'black',
}
export default function Page() {}
1
2
3
4
5
2
3
4
5
generateViewport
函数
generateViewport
应返回一个包含一个或多个视口字段的 Viewport
对象。
tsx
export function generateViewport({ params }) {
return {
themeColor: '...',
}
}
1
2
3
4
5
2
3
4
5
jsx
export function generateViewport({ params }) {
return {
themeColor: '...',
}
}
1
2
3
4
5
2
3
4
5
须知:
- 如果视口不依赖运行时信息,则应该使用静态
viewport
对象而不是generateViewport
来定义。
视口字段
themeColor
了解更多关于 theme-color
的信息。
简单主题颜色
tsx
import type { Viewport } from 'next'
export const viewport: Viewport = {
themeColor: 'black',
}
1
2
3
4
5
2
3
4
5
jsx
export const viewport = {
themeColor: 'black',
}
1
2
3
2
3
html
<meta name="theme-color" content="black" />
1
带媒体属性
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' },
],
}
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
jsx
export const viewport = {
themeColor: [
{ media: '(prefers-color-scheme: light)', color: 'cyan' },
{ media: '(prefers-color-scheme: dark)', color: 'black' },
],
}
1
2
3
4
5
6
2
3
4
5
6
html
<meta name="theme-color" media="(prefers-color-scheme: light)" content="cyan" />
<meta name="theme-color" media="(prefers-color-scheme: dark)" content="black" />
1
2
2
width
、initialScale
、maximumScale
和 userScalable
须知:
viewport
元标签会自动设置,通常不需要手动配置,因为默认设置已经足够。但为了完整性,提供以下信息。
tsx
import type { Viewport } from 'next'
export const viewport: Viewport = {
width: 'device-width',
initialScale: 1,
maximumScale: 1,
userScalable: false,
// 也支持但不常用
// interactiveWidget: 'resizes-visual',
}
1
2
3
4
5
6
7
8
9
10
2
3
4
5
6
7
8
9
10
jsx
export const viewport = {
width: 'device-width',
initialScale: 1,
maximumScale: 1,
userScalable: false,
// 也支持但不常用
// interactiveWidget: 'resizes-visual',
}
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
html
<meta
name="viewport"
content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
/>
1
2
3
4
2
3
4
colorScheme
了解更多关于 color-scheme
的信息。
tsx
import type { Viewport } from 'next'
export const viewport: Viewport = {
colorScheme: 'dark',
}
1
2
3
4
5
2
3
4
5
jsx
export const viewport = {
colorScheme: 'dark',
}
1
2
3
2
3
html
<meta name="color-scheme" content="dark" />
1
类型
你可以使用 Viewport
类型为你的视口对象添加类型安全。如果你在 IDE 中使用内置 TypeScript 插件,则不需要手动添加类型,但你仍然可以明确添加。
viewport
对象
tsx
import type { Viewport } from 'next'
export const viewport: Viewport = {
themeColor: 'black',
}
1
2
3
4
5
2
3
4
5
generateViewport
函数
常规函数
tsx
import type { Viewport } from 'next'
export function generateViewport(): Viewport {
return {
themeColor: 'black',
}
}
1
2
3
4
5
6
7
2
3
4
5
6
7
带段参数
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) {}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
2
3
4
5
6
7
8
9
10
11
12
13
14
JavaScript 项目
对于 JavaScript 项目,你可以使用 JSDoc 添加类型安全。
js
/** @type {import("next").Viewport} */
export const viewport = {
themeColor: 'black',
}
1
2
3
4
2
3
4
版本历史
版本 | 变更 |
---|---|
v14.0.0 | 引入 viewport 和 generateViewport 。 |