Référence de l'API des collections de contenu

Ajouté à la version : astro@2.0.0

Les collections de contenu consommées lors de la compilation offrent des API permettant de configurer, d’interroger et d’effectuer le rendu de vos fichiers Markdown, MDX, Markdoc, YAML, TOML ou JSON locaux, ainsi que du contenu distant.

Ajouté à la version : astro@6.0.0 Nouveau

Les collections de contenu en direct offrent des API permettant de configurer, d’interroger et d’afficher des données en direct, actualisées en temps réel, provenant de sources distantes.

Pour les fonctionnalités et des exemples d’utilisation, consultez notre guide sur les collections de contenu.

Importations depuis `astro:content`

import {
  defineCollection,
  defineLiveCollection,
  getCollection,
  getLiveCollection,
  getEntry,
  getLiveEntry,
  getEntries,
  reference,
  render
} from 'astro:content';

`defineCollection()`

Type : (input: CollectionConfig) => CollectionConfig

Ajouté à la version : astro@2.0.0

Un utilitaire pour configurer une collection dans un fichier src/content.config.*.

import { defineCollection } from 'astro:content';
import { z } from 'astro/zod';
import { glob } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});

// Exposez votre collection définie à Astro
// avec l'exportation de `collections`
export const collections = { blog };

Cette fonction accepte les propriétés suivantes :

`loader`

Type : () => Promise<Array<{ id: string, [key: string]: any }> | Record<string, Record<string, any>>> | Loader

Ajouté à la version : astro@5.0.0

Un objet ou une fonction permettant de charger des données depuis n’importe quelle source, locale ou distante, dans une collection de contenu consommée lors de la compilation. (Pour les collections en direct, consultez la propriété loader pour les chargeurs en direct.)

Découvrez les chargeurs de collections appelés lors de la compilation avec des explications guidées et des exemples d’utilisation.

`schema`

Type : ZodType | (context: SchemaContext) => ZodType

Ajouté à la version : astro@2.0.0

Un objet ou une fonction Zod, optionnel, qui renvoie un objet Zod pour configurer le type et la structure des métadonnées d’un document pour une collection. Chaque valeur doit utiliser un validateur Zod. (Pour les collections en direct, consultez la propriété schema des collections en direct.)

Découvrez la définition d’un schéma de collection à l’aide de Zod avec des explications guidées, des exemples d’utilisation et des types de données courants.

`defineLiveCollection()`

Type : (config: LiveCollectionConfig) => LiveCollectionConfig

Ajouté à la version : astro@6.0.0 Nouveau

Un utilitaire permettant de configurer une collection en direct dans un fichier src/live.config.*.

import { defineLiveCollection } from 'astro:content';
import { storeLoader } from '@example/astro-loader';

const produits = defineLiveCollection({
  loader: storeLoader({
    apiKey: process.env.STORE_API_KEY,
    endpoint: 'https://api.example.com/v1',
  }),
});

// Exposez votre collection définie à Astro
// avec l'exportation de `collections`
export const collections = { produits };

Cette fonction accepte les propriétés suivantes :

`loader`

Type : LiveLoader

Ajouté à la version : astro@6.0.0 Nouveau

Un objet permettant de charger des données à l’exécution depuis une source distante dans une collection de contenu en direct. (Pour les collections consommées lors de la compilation, voir la propriété loader utilisée au moment de la compilation.)

Apprenez comment créer un chargeur en direct avec des explications guidées et des exemples d’utilisation.

`schema`

Type : ZodType

Ajouté à la version : astro@6.0.0 Nouveau

Un objet Zod optionnel permet de configurer le type et la structure de vos données pour une collection en direct. Chaque valeur doit utiliser un validateur Zod. (Pour les collections consommées lors de la compilation, consultez la propriété schema utilisée au moment de la compilation.)

Lorsque vous définissez un schéma, celui-ci aura la priorité sur les types du chargeur en direct lorsque vous interrogez la collection.

Apprenez à utiliser les schémas Zod avec les collections en direct grâce à des explications guidées et des exemples d’utilisation.

`reference()`

