API des polices expérimentale

Type : FontFamily[]

Ajouté à la version : astro@5.7.0 Nouveau

Cette fonctionnalité expérimentale vous permet d’utiliser des polices de votre système de fichiers et de divers fournisseurs de polices (par exemple Google, Fontsource, Bunny) via une API unifiée, entièrement personnalisable et assurant la sûreté du typage.

Les polices web peuvent impacter les performances des pages, aussi bien au moment du chargement qu’au moment du rendu. Cette API vous aide à maintenir les performances de votre site grâce à des optimisations automatiques des polices web notamment des liens de préchargement, des solutions de repli optimisées et des valeurs par défaut pensées pour éviter les problèmes courants tels que le téléchargement inutiles de fichiers de polices.

Pour activer cette fonctionnalité, configurez un objet experimental.fonts avec au moins une police :

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

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

Ensuite, ajoutez le composant <Font /> et le style à l’échelle du site dans votre <head> :

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

<Font cssVariable='--font-roboto' preload />

<style>
body {
    font-family: var(--font-roboto);
}
</style>

Utilisation

experimental.fonts accepte un tableau d’objets de police. Pour chaque police, vous devez spécifier un fournisseur (provider), un nom de la famille (name) et définir une variable CSS (cssVariable) pour référencer votre police.
- provider : Vous pouvez choisir dans la liste des fournisseurs distants intégrés, créer votre propre fournisseur de polices personnalisé ou utiliser le fournisseur local pour enregistrer les fichiers de polices locaux.
- name : Choisissez une famille de polices prise en charge par votre fournisseur.
- cssVariable : Doit être un identifiant valide sous la forme d’une variable CSS.
L’exemple suivant configure la famille « Roboto » depuis Google Fonts :
astro.config.mjs
```
import { defineConfig, fontProviders } from "astro/config";

export default defineConfig({
  experimental: {
    fonts: [{
      provider: fontProviders.google(),
      name: "Roboto",
      cssVariable: "--font-roboto"
    }]
  }
});
```
Plus d’options de configuration, telles que la définition de familles de polices de repli ainsi que les graisses (weights) et styles à télécharger, sont disponibles et certaines dépendront du fournisseur choisi.

Consultez la référence de configuration complète pour en savoir plus.
Appliquez des styles à l’aide du composant <Font />. Il doit être importé et ajouté au <head> de votre page. La fourniture de la variable CSS de la police est obligatoire, et vous pouvez éventuellement générer les liens de préchargement :
src/components/Head.astro
```
---
import { Font } from 'astro:assets';
---

<Font cssVariable="--font-roboto" preload />
```
Cela se fait généralement dans un composant tel que Head.astro qui est utilisé dans une mise en page de site courante.

Consultez la référence complète du composant <Font> pour plus d’informations.

Étant donné que le composant <Font /> génère du CSS avec des déclarations de polices, vous pouvez faire référence à la famille de polices à l’aide de cssVariable :
<style> body { font-family: var(--font-roboto); } </style>
src/styles/global.css
@import 'tailwindcss'; @theme inline { --font-sans: var(--font-roboto); }
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: [] };

Fournisseurs de polices distantes disponibles

Astro réexporte la plupart des fournisseurs de polices unifont. Les suivants offrent une prise en charge intégrée :

Pour utiliser un fournisseur distant intégré, configurez provider avec la valeur appropriée pour le fournisseur de polices choisi :

provider: fontProviders.adobe({ id: process.env.ADOBE_ID })

provider: fontProviders.bunny()

provider: fontProviders.fontshare()

provider: fontProviders.fontsource()

provider: fontProviders.google()

En complément, le fournisseur de polices google() accepte toutes les options disponibles dans l’interface ProviderOption d’unifont pour Google :

provider: fontProviders.google({
  glyphs: {
    Roboto: ["a"]
  }
})

Vous pouvez également créer un fournisseur de polices Astro personnalisé pour n’importe quel fournisseur unifont.

Référence du composant `<Font />`

Ce composant génère des balises de style et peut éventuellement générer des liens de préchargement pour une famille de polices donnée.

Il doit être importé et ajouté au <head> de votre page. Cette opération est généralement effectuée dans un composant tel que Head.astro, utilisé dans une mise en page de site commune à usage global, mais peut être ajouté à des pages individuelles si nécessaire.

Avec ce composant, vous contrôlez quelle famille de polices est utilisée sur quelle page et quelles polices sont préchargées.

cssVariable

Exemple de type : "--font-roboto" | "--font-comic-sans" | ...

