opengraph-image et twitter-image

Les conventions de fichiers opengraph-image et twitter-image vous permettent de définir des images Open Graph et Twitter pour un segment de route.

Elles sont utiles pour définir les images qui apparaissent sur les réseaux sociaux et les applications de messagerie lorsqu'un utilisateur partage un lien vers votre site.

Il existe deux façons de définir les images Open Graph et Twitter :

Utilisation de fichiers image (.jpg, .png, .gif)
Utilisation de code pour générer des images (.js, .ts, .tsx)

Fichiers image (.jpg, .png, .gif)

Utilisez un fichier image pour définir l'image partagée d'un segment de route en plaçant un fichier image opengraph-image ou twitter-image dans le segment.

Next.js évaluera le fichier et ajoutera automatiquement les balises appropriées à l'élément <head> de votre application.

Convention de fichier	Types de fichiers pris en charge
`opengraph-image`	`.jpg`, `.jpeg`, `.png`, `.gif`
`twitter-image`	`.jpg`, `.jpeg`, `.png`, `.gif`
`opengraph-image.alt`	`.txt`
`twitter-image.alt`	`.txt`

`opengraph-image`

Ajoutez un fichier image opengraph-image.(jpg|jpeg|png|gif) à n'importe quel segment de route.

Sortie <head>

<meta property="og:image" content="<generated>" />
<meta property="og:image:type" content="<generated>" />
<meta property="og:image:width" content="<generated>" />
<meta property="og:image:height" content="<generated>" />

`twitter-image`

Ajoutez un fichier image twitter-image.(jpg|jpeg|png|gif) à n'importe quel segment de route.

Sortie <head>

<meta name="twitter:image" content="<generated>" />
<meta name="twitter:image:type" content="<generated>" />
<meta name="twitter:image:width" content="<generated>" />
<meta name="twitter:image:height" content="<generated>" />

`opengraph-image.alt.txt`

Ajoutez un fichier opengraph-image.alt.txt accompagnant dans le même segment de route que l'image opengraph-image.(jpg|jpeg|png|gif) pour son texte alternatif.

opengraph-image.alt.txt

À propos d'Acme

Sortie <head>

<meta property="og:image:alt" content="À propos d'Acme" />

`twitter-image.alt.txt`

Ajoutez un fichier twitter-image.alt.txt accompagnant dans le même segment de route que l'image twitter-image.(jpg|jpeg|png|gif) pour son texte alternatif.

twitter-image.alt.txt

À propos d'Acme

Sortie <head>

<meta property="twitter:image:alt" content="À propos d'Acme" />

Générer des images avec du code (.js, .ts, .tsx)

En plus d'utiliser des fichiers image littéraux, vous pouvez générer programmatiquement des images avec du code.

Générez l'image partagée d'un segment de route en créant une route opengraph-image ou twitter-image qui exporte par défaut une fonction.

Convention de fichier	Types de fichiers pris en charge
`opengraph-image`	`.js`, `.ts`, `.tsx`
`twitter-image`	`.js`, `.ts`, `.tsx`

Bon à savoir

Par défaut, les images générées sont optimisées statiquement (générées au moment de la construction et mises en cache) sauf si elles utilisent des fonctions dynamiques ou des données non mises en cache.

Vous pouvez générer plusieurs images dans le même fichier en utilisant generateImageMetadata.

La façon la plus simple de générer une image est d'utiliser l'API ImageResponse de next/og.

import { ImageResponse } from 'next/og'

// Configuration du segment de route
export const runtime = 'edge'

