API des fournisseurs de polices d'Astro

Ajouté à la version : astro@6.0.0

L’API des polices vous permet d’accéder aux polices de manière unifiée. Chaque famille nécessite l’utilisation d’un fournisseur de polices pour Astro, qui télécharge les fichiers de polices à partir d’un service distant ou charge les fichiers de polices locaux depuis le disque.

Fournisseurs intégrés

Astro exporte les fournisseurs de polices intégrés depuis astro/config :

import { fontProviders } from 'astro/config'

Pour utiliser un fournisseur de polices intégré, définissez provider avec la valeur appropriée pour le fournisseur de polices que vous avez choisi :

• Adobe
• Bunny
• Fontshare
• Fontsource
• Google
• Google Icons
• Locales
• NPM

Adobe

Récupère les polices depuis Adobe :

provider: fontProviders.adobe({ id: "your-id" })

Transmettez au fournisseur de polices Adobe un ID chargé en tant que variable d’environnement dans votre fichier de configuration d’Astro.

Bunny

Récupère les polices depuis Bunny :

provider: fontProviders.bunny()

Fontshare

Récupère les polices depuis Fontshare :

provider: fontProviders.fontshare()

Fontsource

Récupère les polices depuis Fontsource :

provider: fontProviders.fontsource()

Google

Récupère les polices depuis Google :

provider: fontProviders.google()

Le fournisseur est livré avec les options suivantes, spécifiques à la famille, qui peuvent être ajoutées dans l’objet font.options.

experimental.glyphs

Type : string[]

Permet de spécifier une liste de glyphes à inclure dans la police pour chaque famille de polices. Cela peut réduire la taille du fichier de police :

{
  // ...
  provider: fontProviders.google(),
  options: {
    experimental: {
      glyphs: ["a"]
    }
  }
}

experimental.variableAxis

Type : Partial<Record<VariableAxis, ([string, string] | string)[]>>

Permet de configurer les axes variables :

{
  // ...
  provider: fontProviders.google(),
  options: {
    experimental: {
      variableAxis: {
        slnt: [["-15", "0"]],
        CASL: [["0", "1"]],
        CRSV: ["1"],
        MONO: [["0", "1"]],
      }
    }
  }
}

Google Icons

Récupère les polices depuis Google Icons :

provider: fontProviders.googleicons()

Le fournisseur est livré avec les options suivantes, spécifiques à la famille, qui peuvent être ajoutées dans l’objet font.options.

experimental.glyphs

Type : string[]

Lors de la résolution des nouvelles icônes Material Symbols, il est possible de spécifier une liste de glyphes à inclure dans la police pour chaque famille de polices. Cela peut réduire la taille du fichier de police :

{
  // ...
  provider: fontProviders.googleicons(),
  options: {
    experimental: {
      glyphs: ["a"]
    }
  }
}

Locales

Récupère les polices depuis le disque :

provider: fontProviders.local()

Le fournisseur exige que les variantes (variants) soient définies dans l’objet font.options.

variants

Type : LocalFontFamily["variants"]

La propriété options.variants est obligatoire. Chaque variante représente une déclaration @font-face et nécessite une src.

De plus, d’autres propriétés peuvent être spécifiées dans chaque variante.

astro.config.mjs

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