La variable CSS enregistrée dans votre configuration Astro :

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

<Font cssVariable="--font-roboto" />

preload

Type : boolean
Par défaut : false

Détermine s’il faut ou non afficher les liens de préchargement :

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

<Font cssVariable="--font-roboto" preload />

Référence de configuration des polices

Toutes les propriétés de vos polices doivent être configurées dans la configuration d’Astro. Certaines propriétés sont communes aux polices distantes et locales, tandis que d’autres sont disponibles selon le fournisseur de polices choisi.

Propriétés communes

Les propriétés suivantes sont disponibles pour les polices distantes et locales. provider, name et cssVariable sont obligatoires.

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

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

provider

Type : AstroFontProvider | "local"

La source de vos fichiers de polices. Vous pouvez utiliser un fournisseur intégré, créer votre propre fournisseur personnalisé ou définir local pour utiliser les fichiers de polices locaux :

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

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

name

Type : string

Le nom de la famille de polices, tel qu’identifié par votre fournisseur de polices :

name: "Roboto"

cssVariable

Type : string

Un identifiant valide de votre choix sous la forme d’une variable CSS (c’est-à-dire commençant par --) :

cssVariable: "--font-roboto"

fallbacks

Type : string[]
Par défaut : ["sans-serif"]

Un tableau de polices à utiliser lorsque la police choisie n’est pas disponible ou est en cours de chargement. Les polices de repli seront sélectionnées dans l’ordre indiqué. La première police disponible sera utilisée :

fallbacks: ["PolicePersonnalisee", "serif"]

Pour désactiver complètement les polices de repli, configurez un tableau vide :

fallbacks: []

Si la dernière police du tableau fallbacks est un nom de famille générique, Astro tentera de générer des solutions de repli optimisées en utilisant les métriques de police. Pour désactiver cette optimisation, définissez optimizedFallbacks sur false.

optimizedFallbacks

Type : boolean
Par défaut : true

S’il faut ou non activer l’optimisation par défaut d’Astro lors de la génération de polices de repli. Vous pouvez désactiver cette optimisation par défaut pour contrôler entièrement la manière dont les solutions de repli sont générées.

optimizedFallbacks: false

Propriétés de police à distance

D’autres options de configuration sont disponibles pour les polices distantes. Définissez-les pour personnaliser les données chargées depuis votre fournisseur de polices, par exemple pour télécharger uniquement certains styles ou graisses de police.

Sous le capot, ces options sont gérées par unifont. Certaines propriétés peuvent ne pas être prises en charge par certains fournisseurs et être gérées différemment par chacun.

weights

Type : (number | string)[]
Par défaut : [400]

Un tableau de graisses de police. Si aucune valeur n’est spécifiée dans votre configuration, seule la graisse 400 est incluse par défaut pour éviter les téléchargements inutiles. Vous devrez inclure cette propriété pour accéder aux autres graisses de police :

weights: [200, "400", "bold"]

Si la police associée est une police variable, vous pouvez spécifier une plage de graisses :

weights: ["100 900"]

styles

Type : ("normal" | "italic" | "oblique")[]
Par défaut : ["normal", "italic"]

Un tableau de styles de police :

styles: ["normal", "oblique"]

subsets

Type : string[]
Par défaut : ["cyrillic-ext", "cyrillic", "greek-ext", "greek", "vietnamese", "latin-ext", "latin"]

Définit une liste de sous-ensembles de polices à précharger.

subsets: ["latin"]

display

Type : "auto" | "block" | "swap" | "fallback" | "optional"
Par défaut : "swap"

Définit comment une police s’affiche en fonction du moment où elle est téléchargée et prête à l’emploi :

display: "block"

unicodeRange

Type : string[]
Par défaut : undefined

Détermine la plage spécifique de caractères Unicode à utiliser à partir d’une police :

unicodeRange: ["U+26"]

stretch

Type : string
Par défaut : undefined

Un étirement de la police :

stretch: "condensed"

featureSettings

Type : string
Par défaut : undefined

Contrôle les fonctionnalités de police typographique (par exemple, les ligatures, les petites majuscules ou les ornements) :

featureSettings: "'smcp' 2"

variationSettings

Type : string
Par défaut : undefined

Paramètres de variation de police :

variationSettings: "'xhgt' 0.7"

Variantes de polices locales

Type : LocalFontFamily["variants"]

La propriété variants est requise lors de l’utilisation de fichiers de polices locaux. Chaque variante représente une déclaration @font-face et nécessite une valeur pour weight, style et src.

De plus, certaines autres propriétés des polices distantes peuvent être spécifiées dans chaque variante.

