ImageResponse

Der ImageResponse-Konstruktor ermöglicht die Generierung dynamischer Bilder mit JSX und CSS. Dies ist nützlich für die Erstellung von Social-Media-Bildern wie Open-Graph-Bilder, Twitter-Karten und mehr.

Referenz

Parameter

Für ImageResponse stehen folgende Parameter zur Verfügung:

import { ImageResponse } from 'next/og'

new ImageResponse(
  element: ReactElement,
  options: {
    width?: number = 1200
    height?: number = 630
    emoji?: 'twemoji' | 'blobmoji' | 'noto' | 'openmoji' = 'twemoji',
    fonts?: {
      name: string,
      data: ArrayBuffer,
      weight: number,
      style: 'normal' | 'italic'
    }[]
    debug?: boolean = false

    // Optionen, die an die HTTP-Antwort übergeben werden
    status?: number = 200
    statusText?: string
    headers?: Record<string, string>
  },
)

Beispiele sind im Vercel OG Playground verfügbar.

Unterstützte HTML- und CSS-Funktionen

ImageResponse unterstützt gängige CSS-Eigenschaften inklusive Flexbox und absolute Positionierung, benutzerdefinierte Schriftarten, Textumbruch, Zentrierung und verschachtelte Bilder.

Eine Liste der unterstützten HTML- und CSS-Funktionen finden Sie in der Satori-Dokumentation.

Verhalten

ImageResponse verwendet @vercel/og, Satori und Resvg, um HTML und CSS in PNG umzuwandeln.
Nur Flexbox und eine Teilmenge von CSS-Eigenschaften werden unterstützt. Erweiterte Layouts (z.B. display: grid) funktionieren nicht.
Maximale Bundle-Größe von 500KB. Die Bundle-Größe umfasst Ihr JSX, CSS, Schriftarten, Bilder und andere Assets. Wenn Sie das Limit überschreiten, sollten Sie die Größe der Assets reduzieren oder sie zur Laufzeit abrufen.
Nur die Schriftformate ttf, otf und woff werden unterstützt. Um die Geschwindigkeit der Schriftanalyse zu maximieren, sind ttf oder otf gegenüber woff zu bevorzugen.

Beispiele

Route Handler

ImageResponse kann in Route Handlern verwendet werden, um Bilder dynamisch zur Laufzeit einer Anfrage zu generieren.

app/api/route.js

import { ImageResponse } from 'next/og'

export async function GET() {
  try {
    return new ImageResponse(
      (
        <div
          style={{
            height: '100%',
            width: '100%',
            display: 'flex',
            flexDirection: 'column',
            alignItems: 'center',
            justifyContent: 'center',
            backgroundColor: 'white',
            padding: '40px',
          }}
        >
          <div
            style={{
              fontSize: 60,
              fontWeight: 'bold',
              color: 'black',
              textAlign: 'center',
            }}
          >
            Welcome to My Site
          </div>
          <div
            style={{
              fontSize: 30,
              color: '#666',
              marginTop: '20px',
            }}
          >
            Generated with Next.js ImageResponse
          </div>
        </div>
      ),
      {
        width: 1200,
        height: 630,
      }
    )
  } catch (e) {
    console.log(`${e.message}`)
    return new Response(`Failed to generate the image`, {
      status: 500,
    })
  }
}

Dateibasierte Metadaten

Sie können ImageResponse in einer opengraph-image.tsx-Datei verwenden, um Open-Graph-Bilder zur Build-Zeit oder dynamisch zur Laufzeit einer Anfrage zu generieren.

app/opengraph-image.tsx

import { ImageResponse } from 'next/og'

// Bild-Metadaten
export const alt = 'My site'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// Bildgenerierung
export default async function Image() {
  return new ImageResponse(
    (
      // ImageResponse JSX-Element
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        My site
      </div>
    ),
    // ImageResponse-Optionen
    {
      // Der Einfachheit halber können wir die exportierte opengraph-image
      // Größenkonfiguration wiederverwenden, um auch die Breite und Höhe von ImageResponse festzulegen.
      ...size,
    }
  )
}

Benutzerdefinierte Schriftarten

Sie können benutzerdefinierte Schriftarten in Ihrem ImageResponse verwenden, indem Sie ein fonts-Array in den Optionen bereitstellen.

app/opengraph-image.tsx

import { ImageResponse } from 'next/og'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

// Bild-Metadaten
export const alt = 'My site'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// Bildgenerierung
export default async function Image() {
  // Schriftarten laden, process.cwd() ist das Next.js-Projektverzeichnis
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )

  return new ImageResponse(
    (
      // ...
    ),
    // ImageResponse-Optionen
    {
      // Der Einfachheit halber können wir die exportierte opengraph-image
      // Größenkonfiguration wiederverwenden, um auch die Breite und Höhe von ImageResponse festzulegen.
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

Versionsverlauf

Version	Änderungen
`v14.0.0`	`ImageResponse` wurde von `next/server` nach `next/og` verschoben
`v13.3.0`	`ImageResponse` kann aus `next/server` importiert werden.
`v13.0.0`	`ImageResponse` wurde über das `@vercel/og`-Paket eingeführt.

On this page