Utiliser des polices personnalisées

Ce guide vous montrera comment ajouter des polices web à votre projet et les utiliser dans vos composants.

Astro offre la possibilité d’utiliser des polices provenant de votre système de fichiers et de divers fournisseurs de polices (par exemple Fontsource, Google) via une API unifiée, entièrement personnalisable et avec sûreté du typage.

Les polices web peuvent avoir un impact sur les performances des pages, tant au moment du chargement qu’au moment du rendu. Cette API vous aide à maintenir les performances de votre site grâce à des optimisations de polices web automatiques, notamment des liens de préchargement, des solutions de repli optimisées et des valeurs par défaut personnalisées. Consultez des exemples d’utilisation courants.

L’API des polices privilégie la performance et la confidentialité en téléchargeant et en mettant en cache les polices afin qu’elles soient diffusées depuis votre site. Cela permet d’éviter l’envoi de données utilisateur à des sites tiers et garantit également la mise à disposition d’un ensemble de polices cohérent pour tous vos visiteurs.

Configuration de polices personnalisées

L’enregistrement des polices personnalisées pour votre projet Astro se fait via l’option fonts dans la configuration d’Astro.

Pour chaque police que vous souhaitez utiliser, vous devez spécifier son nom, une variable CSS et un fournisseur de polices pour Astro.

Astro fournit une prise en charge intégrée des fournisseurs de polices les plus populaires : Adobe, Bunny, Fontshare, Fontsource, Google, Google Icons et NPM, ainsi que la possibilité d’utiliser vos propres fichiers de polices locaux. De plus, vous pouvez personnaliser davantage votre configuration de police pour optimiser les performances et l’expérience des visiteurs.

Utilisation d’un fichier de police local

Cet exemple démontre comment ajouter une police personnalisée en utilisant le fichier de police DistantGalaxy.woff2.

1. Ajoutez votre fichier de police dans le dossier src/, par exemple src/assets/fonts/.

2. Créez une nouvelle famille de polices dans votre fichier de configuration d’Astro en utilisant le fournisseur de polices local et spécifiez les variantes à inclure :

   astro.config.mjs

   import { defineConfig, fontProviders } from "astro/config";
   
   export default defineConfig({
     fonts: [{
       provider: fontProviders.local(),
       name: "DistantGalaxy",
       cssVariable: "--font-distant-galaxy",
       options: {
         variants: [{
           src: ['./src/assets/fonts/DistantGalaxy.woff2'],
           weight: 'normal',
           style: 'normal'
         }]
       }
     }]
   });

3. Votre police est maintenant configurée et prête à être ajoutée à l’en-tête de votre page afin qu’elle puisse être utilisée dans votre projet.

Utilisation de Fontsource

Astro prend en charge plusieurs fournisseurs de polices dès son installation, y compris la prise en charge de Fontsource qui simplifie l’utilisation de Google Fonts et d’autres polices open-source.

L’exemple suivant utilise Fontsource pour ajouter la prise en charge des polices personnalisées, mais le processus est similaire pour tous les fournisseurs de polices intégrés à Astro (par exemple, Adobe, Bunny).

1. Trouvez la police que vous souhaitez utiliser dans le catalogue de Fontsource. Cet exemple utilise Roboto.

2. Créez une nouvelle famille de polices dans votre fichier de configuration d’Astro en utilisant le fournisseur Fontsource :

   astro.config.mjs

   import { defineConfig, fontProviders } from "astro/config";
   
   export default defineConfig({
     fonts: [{
       provider: fontProviders.fontsource(),
       name: "Roboto",
       cssVariable: "--font-roboto",
     }]
   });

3. Votre police est maintenant configurée et prête à être ajoutée à l’en-tête de votre page afin qu’elle puisse être utilisée dans votre projet.

Application de polices personnalisées