export default defineConfig({
  fonts: [{
    provider: fontProviders.local(),
    name: "Personnalisee",
    cssVariable: "--police-personnalisee",
    options: {
      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
Par défaut : undefined

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"

Lorsque la valeur n’est pas définie, Astro essaiera par défaut de déduire la valeur en fonction de la première source.

style

Type : "normal" | "italic" | "oblique"
Par défaut : undefined

Un style de police :

style: "normal"

Lorsque la valeur n’est pas définie, Astro essaiera par défaut de déduire la valeur en fonction de la première source.

src

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

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

Chemin relatif

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

URL

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

Importation de paquets

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

Attention

Nous vous recommandons de ne pas placer vos fichiers de police dans le dossier public/. Étant donné qu’Astro copiera ces fichiers dans ce dossier au moment de la compilation, cela entraînera la présence de fichiers dupliqués dans le résultat de votre compilation. Il est préférable de les stocker ailleurs dans votre projet, par exemple dans src/.

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 issues des familles de polices sont également disponibles pour les familles de polices locales au sein des variantes :

• display
• unicodeRange
• stretch
• featureSettings
• variationSettings

astro.config.mjs

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

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

NPM

Récupère les polices à partir de paquets NPM, soit à partir des paquets installés localement dans node_modules, soit à partir d’un CDN :

provider: fontProviders.npm()

Le fournisseur détecte automatiquement les polices à partir des dépendances dans votre fichier package.json et peut résoudre les polices à partir de paquets comme @fontsource/*, @fontsource-variable/* et d’autres paquets de polices connus.

Options du fournisseur

Le fournisseur NPM accepte les options de configuration suivantes :

cdn

Type : string
Par défaut : 'https://cdn.jsdelivr.net/npm'

CDN à utiliser pour récupérer les paquets npm à distance :

provider: fontProviders.npm({ cdn: 'https://esm.sh' })

remote

Type : boolean
Par défaut : true

Indique s’il faut utiliser le CDN en cas d’échec de la résolution locale. Définissez cette valeur sur false pour n’utiliser que les paquets installés localement.

provider: fontProviders.npm({ remote: false })

Options de la famille

Le fournisseur est livré avec les options suivantes, spécifiques à la famille, qui peuvent être ajoutées dans l’objet font.options.

package

Type : string
Par défaut : Détecté automatiquement ou déduit du nom de la famille

Le nom du paquet NPM. S’il n’est pas spécifié, le fournisseur tentera de trouver la famille de polices dans les modèles de paquets de polices connus ou de la déduire en fonction des conventions de Fontsource :

{
  // ...
  provider: fontProviders.npm(),
  options: {
    package: '@fontsource/roboto'
  }
}

version

Type : string
Par défaut : 'latest'

La version du paquet (utilisée uniquement pour la résolution CDN) :

{
  // ...
  provider: fontProviders.npm(),
  options: {
    version: '5.0.0'
  }
}

file

Type : string
Par défaut : 'index.css'

Le fichier CSS d’entrée à analyser à partir du paquet :

{
  // ...
  provider: fontProviders.npm(),
  options: {
    file: 'latin.css'
  }
}

Création d’un fournisseur de polices

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

La méthode préférée pour implémenter un fournisseur de polices personnalisé consiste à exporter une fonction qui renvoie l’objet FontProvider et prend la configuration en tant que paramètre.

L’objet du fournisseur de polices

Un FontProvider est un objet contenant les propriétés obligatoires name et resolveFont(). Il possède également des propriétés facultatives : config, init() et listFonts().

Le type FontProvider accepte un générique pour les options de famille.

name

Type : string

Un nom unique pour le fournisseur, utilisé dans les journaux et à des fins d’identification.

resolveFont()

Type : (options: ResolveFontOptions) => Awaitable<{ fonts: FontFaceData[] } | undefined>

Utilisé pour récupérer et renvoyer les données de police de caractères en fonction des options données.

config

Type : Record<string, any>
Par défaut : undefined

Un objet sérialisable, utilisé à des fins d’identification.

init()

Type : (context: FontProviderInitContext) => Awaitable<void>
Par défaut : undefined

Fonction de rappel facultative, utilisée pour exécuter toute logique d’initialisation.

context.storage

Type : Storage

Utile pour la mise en cache.

context.root

Type : URL

La racine du projet, utile pour résoudre les chemins d’accès aux fichiers locaux.

listFonts()

Type : () => Awaitable<string[] | undefined>
Par défaut : undefined

Fonction de rappel facultative, utilisée pour renvoyer la liste des noms de polices disponibles.

Prise en charge d’un registre privé

L’exemple suivant définit un fournisseur de polices pour un registre privé :

Simple

font-provider.ts

import type { FontProvider } from "astro";
import { retrieveFonts, type Fonts } from "./utils.js",

export function registryFontProvider(): FontProvider {
  let data: Fonts = {}

  return {
    name: "registre",
    init: async () => {
      data = await retrieveFonts(token);
    },
    listFonts: () => {
      return Object.keys(data);
    },
    resolveFont: ({ familyName, ...rest }) => {
      const fonts = data[familyName];
      if (fonts) {
        return { fonts };
      }
      return undefined;
    },
  };
}

Options du fournisseur

font-provider.ts

import type { FontProvider } from "astro";
import { retrieveFonts, type Fonts } from "./utils.js",

interface Config {
  token: string;
}

export function registryFontProvider(config: Config): FontProvider {
  let data: Fonts = {}

  return {
    name: "registre",
    config,
    init: async () => {
      data = await retrieveFonts(token);
    },
    listFonts: () => {
      return Object.keys(data);
    },
    resolveFont: ({ familyName, ...rest }) => {
      const fonts = data[familyName];
      if (fonts) {
        return { fonts };
      }
      return undefined;
    },
  };
}

Options de la famille

font-provider.ts

import type { FontProvider } from "astro";
import { retrieveFonts, type Fonts } from "./utils.js",

interface FamilyOptions {
  minimal?: boolean;
}

export function registryFontProvider(): FontProvider<FamilyOptions | undefined> {
  let data: Fonts = {}

  return {
    name: "registre",
    init: async () => {
      data = await retrieveFonts(token);
    },
    listFonts: () => {
      return Object.keys(data);
    },
    // options est typé en tant que FamilyOptions | undefined
    resolveFont: ({ familyName, options, ...rest }) => {
      const fonts = data[familyName];
      if (fonts) {
        return { fonts };
      }
      return undefined;
    },
  };
}

Vous pouvez ensuite enregistrer ce fournisseur de polices dans la configuration d’Astro :

Simple

astro.config.ts

import { defineConfig } from "astro/config";
import { registryFontProvider } from "./font-provider";

export default defineConfig({
  fonts: [{
    provider: registryFontProvider(),
    name: "Personalisee",
    cssVariable: "--police-personalisee"
  }]
});

Options du fournisseur

astro.config.ts

import { defineConfig } from "astro/config";
import { registryFontProvider } from "./font-provider";

export default defineConfig({
  fonts: [{
    provider: registryFontProvider({
      token: "..."
    }),
    name: "Personalisee",
    cssVariable: "--police-personalisee"
  }]
});

Options de la famille

astro.config.ts

import { defineConfig } from "astro/config";
import { registryFontProvider } from "./font-provider";

export default defineConfig({
  fonts: [{
    provider: registryFontProvider(),
    options: {
      minimal: true
    },
    name: "Personalisee",
    cssVariable: "--police-personalisee"
  }]
});

Prise en charge d’un fournisseur Unifont tiers

Vous pouvez définir un fournisseur de polices pour Astro en utilisant un fournisseur Unifont en interne :

Simple

font-provider.ts

import type { FontProvider } from "astro";
import type { InitializedProvider } from "unifont";
import { acmeProvider } from "@acme/unifont-provider"

export function acmeFontProvider(): FontProvider {
  const provider = acmeProvider();
  let initializedProvider: InitializedProvider | undefined;
  return {
    name: provider._name,
    async init(context) {
      initializedProvider = await provider(context);
    },
    async resolveFont({ familyName, ...rest }) {
      return await initializedProvider?.resolveFont(familyName, rest);
    },
    async listFonts() {
      return await initializedProvider?.listFonts?.();
    },
  };
}

Options du fournisseur

font-provider.ts

import type { FontProvider } from "astro";
import type { InitializedProvider } from "unifont";
import { acmeProvider, type AcmeOptions } from "@acme/unifont-provider"

export function acmeFontProvider(config?: AcmeOptions): FontProvider {
  const provider = acmeProvider(config);
  let initializedProvider: InitializedProvider | undefined;
  return {
    name: provider._name,
    config,
    async init(context) {
      initializedProvider = await provider(context);
    },
    async resolveFont({ familyName, ...rest }) {
      return await initializedProvider?.resolveFont(familyName, rest);
    },
    async listFonts() {
      return await initializedProvider?.listFonts?.();
    },
  };
}

Options de la famille

font-provider.ts

import type { FontProvider } from "astro";
import type { InitializedProvider } from "unifont";
import { acmeProvider, type AcmeFamilyOptions } from "@acme/unifont-provider"

export function acmeFontProvider(): FontProvider<AcmeFamilyOptions | undefined> {
  const provider = acmeProvider();
  let initializedProvider: InitializedProvider<AcmeFamilyOptions> | undefined;
  return {
    name: provider._name,
    async init(context) {
      initializedProvider = await provider(context);
    },
    async resolveFont({ familyName, ...rest }) {
      return await initializedProvider?.resolveFont(familyName, rest);
    },
    async listFonts() {
      return await initializedProvider?.listFonts?.();
    },
  };
}

Vous pouvez ensuite enregistrer ce fournisseur de polices dans la configuration d’Astro :

Simple

astro.config.ts

import { defineConfig } from "astro/config";
import { acmeFontProvider } from "./font-provider";

export default defineConfig({
  fonts: [{
    provider: acmeFontProvider(),
    name: "Personnalisee",
    cssVariable: "--police-personnalisee"
  }]
});

Options du fournisseur

astro.config.ts

import { defineConfig } from "astro/config";
import { acmeFontProvider } from "./font-provider";

export default defineConfig({
  fonts: [{
    provider: acmeFontProvider({
      token: "..."
    }),
    name: "Personnalisee",
    cssVariable: "--police-personnalisee"
  }]
});

Options de la famille

astro.config.ts

import { defineConfig } from "astro/config";
import { acmeFontProvider } from "./font-provider";

export default defineConfig({
  fonts: [{
    provider: acmeFontProvider(),
    options: {
      minimal: true
    },
    name: "Personnalisee",
    cssVariable: "--police-personnalisee"
  }]
});