// Métadonnées de l'image
export const alt = 'À propos d'Acme'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// Génération de l'image
export default async function Image() {
  // Police
  const interSemiBold = fetch(
    new URL('./Inter-SemiBold.ttf', import.meta.url)
  ).then((res) => res.arrayBuffer())

  return new ImageResponse(
    (
      // Élément JSX ImageResponse
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        À propos d'Acme
      </div>
    ),
    // Options ImageResponse
    {
      // Par commodité, nous pouvons réutiliser la configuration de taille exportée
      // opengraph-image pour également définir la largeur et la hauteur de ImageResponse.
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: await interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

import { ImageResponse } from 'next/og'

// Configuration du segment de route
export const runtime = 'edge'

// Métadonnées de l'image
export const alt = 'À propos d'Acme'
export const size = {
  width: 1200,
  height: 630,
}

export const contentType = 'image/png'

// Génération de l'image
export default async function Image() {
  // Police
  const interSemiBold = fetch(
    new URL('./Inter-SemiBold.ttf', import.meta.url)
  ).then((res) => res.arrayBuffer())

  return new ImageResponse(
    (
      // Élément JSX ImageResponse
      <div
        style={{
          fontSize: 128,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        À propos d'Acme
      </div>
    ),
    // Options ImageResponse
    {
      // Par commodité, nous pouvons réutiliser la configuration de taille exportée
      // opengraph-image pour également définir la largeur et la hauteur de ImageResponse.
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: await interSemiBold,
          style: 'normal',
          weight: 400,
        },
      ],
    }
  )
}

Sortie <head>

<meta property="og:image" content="<generated>" />
<meta property="og:image:alt" content="À propos d'Acme" />
<meta property="og:image:type" content="image/png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

Props

La fonction exportée par défaut reçoit les props suivantes :

`params` (optionnel)

Un objet contenant les paramètres de route dynamique du segment racine jusqu'au segment où opengraph-image ou twitter-image est colocalisé.

export default function Image({ params }: { params: { slug: string } }) {
  // ...
}

export default function Image({ params }) {
  // ...
}

Route	URL	`params`
`app/shop/opengraph-image.js`	`/shop`	`undefined`
`app/shop/[slug]/opengraph-image.js`	`/shop/1`	`{ slug: '1' }`
`app/shop/[tag]/[item]/opengraph-image.js`	`/shop/1/2`	`{ tag: '1', item: '2' }`
`app/shop/[...slug]/opengraph-image.js`	`/shop/1/2`	`{ slug: ['1', '2'] }`

Retour

Bon à savoir : ImageResponse satisfait ce type de retour.

Exports de configuration

Vous pouvez optionnellement configurer les métadonnées de l'image en exportant les variables alt, size et contentType depuis la route opengraph-image ou twitter-image.

Option	Type
`alt`	`string`
`size`	`{ width: number; height: number }`
`contentType`	`string` - type MIME d'image

`alt`

export const alt = 'Texte alternatif de mon image'

export default function Image() {}

export const alt = 'Texte alternatif de mon image'

export default function Image() {}

Sortie <head>

<meta property="og:image:alt" content="Texte alternatif de mon image" />

`size`

export const size = { width: 1200, height: 630 }

export default function Image() {}

export const size = { width: 1200, height: 630 }

export default function Image() {}

Sortie <head>

<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

`contentType`

export const contentType = 'image/png'

export default function Image() {}

export const contentType = 'image/png'

export default function Image() {}

Sortie <head>

<meta property="og:image:type" content="image/png" />

Configuration du segment de route

opengraph-image et twitter-image sont des Route Handlers spécialisés qui peuvent utiliser les mêmes options de configuration de segment de route que les Pages et Layouts.

Option	Type	Par défaut
`dynamic`	`'auto' \| 'force-dynamic' \| 'error' \| 'force-static'`	`'auto'`
`revalidate`	`false \| 'force-cache' \| 0 \| number`	`false`
`runtime`	`'nodejs' \| 'edge'`	`'nodejs'`
`preferredRegion`	`'auto' \| 'global' \| 'home' \| string \| string[]`	`'auto'`

export const runtime = 'edge'

export default function Image() {}

export const runtime = 'edge'

export default function Image() {}

Exemples

Utilisation de données externes

Cet exemple utilise l'objet params et des données externes pour générer l'image.

Bon à savoir : Par défaut, cette image générée sera optimisée statiquement. Vous pouvez configurer les options individuelles de fetch ou les options des segments de route pour modifier ce comportement.

import { ImageResponse } from 'next/og'

export const runtime = 'edge'

export const alt = 'À propos d'Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'

export default async function Image({ params }: { params: { slug: string } }) {
  const post = await fetch(`https://.../posts/${params.slug}`).then((res) =>
    res.json()
  )

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 48,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    ),
    {
      ...size,
    }
  )
}

import { ImageResponse } from 'next/og'

export const runtime = 'edge'

export const alt = 'À propos d'Acme'
export const size = {
  width: 1200,
  height: 630,
}
export const contentType = 'image/png'

export default async function Image({ params }) {
  const post = await fetch(`https://.../posts/${params.slug}`).then((res) =>
    res.json()
  )

  return new ImageResponse(
    (
      <div
        style={{
          fontSize: 48,
          background: 'white',
          width: '100%',
          height: '100%',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        {post.title}
      </div>
    ),
    {
      ...size,
    }
  )
}

Historique des versions

Version	Changements
`v13.3.0`	Introduction de `opengraph-image` et `twitter-image`.

opengraph-image et twitter-image

On this page