Type : (collection: CollectionKey) => ZodEffects<ZodString, { collection: CollectionKey, id: string }>

Ajouté à la version : astro@2.5.0

Une fonction utilisée dans la configuration du contenu pour définir une relation, ou « référence », entre une collection et une autre. Elle accepte un nom de collection et transforme la référence en un objet contenant le nom de la collection et l’identifiant de référence.

Cet exemple définit les références d’un auteur de blog à la collection authors et un tableau d’articles associés à la même collection blog :

import { defineCollection, reference } from 'astro:content';
import { z } from 'astro/zod';
import { glob, file } from 'astro/loaders';

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: z.object({
    // Référence un seul auteur de la collection `authors` par `id`
    author: reference('authors'),
    // Référence un tableau d'articles connexes de la collection `blog` par `slug`
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  loader: file("src/data/authors.json"),
  schema: z.object({ /* ... */ })
});

export const collections = { blog, authors };

La validation des entrées référencées se produit au moment de l’exécution lors de l’utilisation de getEntry() ou getEntries() :

// si une entrée référencée n'est pas valide, cela renverra undefined.
const relatedPosts = await getEntries(blogPost.data.relatedPosts);

Apprenez à définir et utiliser les références de collection grâce à des explications guidées et des exemples d’utilisation.

`getCollection()`

Type : (collection: CollectionKey, filter?: (entry: CollectionEntry) => boolean) => CollectionEntry[]

Ajouté à la version : astro@2.0.0

Une fonction qui récupère une liste d’entrées de collection de contenu par nom de collection.

Elle renvoie tous les éléments de la collection par défaut et accepte une fonction facultative filter pour affiner les propriétés d’entrée. Cela vous permet d’interroger uniquement certains éléments d’une collection en fonction de id ou des valeurs du frontmatter via l’objet data.

---
import { getCollection } from 'astro:content';

// Récupère toutes les entrées `src/data/blog/`
const allBlogPosts = await getCollection('blog');

// Ne renvoie que les messages avec `draft: true` dans le frontmatter
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

Apprenez à interroger les collections consommées lors de la compilation avec des explications guidées et des exemples d’utilisation.

`getLiveCollection()`

Type : (collection: string, filter?: LiveLoaderCollectionFilterType) => Promise<LiveDataCollectionResult>

Ajouté à la version : astro@6.0.0 Nouveau

Une fonction qui récupère la liste des entrées de collection de contenu en direct par nom de collection.

Elle renvoie par défaut tous les éléments de la collection et accepte un objet filter optionnel dont la structure est définie par le chargeur de la collection. Cela vous permet d’interroger uniquement certains éléments d’une collection ou de récupérer des données sous un format différent, selon les capacités de votre API.

---
import { getLiveCollection } from 'astro:content';

// Récupérer toutes les entrées de produits depuis votre API
const { entries: allProducts } = await getLiveCollection('produits');

// Ne renvoyer que les produits qui devraient être mis en avant.
const { entries: featuredProducts } = await getLiveCollection('produits', { featured: true });
---

Apprenez comment accéder aux données des collections en direct grâce à des explications guidées et des exemples d’utilisation.

`getEntry()`

Types :

(collection: CollectionKey, id: string) => Promise<CollectionEntry | undefined>
({ collection: CollectionKey, id: string }) => Promise<CollectionEntry | undefined>

Ajouté à la version : astro@2.5.0

Une fonction qui récupère une seule entrée de collection par nom de collection et l’entrée id. getEntry() peut également être utilisée pour obtenir des entrées référencées pour accéder aux propriétés data ou body :

---
import { getEntry } from 'astro:content';

// Récupère `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');

// Récupère `src/content/captains/picard.json`
const picardProfile = await getEntry('captains', 'picard');

// Récupère le profil référencé par `data.captain`
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

Apprenez-en davantage sur l’interrogation des collections consommées lors de la compilation grâce à des explications guidées et des exemples d’utilisation.

`getLiveEntry()`

Type : (collection: string, filter: string | LiveLoaderEntryFilterType) => Promise<LiveDataEntryResult>

Ajouté à la version : astro@6.0.0 Nouveau