Une fois la police configurée, elle doit être ajoutée à l’en-tête de votre page avec une variable CSS d’identification. Vous pourrez ensuite utiliser cette variable pour définir les styles de votre page.

1. Importez et incluez le composant <Font /> avec la propriété cssVariable requise dans l’en-tête de votre page, généralement dans un composant Head.astro dédié ou directement dans un composant de mise en page :

   src/layouts/Layout.astro

   ---
   import { Font } from "astro:assets";
   ---
   
   <html>
     <head>
       <Font cssVariable="--font-distant-galaxy" />
     </head>
     <body>
       <slot />
     </body>
   </html>

2. Dans n’importe quelle page générée avec cette mise en page, comprenant le composant de mise en page lui-même, vous pouvez désormais définir des styles avec la variable CSS (cssVariable) de votre police pour appliquer votre police personnalisée.

   Dans l’exemple suivant, le titre <h1> a la police personnalisée appliquée, tandis que le paragraphe <p> ne l’a pas.

   src/pages/example.astro

   ---
   import Layout from "../layouts/Layout.astro";
   ---
   <Layout>
     <h1>Dans une galaxie très, très lointaine...</h1>
   
     <p>Les polices personnalisées rendent mes titres beaucoup plus sympas !</p>
   
     <style>
     h1 {
       font-family: var(--font-distant-galaxy);
     }
     </style>
   </Layout>

Préchargement des polices

Le préchargement des polices doit être utilisé avec parcimonie, car il peut bloquer le chargement d’autres ressources importantes ou télécharger des polices inutiles pour la page actuelle. Envisagez de précharger uniquement les polices essentielles, nécessaires à l’affichage du contenu visible au-dessus de la ligne de flottaison.

Pour précharger une police, transmettez la propriété preload au composant <Font /> correspondant. Si plusieurs fichiers correspondent à une police, vous pouvez également spécifier lequel précharger en transmettant un tableau.

src/layouts/Layout.astro

---
import { Font } from "astro:assets";
---

<html>
  <head>
    <Font cssVariable="--font-distant-galaxy" preload />
  </head>
  <body>
    <slot />
  </body>
</html>

Enregistrer les polices avec Tailwind

Si vous utilisez Tailwind pour la mise en forme, vous n’appliquerez pas vos styles avec la propriété CSS font-face.

À la place, après avoir configuré votre police personnalisée et l’avoir ajoutée à l’en-tête de votre page, vous devrez mettre à jour votre configuration de Tailwind pour enregistrer votre police :

Tailwind CSS 4.0

src/styles/global.css

@import "tailwindcss";

@theme inline {
  --font-sans: var(--font-roboto);
}

Tailwind CSS 3.0

tailwind.config.mjs

/** @type {import("tailwindcss").Config} */
export default {
  content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
  theme: {
    extend: {},
    fontFamily: {
      sans: ["var(--font-roboto)"]
    }
  },
  plugins: []
};

Consultez la documentation de Tailwind sur l’ajout de familles de polices personnalisées pour plus d’informations.

Utilisation de polices variables

Pour utiliser des polices variables dans votre projet, indiquez la plage de graisses disponible au lieu des graisses individuelles dans la configuration de votre fournisseur.

Fournisseur local

Lorsque vous utilisez un fichier de police local, vous pouvez indiquer que la police est variable en définissant la propriété weight de la variante avec une chaîne de caractères correspondant à la plage de graisses exacte disponible pour la police.

L’exemple suivant configure Inter en tant que police variable locale avec la plage de graisses disponible :

astro.config.mjs

import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  fonts: [{
    provider: fontProviders.local(),
    name: "Inter",
    cssVariable: "--font-inter",
    options: {
      variants: [
        {
          weight: "100 900",
          style: "normal",
          src: ["./src/assets/fonts/InterVariable.woff2"],
        },
      ],
    },
  }]
});

Autres fournisseurs

