Aller au contenu

API du chargeur de contenu d'Astro

L’API du chargeur de contenu d’Astro (Content Loader) vous permet de charger vos données à partir de n’importe quelle source, locale ou distante, et d’interagir avec la couche de contenu d’Astro pour gérer vos collections de contenu.

Qu’est-ce qu’un chargeur ?

Titre de la section Qu’est-ce qu’un chargeur ?

Les chargeurs Astro vous permettent de charger des données dans des collections de contenu, qui peuvent ensuite être utilisées dans des pages et des composants. Les chargeurs intégrés glob() et file() sont utilisés pour charger le contenu du système de fichiers, et vous pouvez créer vos propres chargeurs pour charger le contenu à partir d’autres sources.

Chaque collection a besoin d’un chargeur défini dans son schéma. Vous pouvez définir un chargeur en ligne dans le fichier src/content.config.ts de votre projet, partager un chargeur entre plusieurs collections, ou même publier votre chargeur sur NPM en tant que paquet à partager avec d’autres et à inclure dans notre bibliothèque d’intégrations.

Types de chargeurs

Titre de la section Types de chargeurs

Les chargeurs peuvent être définis soit comme une simple fonction qui renvoie un tableau d’entrées, soit avec l’API du chargeur de contenu sous forme d’objet plus puissante pour plus de contrôle sur le processus de chargement.

Chargeurs en ligne

Titre de la section Chargeurs en ligne

Un chargeur en ligne est une fonction asynchrone qui renvoie un tableau ou un objet contenant des entrées. Utilisez-le pour les chargeurs simples, en particulier ceux qui sont définis en ligne dans le fichier src/content.config.ts.

La fonction peut être asynchrone et doit renvoyer soit un tableau d’entrées contenant chacune un champ id unique, soit un objet où chaque clé est un ID unique et chaque valeur est l’entrée. Chaque fois que le chargeur est appelé, il efface le magasin et recharge toutes les entrées.

src/content.config.ts
const countries = defineCollection({
  loader: async () => {
    const response = await fetch("https://restcountries.com/v3.1/all");
    const data = await response.json();
    // Doit renvoyer un tableau d'entrées avec une propriété id
    // ou un objet avec des identifiants comme clés et des entrées comme valeurs
    return data.map((country) => ({
      id: country.cca3,
      ...country,
    }));
  },
  schema: /* ... */
});

Chargeurs sous forme d’objet

Titre de la section Chargeurs sous forme d’objet

Un chargeur est un objet doté d’une méthode load() qui est appelée au moment de la construction pour récupérer des données et mettre à jour le magasin de données. Il permet de mettre à jour les entrées de manière incrémentielle ou de vider le magasin uniquement lorsque cela est nécessaire. Il peut également définir un schéma pour les entrées, qui peut être utilisé pour valider les données et générer des types statiques.

Le modèle recommandé consiste à définir une fonction qui accepte les options de configuration et renvoie l’objet chargeur, de la même manière que vous définiriez normalement une intégration Astro ou un plugin Vite.

loader.ts
import type { Loader, LoaderContext } from 'astro/loaders';
import { z } from 'astro:content';
import { loadFeedData } from "./feed.js";


// Définir toutes les options dont le chargeur a besoin
export function myLoader(options: { url: string, apiKey: string }): Loader {
  // Configurer le chargeur
  const feedUrl = new URL(options.url);
  // Renvoyer un objet chargeur
  return {
    name: "my-loader",
    // Appelé lors de la mise à jour de la collection.
    load: async (context: LoaderContext): Promise<void> => {
      // Charger les données et mettre à jour le magasin
      const response = await loadFeedData(feedUrl, options.apiKey);
    },
    // En option, définir le schéma d'une entrée.
    // Il sera remplacé par le schéma défini par l'utilisateur.
    schema: async () => z.object({
      // ...
    })
  };
}

Ces options de configuration peuvent ensuite être définies lors de la définition d’une collection :

src/content.config.ts
import { defineCollection, z } from 'astro:content';
import myLoader from '../../loader.ts';


const blog = defineCollection({
  loader: myLoader({
    url: "https://api.example.com/posts",
    apiKey: "mon-secret",
  }),
  schema: /* ... */
});

API du chargeur

Titre de la section API du chargeur

L’API pour les chargeurs en ligne est très simple et est présentée ci-dessus. Cette section présente l’API permettant de définir un chargeur sous forme d’objet.

L’objet Loader

Titre de la section L’objet Loader

L’objet chargeur possède les propriétés suivantes :

name

Titre de la section name

Type : string

Un nom unique pour le chargeur, utilisé dans les logs et pour le chargement conditionnel.

load

Titre de la section load

Type : (context: LoaderContext) => Promise<void>

Une fonction asynchrone qui est appelée au moment de la construction pour charger les données et mettre à jour le magasin. Voir LoaderContext pour plus d’informations.

schema

Titre de la section schema

Type : ZodSchema | Promise<ZodSchema> | (() => ZodSchema | Promise<ZodSchema>)

