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`

import {
  z,
  defineCollection,
  getCollection,
  getEntry,
  getEntries,
  reference,
 } from 'astro:content';

`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.*.

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`

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`

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()`

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()`

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()`

Types :

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

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()`

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()`

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 :

<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 plugins Remark ou Rehype ont été appliqués. Définit sur le type any.

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

if (!entry) {
   // Gérer l'erreur, par exemple :
  throw new Error('Could not find blog post 1');
}
const { Content, headings, remarkPluginFrontmatter } = await render(entry);
---

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

Types d’`astro:content`

import type {
  CollectionEntry,
  CollectionKey,
  ContentCollectionKey,
  DataCollectionKey,
  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';

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`

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`

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`

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`

Type : string

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

`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`

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 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 Communauté Parrainer

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

Importations depuis astro:content

defineCollection()

loader

schema

reference()

getCollection()

getEntry()

getEntries()

render()

Types d’astro:content

CollectionEntry

id

collection

data

body

CollectionKey

SchemaContext

Importations depuis `astro:content`

`defineCollection()`

`loader`

`schema`

`reference()`

`getCollection()`

`getEntry()`

`getEntries()`

`render()`

Types d’`astro:content`

`CollectionEntry`

`id`

`collection`

`data`

`body`

`CollectionKey`

`SchemaContext`