Lorsque vous utilisez d’autres fournisseurs (par exemple Fontsource) qui prennent en charge les polices variables, vous pouvez demander la version variable d’une police en définissant la propriété weights avec un tableau contenant la plage exacte de graisses disponibles pour la police.

L’exemple suivant télécharge Fira Code depuis Fontsource en tant que police variable avec la plage de graisses disponible :

astro.config.mjs

import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  fonts: [{
    cssVariable: "--font-fira-code",
    name: "Fira Code",
    provider: fontProviders.fontsource(),
    styles: ["normal"],
    weights: ["300 700"],
  }]
});

Personnalisation des polices de repli

Les polices de repli sont utilisées lorsque la police principale n’a pas encore été chargée, contient des caractères manquants ou ne peut pas être chargée pour une raison quelconque. Lorsque la police de repli diffère considérablement de la police principale, des décalages de mise en page peuvent se produire lors du chargement de la page.

Pour éviter cela, Astro tente automatiquement de générer des polices de repli optimisées à partir de la dernière police de repli définie si elle appartient à une famille de polices générique. Il utilise par défaut la police sans-serif, mais celle-ci peut ne pas correspondre à l’apparence souhaitée de votre police principale. Vous pouvez la régler dans votre configuration de police :

astro.config.mjs

import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  fonts: [{
    provider: fontProviders.fontsource(),
    name: "Cousine",
    cssVariable: "--font-cousine",
    fallbacks: ["monospace"]
  }]
});

Vous pouvez également choisir de ne pas utiliser l’optimisation par défaut en définissant font.optimizedFallbacks sur false dans votre configuration de police. Astro utilisera alors les polices de repli spécifiées dans votre configuration sans aucun traitement automatique supplémentaire.

Accéder aux données de police par programmation

Astro expose une API de bas niveau permettant d’accéder par programmation aux données des familles de polices via l’objet fontData. Ceci peut s’avérer utile pour des cas d’utilisation avancés nécessitant un accès direct aux fichiers de polices, comme la génération d’images OpenGraph avec Satori dans une route d’API.

Cette API de bas niveau vous donne accès à tous les fichiers de polices téléchargés par Astro pour votre projet, ainsi qu’à leurs métadonnées. Cela signifie que vous êtes responsable du filtrage des fichiers de polices pour trouver le fichier spécifique dont vous avez besoin, et de la résolution du chemin du fichier à utiliser en fonction de la structure de sortie de la compilation.

Note

L’API actuelle présente une limitation connue qui vous oblige à charger manuellement le fichier de police à partir du chemin de sortie au moment de la compilation.

Une nouvelle API est en cours de développement pour simplifier ce processus et sera disponible dans une future version. Vous pouvez vous abonner au ticket GitHub pour suivre son avancement.

L’exemple suivant génère une image OpenGraph dans un point de terminaison de fichier statique, en supposant qu’une seule police et son format ont été configurés avec un format pris en charge par Satori :

src/pages/og.png.ts

import type { APIRoute } from "astro";
import { fontData } from "astro:assets";
import { outDir } from "astro:config/server";
import { readFile } from "node:fs/promises";
import satori from "satori";
import { html } from "satori-html";
import sharp from "sharp";

export const GET: APIRoute = async (context) => {
  const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;

  if (fontPath === undefined) {
    throw new Error("Impossible de trouver le chemin de la police.");
  }

  const data = import.meta.env.DEV
    ? await fetch(new URL(fontPath, context.url.origin)).then(async (res) => res.arrayBuffer())
    : await readFile(new URL(`.${fontPath}`, outDir));

  const svg = await satori(
    html`<div style="color: black;">hello, world</div>`,
    {
      width: 600,
      height: 400,
      fonts: [
        {
          name: "Roboto",
          data,
          weight: 400,
          style: "normal",
        },
      ],
    },
  );

  const pngBuffer = await sharp(Buffer.from(svg))
    .resize(600, 400)
    .png()
    .toBuffer();

  return new Response(new Uint8Array(pngBuffer), {
    headers: {
      "Content-Type": "image/png",
    },
  });
};

