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`

Bon à savoir :

La taille du fichier twitter-image ne doit pas dépasser 5Mo, et la taille du fichier opengraph-image ne doit pas dépasser 8Mo. Si la taille de l'image dépasse ces limites, la construction échouera.

`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 APIs dynamiques ou des données non mises en cache.

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

opengraph-image.js et twitter-image.js sont des gestionnaires de route spéciaux qui sont mis en cache par défaut sauf s'ils utilisent une API dynamique ou une option de configuration dynamique.

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'
import { readFile } from 'node:fs/promises'
import { join } from 'node:path'

// 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() {
  // Chargement de la police, process.cwd() est le répertoire du projet Next.js
  const interSemiBold = await readFile(
    join(process.cwd(), 'assets/Inter-SemiBold.ttf')
  )

  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
    {
      // Pour plus de commodité, nous pouvons réutiliser la configuration de taille exportée
      // d'opengraph-image pour définir également la largeur et la hauteur de ImageResponse.
      ...size,
      fonts: [
        {
          name: 'Inter',
          data: 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 l'objet paramètres de route dynamique depuis le segment racine jusqu'au segment où opengraph-image ou twitter-image est colocalisé.

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

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

Retours

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() {}

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() {}

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() {}

Sortie <head>

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

Configuration du segment de route

opengraph-image et twitter-image sont des gestionnaires de route spécialisés qui peuvent utiliser les mêmes options de configuration de segment de route que les pages et les layouts.

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

Utilisation du runtime Node.js avec des ressources locales

Cet exemple utilise le runtime Node.js pour récupérer une image locale sur le système de fichiers et la passe en tant que ArrayBuffer à l'attribut src d'un élément <img>. La ressource locale doit être placée relative à la racine de votre projet, plutôt qu'à l'emplacement du fichier source de l'exemple.

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

export default async function Image() {
  const logoData = await readFile(join(process.cwd(), 'logo.png'))
  const logoSrc = Uint8Array.from(logoData).buffer

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
        }}
      >
        <img src={logoSrc} height="100" />
      </div>
    )
  )
}

Historique des versions

Version	Changements
`v13.3.0`	`opengraph-image` et `twitter-image` introduits.

On this page