Une fonction qui récupère une seule entrée de collection en direct par nom de collection et un filtre facultatif, soit sous forme de chaîne de caractères correspondant à l’id, soit sous forme d’objet avec sûreté du typage.

---
import { getLiveEntry } from 'astro:content';

const { entry: liveCollectionsPost } = await getLiveEntry('blog', Astro.params.id);
const { entry: mattDraft } = await getLiveEntry('blog', {
  status: 'draft',
  author: 'matt',
});
---

Apprenez comment accéder aux données des collections en direct grâce à des explications guidées et des exemples d’utilisation.

`getEntries()`

Type : ({ collection: CollectionKey, id: string }[]) => CollectionEntry[]

Ajouté à la version : astro@2.5.0

Une fonction qui récupère plusieurs entrées dans une même collection. Ceci est utile pour renvoyer un tableau d’entrées référencées afin d’accéder à leurs propriétés associées data et body.

---
import { getEntries, getEntry } from 'astro:content';

const enterprisePost = await getEntry('blog', 'enterprise');

// Récupère les articles associés référencés par `data.ratedPosts`
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

`render()`

Type : (entry: CollectionEntry) => Promise<RenderResult>

Ajouté à la version : astro@5.0.0

Une fonction permettant de compiler une entrée donnée pour le rendu. Elle renvoie les propriétés suivantes :

<Content /> - Un composant utilisé pour restituer le contenu du document dans un fichier Astro.
headings - Une liste générée de titres, reflétant l’utilitaire getHeadings() d’Astro sur les importations Markdown et MDX.
remarkPluginFrontmatter - L’objet frontmatter modifié après que tous les modules d’extension Remark ou Rehype ont été appliqués. Définit sur le type any.

---
import { getEntry, render } from 'astro:content';
const entry = await getEntry('blog', 'article-1');

if (!entry) {
   // Gérer l'erreur, par exemple :
  throw new Error("Impossible de trouver l'article de blog 1");
}
const { Content, headings, remarkPluginFrontmatter } = await render(entry);
---

Apprenez comment restituer le contenu des entrées avec des explications guidées et des exemples d’utilisation.

Types d’`astro:content`

import type {
  CollectionEntry,
  CollectionKey,
  SchemaContext,
} from 'astro:content';

`CollectionEntry`

Les fonctions de requête, notamment getCollection(), getEntry() et getEntries() renvoient chacune des entrées avec le type CollectionEntry. Ce type est disponible en tant qu’utilitaire depuis astro:content :

import type { CollectionEntry } from 'astro:content';

Un type générique à utiliser avec le nom de la collection interrogée pour représenter une entrée unique de cette collection. Par exemple, une entrée de votre collection blog aurait le type CollectionEntry<'blog'>.

Chaque CollectionEntry est un objet avec les valeurs suivantes :

`CollectionEntry.id`

Type : string

Un identifiant unique. Notez que tous les identifiants du chargeur glob() intégré d’Astro sont transformés en slug.

`CollectionEntry.collection`

Type : CollectionKey

Le nom d’une collection dans laquelle se trouvent les entrées. Il s’agit du nom utilisé pour référencer la collection dans votre schéma et dans les fonctions de requête.

`CollectionEntry.data`

Type : CollectionSchema<TCollectionName>

Un objet de propriétés provenant du frontmatter et déduit de votre schéma de collection (voir la référence defineCollection()). La valeur par défaut est any si aucun schéma n’est configuré.

`CollectionEntry.body`

Type : string | undefined

Une chaîne de caractères contenant le corps brut et non compilé du document Markdown ou MDX.

Notez que si retainBody est défini sur false, cette valeur sera undefined au lieu de contenir le contenu brut du fichier.

`CollectionEntry.rendered`

Type : RenderedContent | undefined

Le contenu rendu d’une entrée tel qu’enregistré par votre chargeur. Par exemple, il peut s’agir du contenu rendu d’une entrée Markdown ou de code HTML provenant d’un CMS.

`CollectionEntry.filePath`

Type : string | undefined

Le chemin d’accès à une entrée, relatif à votre répertoire de projet. Cette valeur n’est disponible que pour les entrées locales.