Configuration granulaire des polices

Une famille de polices est définie par une combinaison de propriétés telles que les graisses et les styles (par exemple weights: [500, 600] et styles: ["normal", "bold"]), mais vous pouvez vouloir télécharger uniquement certaines combinaisons de celles-ci.

Pour un meilleur contrôle sur les fichiers de police téléchargés, vous pouvez spécifier la même police (c’est-à-dire avec les mêmes propriétés cssVariable, name et provider) plusieurs fois avec différentes combinaisons. Astro fusionnera les résultats et téléchargera uniquement les fichiers nécessaires. Par exemple, il est possible de télécharger les polices normales 500 et 600 tout en téléchargeant uniquement la police italique 500 :

astro.config.mjs

import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  fonts: [
    {
      name: "Roboto",
      cssVariable: "--roboto",
      provider: fontProviders.google(),
      weights: [500, 600],
      styles: ["normal"]
    },
    {
      name: "Roboto",
      cssVariable: "--roboto",
      provider: fontProviders.google(),
      weights: [500],
      styles: ["italic"]
    }
  ]
});

Mise en cache

L’implémentation de la mise en cache de l’API des polices a été conçue pour être pratique en développement et efficace en production. Lors des compilations, les fichiers de polices sont copiés dans le répertoire de sortie _astro/fonts, ce qui leur permet de bénéficier de la mise en cache HTTP des ressources statiques (généralement pendant un an).

Pour vider le cache en mode développement, supprimez le répertoire .astro/fonts. Pour vider le cache de compilation, supprimez le répertoire node_modules/.astro/fonts.

Exemples

La fonctionnalité des polices d’Astro repose sur des options de configuration flexibles. La configuration des polices dans votre propre projet peut sembler différente des exemples simplifiés. Les exemples suivants sont donc fournis pour illustrer à quoi peuvent ressembler différentes configurations de police en production.

astro.config.mjs

import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  fonts: [
    {
      name: "Roboto",
      cssVariable: "--font-roboto",
      provider: fontProviders.google(),
      // Inclus par défaut :
      // weights: [400] ,
      // styles: ["normal", "italic"],
      // subsets: ["latin"],
      // fallbacks: ["sans-serif"],
      // formats: ["woff2"],
    },
    {
      name: "Inter",
      cssVariable: "--font-inter",
      provider: fontProviders.fontsource(),
      // Spécifier les graisses réellement utilisées
      weights: [400, 500, 600, 700],
      // Spécifier les styles réellement utilisés
      styles: ["normal"],
      // Télécharger uniquement les fichiers de police pour les caractères utilisés sur la page.
      subsets: ["latin", "cyrillic"],
      // Télécharger plus de formats de police
      formats: ["woff2", "woff"],
    },
    {
      name: "JetBrains Mono",
      cssVariable: "--font-jetbrains-mono",
      provider: fontProviders.fontsource(),
      // Télécharger uniquement les fichiers de police pour les caractères utilisés sur la page.
      subsets: ["latin", "latin-ext"],
      // Utiliser une police de caractères de repli correspondant à l'apparence souhaitée
      fallbacks: ["monospace"],
    },
    {
      name: "Poppins",
      cssVariable: "--font-poppins",
      provider: fontProviders.local(),
      options: {
        // La graisse et le style ne sont pas précisés, donc Astro
        // tentera de les déduire pour chaque variante.
        variants: [
          {
            src: [
              "./src/assets/fonts/Poppins-regular.woff2",
              "./src/assets/fonts/Poppins-regular.woff",
            ]
          },
          {
            src: [
              "./src/assets/fonts/Poppins-bold.woff2",
              "./src/assets/fonts/Poppins-bold.woff",
            ]
          },
        ]
      }
    }
  ],
});