Un schéma Zod facultatif qui définit la forme des entrées. Il est utilisé à la fois pour valider les données et pour générer des types TypeScript pour la collection.

Si une fonction est fournie, elle sera appelée au moment de la construction avant load() pour générer le schéma. Vous pouvez l’utiliser pour générer dynamiquement le schéma en fonction des options de configuration ou en introspectant une API.

LoaderContext

Titre de la section LoaderContext

Cet objet est passé à la méthode load() du chargeur et contient les propriétés suivantes :

collection

Titre de la section collection

Type : string

Le nom unique de la collection. Il s’agit de la clé dans l’objet collections dans le fichier src/content.config.ts.

store

Titre de la section store

Type : DataStore

Une magasin de données pour stocker les données réelles. Utilisez-le pour mettre à jour le magasin avec de nouvelles entrées. Voir DataStore pour plus d’informations.

meta

Titre de la section meta

Type : MetaStore

Un magasin de clés-valeurs avec une portée limitée à la collection, conçu pour des choses comme la synchronisation des jetons et des heures de dernière modification. Ces métadonnées sont conservées entre les constructions avec les données de la collection, mais ne sont disponibles qu’à l’intérieur du chargeur.

const lastModified = meta.get("lastModified");
// ...
meta.set("lastModified", new Date().toISOString());

logger

Titre de la section logger

Type : AstroIntegrationLogger

Un enregistreur qui peut être utilisé pour enregistrer des messages sur la console. Utilisez-le à la place de console.log pour des journaux plus utiles qui incluent le nom du chargeur dans le message de journal. Voir AstroIntegrationLogger pour plus d’informations.

config

Titre de la section config

Type : AstroConfig

L’objet de configuration Astro complet et résolu avec toutes les valeurs par défaut appliquées. Consultez la référence de configuration pour plus d’informations.

parseData

Titre de la section parseData

Type : (props: ParseDataOptions<TData>) => Promise<TData>

Valide et analyse les données conformément au schéma de la collection. Transmettez les données à cette fonction pour les valider et les analyser avant de les stocker dans le magasin de données.

loader.ts
import type { Loader } from "astro/loaders";
import { loadFeed } from "./feed.js";


export function feedLoader({ url }): Loader {
  const feedUrl = new URL(url);
  return {
    name: "feed-loader",
    load: async ({ store, logger, parseData, meta, generateDigest }) => {
      logger.info("Chargement des articles");
      const feed = loadFeed(feedUrl);
      store.clear();


      for (const item of feed.items) {
        const data = await parseData({
          id: item.guid,
          data: item,
        });
        store.set({
          id,
          data,
        });
      }
    },
  };
}

generateDigest

Titre de la section generateDigest

Type : (data: Record<string, unknown> | string) => string

Génère un résumé de contenu non cryptographique d’un objet ou d’une chaîne de caractères. Cela peut être utilisé pour suivre si les données ont changé en définissant le champ digest d’une entrée.

loader.ts
import type { Loader } from "astro/loaders";
import { loadFeed } from "./feed.js";


export function feedLoader({ url }): Loader {
  const feedUrl = new URL(url);
  return {
    name: "feed-loader",
    load: async ({ store, logger, parseData, meta, generateDigest }) => {
      logger.info("Chargement des articles");
      const feed = loadFeed(feedUrl);
      store.clear();


      for (const item of feed.items) {
        const data = await parseData({
          id: item.guid,
          data: item,
        });


        const digest = generateDigest(data);


        store.set({
          id,
          data,
          digest,
        });
      }
    },
  };
}

watcher

Titre de la section watcher

Type : FSWatcher

En mode dev, il s’agit d’un observateur de système de fichiers qui peut être utilisé pour déclencher des mises à jour. Voir ViteDevServer pour plus d’informations.

Extraire du chargeur file()
return {
  name: 'file-loader',
  load: async ({ config, store, watcher }) => {
    const url = new URL(fileName, config.root);
    const filePath = fileURLToPath(url);
    await syncData(filePath, store);


    watcher?.on('change', async (changedPath) => {
      if (changedPath === filePath) {
        logger.info(`Reloading data from ${fileName}`);
        await syncData(filePath, store);
      }
    });
  },
};

refreshContextData

Titre de la section refreshContextData

Type : Record<string, unknown>

Si le chargeur a été déclenché par une intégration, il peut éventuellement contenir des données supplémentaires définies par cette intégration. Il n’est défini que lorsque le chargeur est déclenché par une intégration. Consultez la référence du hook astro:server:setup pour plus d’informations.

loader.ts
export function myLoader(options: { url: string }): Loader {
  return {
    name: "mon-chargeur",
    load: async ({ refreshContextData, store, logger }) => {
      if(refreshContextData?.webhookBody) {
        logger.info("Webhook déclenché avec le corps");
        processWebhook(store, refreshContextData.webhookBody);
      }
      // ...
    },
  };
}

DataStore

Titre de la section DataStore

