문서
App Router 사용하기
API 참조
함수
generateViewport

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: "...",
  };
}

알아두면 좋은 점:

  • 뷰포트가 런타임 정보에 의존하지 않는 경우, generateViewport 대신 정적 viewport 객체를 사용하여 정의해야 합니다.

뷰포트 필드

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

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

width, initialScale, maximumScale 및 userScalable

알아두면 좋은 점: viewport 메타 태그는 자동으로 설정되며, 일반적으로 기본값이 충분하므로 수동 구성이 필요하지 않습니다. 그러나 참고를 위해 이 정보를 제공합니다.

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: { 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.0viewport와 generateViewport가 도입되었습니다.
generateStaticParamsheaders