Aller au contenu

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

Ajouté à la version : astro@2.0.0

Les collections de contenu proposent des API pour configurer et interroger vos documents Markdown ou MDX dans src/content/. Pour connaître les fonctionnalités et les exemples d’utilisation, consultez notre guide sur les collections de contenu.

Importations depuis astro:content

Titre de la section Importations depuis astro:content
import {
  z,
  defineCollection,
  getCollection,
  getEntry,
  getEntries,
  reference,
 } from 'astro:content';

defineCollection()

Titre de la section defineCollection()

Type : (input: CollectionConfig) => CollectionConfig

Ajouté à la version : astro@2.0.0

defineCollection() est un utilitaire pour configurer une collection dans un fichier src/content.config.*.

src/content.config.ts
import { z, defineCollection } from 'astro:content';
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 `collections`
export const collections = { blog };

Cette fonction accepte les propriétés suivantes :

loader

Titre de la section loader

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

Ajouté à la version : astro@5.0.0

Un loader est soit un objet, soit une fonction qui vous permet de charger des données à partir de n’importe quelle source, locale ou distante, dans des collections de contenu.

Consultez le guide « Collection de contenu » pour un exemple d’utilisation.

schema

Titre de la section schema

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

Ajouté à la version : astro@2.0.0

schema est un objet Zod facultatif pour configurer le type et la forme du document pour une collection. Chaque valeur doit utiliser un validateur Zod.

Consultez le guide Collections de contenu pour un exemple d’utilisation.

reference()

Titre de la section reference()

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

Ajouté à la version : astro@2.5.0

La fonction reference() est utilisée dans la configuration du contenu pour définir une relation, ou une « référence », entre une collection et une autre. Elle accepte un nom de collection et valide le ou les identifiants d’entrée spécifiés dans le frontmatter de votre contenu ou dans votre fichier de données.

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, z } from 'astro:content';
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 };

Consultez le guide Collections de contenu pour un exemple d’utilisation.

getCollection()

Titre de la section getCollection()

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

Ajouté à la version : astro@2.0.0

getCollection() est une fonction qui récupère une liste d’entrées de collection de contenu par nom de collection.

Il 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/content/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;
});
---

Consultez le guide Collections de contenu pour un exemple d’utilisation.

getEntry()

Titre de la section getEntry()

Type : ( collection: string, id: string ) => CollectionEntry<collection> | ({ collection: string, id: string }) => CollectionEntry<collection>

Ajouté à la version : astro@2.5.0

getEntry() est 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');


// Get `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);
---

Consultez le guide Collections de contenu pour des exemples d’interrogation des entrées de collection.

getEntries()

Titre de la section getEntries()

Type : (Array<{ collection: string, id: string }>) => Array<CollectionEntry<collection>>

Ajouté à la version : astro@2.5.0

getEntries() est 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 } 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()

Titre de la section render()

Type : () => Promise<RenderedEntry>

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 :

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

Consultez le guide collections de contenu pour un exemple d’utilisation.

Types d’astro:content

Titre de la section Types d’astro:content
import type {
  CollectionEntry,
  CollectionKey,
  ContentCollectionKey,
  DataCollectionKey,
  SchemaContext,
 } from 'astro:content';

CollectionEntry

Titre de la section 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';

CollectionEntry est un type générique. Utilisez-le avec le nom de la collection que vous interrogez. Par exemple, une entrée de votre collection blog aurait le type CollectionEntry<'blog'>.

Chaque CollectionEntry est un objet avec les valeurs suivantes :

id

Titre de la section id

Exemple de type : 'author-1' | 'author-2' | ...

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

collection

Titre de la section collection

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

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.

data

Titre de la section 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é.

body

Titre de la section body

Type : string

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

CollectionKey

Titre de la section CollectionKey

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 qui accepte n’importe quel nom de collection.

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


async function getCollection(collection: CollectionKey) {
  return getCollection(collection);
}

SchemaContext

Titre de la section 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 :

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


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


const blog = defineCollection({
  loader: /* ... */,
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});
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é