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 (EN) : 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.

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

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

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'
      }]
    }
  }]
});

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 (EN) 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).

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

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

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

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

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.

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

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
Tailwind CSS 3.0

@import "tailwindcss";

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

/** @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.

Accéder aux données de police par programmation

L’objet fontData vous permet de récupérer par programmation des données de famille de polices de bas niveau. Par exemple, vous pouvez l’utiliser dans une route d’API pour générer des images OpenGraph à l’aide de satori, combiné avec une configuration de formats appropriée :

import type{ APIRoute } from "astro";
import { fontData } from "astro:assets";
import satori from "satori";
import { html } from "satori-html";

export const GET: APIRoute = async (context) => {
  const data = fontData["--font-roboto"];

  const svg = await satori(
    html`<div style="color: black;">hello, world</div>`,
    {
      width: 600,
      height: 400,
      fonts: [
        {
          name: "Roboto",
          data: await fetch(
            new URL(data[0].src[0].url, context.url.origin),
          ).then((res) => res.arrayBuffer()),
          weight: 400,
          style: "normal",
        },
      ],
    },
  );

  // ...
}

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 :

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.

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",
            ]
          },
        ]
      }
    }
  ],
});

Contribuer Communauté Parrainer