`CollectionKey`

Exemple de type : 'blog' | 'authors' | ...

Ajouté à la version : astro@3.1.0

Une union de chaînes de caractères de tous les noms de collections définis dans votre fichier src/content.config.*. Ce type peut être utile lors de la définition d’une fonction générique enveloppant la fonction intégrée getCollection().

import { type CollectionKey, getCollection } from 'astro:content';

export async function queryCollection(collection: CollectionKey) {
  return getCollection(collection, ({ data }) => {
    return data.draft !== true;
  });
}

`SchemaContext`

L’objet context que defineCollection utilise pour la forme de fonction du schema. Ce type peut être utile lors de la création de schémas réutilisables pour plusieurs collections.

Il inclut la propriété suivante :

image - L’assistant de schéma image() qui vous permet d’utiliser des images locales dans les collections de contenu

import { defineCollection, type SchemaContext } from "astro:content";
import { z } from 'astro/zod';
import { glob } from 'astro/loaders';

export const imageSchema = ({ image }: SchemaContext) =>
    z.object({
        image: image(),
        description: z.string().optional(),
    });

const blog = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/data/blog' }),
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});

Types d’`astro`

import type {
  LiveDataCollectionResult,
  LiveDataEntryResult,
} from "astro";

`LiveDataCollectionResult`

Type : { entries?: Array<LiveDataEntry<TData>>; error?: TError | LiveCollectionError; cacheHint?: CacheHint; }

Ajouté à la version : astro@6.0.0 Nouveau

Un objet renvoyé par getLiveCollection() contenant les données récupérées par le chargeur en direct. Il possède les propriétés suivantes :

`LiveDataCollectionResult.entries`

Type : Array<LiveDataEntry<TData>> | undefined

Un tableau d’objets LiveDataEntry renvoyés par le chargeur.

L’exemple suivant accède aux entrées renvoyées par une collection en direct nommée produits :

---
import { getLiveCollection } from 'astro:content';

const { entries: allProducts } = await getLiveCollection('produits');
---

Apprenez comment accéder aux données en direct grâce à des explications guidées et des exemples d’utilisation.

`LiveDataCollectionResult.error`

Type : TError | LiveCollectionError | undefined

Une erreur renvoyée lorsque le chargeur n’a pas pu charger la collection. Il peut s’agir d’une erreur personnalisée définie par le chargeur ou d’une erreur intégrée.

L’exemple suivant accède à l’erreur renvoyée lors de la récupération de données à partir d’une collection en direct nommée produits :

---
import { getLiveCollection } from 'astro:content';

const { error } = await getLiveCollection('produits');
---

Apprenez-en davantage sur la gestion des erreurs grâce à des explications guidées et des exemples d’utilisation.

`LiveDataCollectionResult.cacheHint`

Type : CacheHint | undefined

Un objet fournissant des instructions sur la manière de mettre en cache cette collection.

Si vous avez activé la mise en cache expérimentale des routes (EN), transmettez directement l’indication de cache à Astro.cache.set() :

---
import { getLiveCollection } from 'astro:content';
export const prerender = false; // Pas nécessaire en mode `server`

const { cacheHint } = await getLiveCollection('produits');

if (cacheHint) {
  Astro.cache.set(cacheHint);
}
Astro.cache.set({ maxAge: 600 });
---

Vous pouvez également utiliser les indications de cache pour définir manuellement les en-têtes de réponse :

---
import { getLiveCollection } from 'astro:content';

const { cacheHint } = await getLiveCollection('produits');

if (cacheHint?.tags) {
  Astro.response.headers.set('Cache-Tag', cacheHint.tags.join(','));
}
if (cacheHint?.lastModified) {
  Astro.response.headers.set('Last-Modified', cacheHint.lastModified.toUTCString());
}
---

`LiveDataEntryResult`

Type : { entry?: LiveDataEntry<TData>; error?: TError | LiveCollectionError; cacheHint?: CacheHint; }

Ajouté à la version : astro@6.0.0 Nouveau

Un objet renvoyé par getLiveEntry() contenant les données récupérées par le chargeur en direct. Il possède les propriétés suivantes :

