generateViewport

您可以使用靜態的 viewport 物件或動態的 generateViewport 函式來自訂頁面的初始視窗設定。

須知事項:

viewport 物件和 generateViewport 函式匯出 僅在伺服器元件 (Server Components) 中支援。

您無法從同一個路由區段同時匯出 viewport 物件和 generateViewport 函式。

如果您是從遷移 metadata 匯出而來，可以使用 metadata-to-viewport-export codemod 來更新您的變更。

`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 物件。

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

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

須知事項:

如果視窗設定不依賴於執行時資訊，應使用靜態的 viewport 物件而非 generateMetadata 來定義。

視窗設定欄位

`themeColor`

了解更多關於 theme-color 的資訊。

簡單主題色

import type { Viewport } from 'next'

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

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

<head> output

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

<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 標籤會自動設定，通常不需要手動配置，因為預設值已足夠。但為了完整性，仍提供相關資訊。

import type { Viewport } from 'next'

export const viewport: Viewport = {
  width: 'device-width',
  initialScale: 1,
  maximumScale: 1,
  userScalable: false,
  // 較少使用的選項也支援
  // interactiveWidget: 'resizes-visual',
}

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 的資訊。

import type { Viewport } from 'next'

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

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

帶有區段屬性

import type { Viewport } from 'next'

type Props = {
  params: { id: string }
  searchParams: { [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` 功能。

中繼資料檔案

關於中繼資料檔案慣例的 API 文件。

中繼資料檔案

On this page