Le magasin de données est l’interface d’un chargeur vers les données de la collection de contenu. Il s’agit d’un magasin clé-valeur (abrégé KV en anglais), limité à la collection, et par conséquent, un chargeur ne peut accéder qu’aux données de sa propre collection.

get

Titre de la section get

Type : (key: string) => DataEntry | undefined

Obtenir une entrée du magasin par son ID. Renvoie undefined si l’entrée n’existe pas.

const existingEntry = store.get("my-entry");

L’objet renvoyé est un objet DataEntry.

set

Titre de la section set

Type : (entry: DataEntry) => boolean

Utilisé après que les données ont été validées et analysées pour ajouter une entrée au magasin, renvoyant true si l’entrée a été définie. Renvoie false lorsque la propriété digest détermine qu’une entrée n’a pas changé et ne doit pas être mise à jour.

loader.ts
    for (const item of feed.items) {
      const data = await parseData({
        id: item.guid,
        data: item,
      });
      const digest = generateDigest(data);
      store.set({
        id,
        data,
        rendered: {
          html: data.description ?? "",
        },
        digest,
      });
    }

entries

Titre de la section entries

Type : () => Array<[id: string, DataEntry]>

Obtenir toutes les entrées de la collection sous forme de tableau de paires clé-valeur.

keys

Titre de la section keys

Type : () => Array<string>

Obtenir toutes les clés des entrées de la collection.

values

Titre de la section values

Type : () => Array<DataEntry>

Obtenir toutes les entrées de la collection sous forme de tableau.

delete

Titre de la section delete

Type : (key: string) => void

Supprimer une entrée du magasin par son ID.

clear

Titre de la section clear

Type : () => void

Effacer toutes les entrées de la collection.

has

Titre de la section has

Type : (key: string) => boolean

Vérifier si une entrée existe dans le magasin par son ID.

DataEntry

Titre de la section DataEntry

Il s’agit du type d’objet stocké dans le magasin de données. Il possède les propriétés suivantes :

id

Titre de la section id

Type : string

Un identifiant pour l’entrée, qui doit être unique dans la collection. Il est utilisé pour rechercher l’entrée dans le magasin et constitue la clé utilisée avec getEntry pour cette collection.

data

Titre de la section data

Type : Record<string, unknown>

Les données réelles de l’entrée. Lorsqu’un utilisateur accède à la collection, des types TypeScript seront générés selon le schéma de la collection.

Il est de la responsabilité du chargeur d’utiliser parseData pour valider et analyser les données avant de les stocker dans le magasin de données : aucune validation n’est effectuée lors de l’obtention ou de la définition des données.

filePath

Titre de la section filePath

Type : string | undefined

Chemin d’accès au fichier source de cette entrée, par rapport à la racine du site. Cela s’applique uniquement aux chargeurs basés sur des fichiers et est utilisé pour résoudre des chemins tels que des images ou d’autres ressources.

S’il n’est pas défini, tous les champs du schéma qui utilisent l’assistant image() seront traités comme des chemins publics et non transformés.

body

Titre de la section body

Type : string | undefined

Le corps brut de l’entrée, le cas échéant. Si l’entrée inclut du contenu rendu, ce champ peut être utilisé pour stocker la source brute. Ceci est facultatif et n’est pas utilisé en interne.

digest

Titre de la section digest

Type : string | undefined

Un résumé facultatif du contenu de l’entrée qui peut être utilisé pour vérifier si les données ont changé.

Lors de la définition d’une entrée, l’entrée ne sera mise à jour que si le résumé ne correspond pas à une entrée existante avec le même ID.

Le format du résumé dépend du chargeur, mais il doit s’agir d’une chaîne de caractères qui change lorsque les données changent. Cela peut être fait avec la fonction generateDigest.

rendered

Titre de la section rendered

Type : RenderedContent | undefined

Stocke un objet avec le contenu rendu et les métadonnées d’une entrée si elle a été rendue au format HTML. Par exemple, cela peut être utilisé pour stocker le contenu rendu d’une entrée Markdown ou du code HTML d’un CMS.

Si ce champ est fourni, alors la fonction render() et le composant <Content /> sont disponibles pour restituer l’entrée dans une page.

Le format de l’objet RenderedContent est :

{
  /** Chaîne HTML rendue. Si elle est présente, `render(entry)` renverra un composant qui restitue ce code HTML. */
  html: string;
  metadata?: {
    /** Toutes les images présentes dans cette entrée. Par rapport au chemin d'accès au fichier {@link DataEntry}. */
    imagePaths?: Array<string>;
    /** Tous les titres présents dans ce fichier. Renvoyé comme `headings` par `render()` */
    headings?: MarkdownHeading[];
    /** Frontmatter brut, analysé à partir du fichier. Cela peut inclure des données provenant de plugins Remark. */
    frontmatter?: Record<string, any>;
    /** Toute autre métadonnée présente dans ce fichier. */
    [key: string]: unknown;
  };
}
Contribuer

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Le moyen le plus rapide d'alerter notre équipe d'un problème.

Communauté