`LiveDataEntryResult.entry`

Type : LiveDataEntry<TData> | undefined

L’objet LiveDataEntry renvoyé par le chargeur.

L’exemple suivant accède à l’entrée demandée dans une collection en direct nommée produits :

---
import { getLiveEntry } from 'astro:content';

const { entry } = await getLiveEntry('produits', Astro.params.id);
---

Apprenez comment accéder aux données en direct grâce à des explications guidées et des exemples d’utilisation.

`LiveDataEntryResult.error`

Type : TError | LiveCollectionError | undefined

Une erreur renvoyée lorsque le chargeur n’a pas pu charger l’entrée. Il peut s’agir d’une erreur personnalisée définie par le chargeur ou d’une erreur intégrée.

L’exemple suivant récupère l’entrée demandée et toute erreur possible depuis une collection en direct nommée produits, puis redirige vers la page 404 si une erreur existe :

---
import { getLiveEntry } from 'astro:content';

const { entry, error } = await getLiveEntry('produits', Astro.params.id);

if (error) {
  return Astro.redirect('/404');
}
---
<h1>{entry.data.name}</h1>

Apprenez-en davantage sur la gestion des erreurs grâce à des explications guidées et des exemples d’utilisation.

`LiveDataEntryResult.cacheHint`

Type : CacheHint | undefined

Un objet fournissant des données pouvant servir à définir une stratégie de mise en cache.

Si vous avez activé la mise en cache expérimentale des routes (EN), transmettez directement l’indication de cache à Astro.cache.set() :

---
import { getLiveEntry } from 'astro:content';

export const prerender = false; // Pas nécessaire en mode `server`

const { cacheHint } = await getLiveEntry('produits', Astro.params.id);

if (cacheHint) {
  Astro.cache.set(cacheHint);
}
Astro.cache.set({ maxAge: 300 });
---

Vous pouvez également utiliser les indications de cache pour définir manuellement les en-têtes de réponse :

---
import { getLiveEntry } from 'astro:content';

const { cacheHint } = await getLiveEntry('produits', Astro.params.id);

if (cacheHint?.tags) {
  Astro.response.headers.set('Cache-Tag', cacheHint.tags.join(','));
}
if (cacheHint?.lastModified) {
  Astro.response.headers.set('Last-Modified', cacheHint.lastModified.toUTCString());
}
---

Contribuer Communauté Parrainer

Référence de l'API des collections de contenu

Importations depuis astro:content

defineCollection()

loader

schema

defineLiveCollection()

loader

schema

reference()

getCollection()

getLiveCollection()

getEntry()

getLiveEntry()

getEntries()

render()

Types d’astro:content

CollectionEntry

CollectionEntry.id

CollectionEntry.collection

CollectionEntry.data

CollectionEntry.body

CollectionEntry.rendered

CollectionEntry.filePath

CollectionKey

SchemaContext

Types d’astro

LiveDataCollectionResult

LiveDataCollectionResult.entries

LiveDataCollectionResult.error

LiveDataCollectionResult.cacheHint

LiveDataEntryResult

LiveDataEntryResult.entry

LiveDataEntryResult.error

LiveDataEntryResult.cacheHint

Importations depuis `astro:content`

`defineCollection()`

`loader`

`schema`

`defineLiveCollection()`

`loader`

`schema`

`reference()`

`getCollection()`

`getLiveCollection()`

`getEntry()`

`getLiveEntry()`

`getEntries()`

`render()`

Types d’`astro:content`

`CollectionEntry`

`CollectionEntry.id`

`CollectionEntry.collection`

`CollectionEntry.data`

`CollectionEntry.body`

`CollectionEntry.rendered`

`CollectionEntry.filePath`

`CollectionKey`

`SchemaContext`

Types d’`astro`

`LiveDataCollectionResult`

`LiveDataCollectionResult.entries`

`LiveDataCollectionResult.error`

`LiveDataCollectionResult.cacheHint`

`LiveDataEntryResult`

`LiveDataEntryResult.entry`

`LiveDataEntryResult.error`

`LiveDataEntryResult.cacheHint`