import { defineConfig } from "astro/config";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: "local",
            name: "Personnalisee",
            cssVariable: "--police-personnalisee",
            variants: [
                {
                    weight: 400,
                    style: "normal",
                    src: ["./src/assets/fonts/personnalisee-400.woff2"]
                },
                {
                    weight: 700,
                    style: "normal",
                    src: ["./src/assets/fonts/personnalisee-700.woff2"]
                }
                // ...
            ]
        }]
    }
});

weight

Type : number | string

Une graisse de police :

weight: 200

Si la police associée est une police variable, vous pouvez spécifier une plage de graisses :

weight: "100 900"

style

Type : "normal" | "italic" | "oblique"

Un style de police :

style: "normal"

src

Type : (string | URL | { url: string | URL; tech?: string })[]

Sources des polices. Il peut s’agir d’un chemin relatif à la racine, d’une importation de paquets ou d’une URL. Les URL sont particulièrement utiles si vous injectez des polices locales via une intégration :

src: ["./src/assets/fonts/MaPolice.woff2", "./src/assets/fonts/MaPolice.woff"]

src: [new URL("./personnalisee.ttf", import.meta.url)]

src: ["mon-paquet/UnePolice.ttf"]

Vous pouvez également spécifier une tech en fournissant des objets :

src: [{ url:"./src/assets/fonts/MaPolice.woff2", tech: "color-COLRv1" }]

Autres propriétés

Les options suivantes des familles de polices distantes sont également disponibles pour les familles de polices locales dans les variantes :

display
unicodeRange
stretch
featureSettings
variationSettings

import { defineConfig } from "astro/config";

export default defineConfig({
    experimental: {
        fonts: [{
            provider: "local",
            name: "Personnalisee",
            cssVariable: "--police-personnalisee",
            variants: [
                {
                    weight: 400,
                    style: "normal",
                    src: ["./src/assets/fonts/personnalisee-400.woff2"],
                    display: "block"
                }
            ]
        }]
    }
});

Créer votre propre fournisseur de polices

Si vous ne souhaitez pas utiliser l’un des fournisseurs intégrés (par exemple, vous souhaitez utiliser un fournisseur de polices unifont tiers ou créer quelque chose pour un registre privé), vous pouvez créer le vôtre.

Un fournisseur de polices Astro est composé de deux parties : l’objet de configuration et l’implémentation réelle.

À l’aide de l’assistant de type defineAstroFontProvider(), créez une fonction qui renvoie un objet de configuration de fournisseur de polices contenant :

entrypoint : Une URL, un chemin relatif à la racine ou une importation de package.
config : Un objet sérialisable facultatif transmis au fournisseur unifont.

Sans configuration
Avec configuration

import { defineAstroFontProvider } from 'astro/config';

export function myProvider() {
    return defineAstroFontProvider({
        entrypoint: new URL('./implementation.js', import.meta.url)
    });
};

import { defineAstroFontProvider } from 'astro/config';

interface Config {
    // ...
};

export function myProvider(config: Config) {
    return defineAstroFontProvider({
        entrypoint: new URL('./implementation.js', import.meta.url),
        config
    });
};

Créez un deuxième fichier pour exporter votre implémentation de fournisseur unifont :
implementation.ts
```
import { defineFontProvider } from "unifont";

export const provider = defineFontProvider("mon-fournisseur", async (options, ctx) => {
    // récupérer/définir vos polices personnalisées
    // ...
});
```
Vous pouvez consulter le code source des fournisseurs d’unifont pour en savoir plus sur la création d’un fournisseur unifont.

Ajoutez votre fournisseur personnalisé à votre configuration de police.

fonts: [{
  provider: fontProviders.myProvider(),
  name: "Police personnalisee",
  cssVariable: "--police-personnalisee"
 }]

Mise en cache

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

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

Lectures complémentaires

Pour plus de détails et pour donner votre avis sur cette API expérimentale, consultez la RFC pour les polices.

Contribuer Communauté Parrainer

API des polices expérimentale

Utilisation

Fournisseurs de polices distantes disponibles

Référence du composant <Font />

cssVariable

preload

Référence de configuration des polices

Propriétés communes

provider

name

cssVariable

fallbacks

optimizedFallbacks

Propriétés de police à distance

weights

styles

subsets

display

unicodeRange

stretch

featureSettings

variationSettings

Variantes de polices locales

weight

style

src

Autres propriétés

Créer votre propre fournisseur de polices

Mise en cache

Lectures complémentaires

Référence du composant `<Font />`