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

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

import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
  type: 'content',
  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 :

`type`

Type : 'content' | 'data'
Par défaut : 'content'

Ajouté à la version : astro@2.5.0

type est une chaîne de caractères qui définit le type d’entrées stockées dans une collection :

'content' - pour les formats de création de contenu comme Markdown (.md), MDX (.mdx) ou Markdoc (.mdoc)
'data' - pour les formats de données uniquement comme JSON (.json) ou YAML (.yaml)

`schema`

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

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 } | { collection, slug: 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';

const blog = defineCollection({
  type: 'content',
  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({
  type: 'data',
  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<TCollectionName>) => boolean) => CollectionEntry<TCollectionName>[]

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

Ajouté à la version : astro@2.5.0

Types :

(collection: string, contentSlugOrDataId: string) => CollectionEntry<TCollectionName>
({ collection: string, id: string }) => CollectionEntry<TCollectionName>
({ collection: string, slug: string }) => CollectionEntry<TCollectionName>

getEntry() est une fonction qui récupère une seule entrée de collection en utilisant le nom de la collection et soit l’entrée id (pour les collections utilisant type: 'data') soit l’entrée slug (pour les collections utilisant type: 'content'). getEntry() peut également être utilisée pour obtenir des entrées référencées pour accéder aux propriétés data, body ou render() :

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

Ajouté à la version : astro@2.5.0

Types :

(Array<{ collection: string, id: string }>) => CollectionEntry<TCollectionName>[]
(Array<{ collection: string, slug: string }>) => CollectionEntry<TCollectionName>[]

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 pour accéder à leurs propriétés data, body et render() associées.

---
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);
---

`getEntryBySlug()`

Type : (collection: string, slug: string) => Promise<CollectionEntry<TCollectionName>>

getEntryBySlug() est une fonction qui récupère une seule entrée de collection en utilisant le nom de la collection et le slug d’une entrée.

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

const enterprise = await getEntryBySlug('blog', 'enterprise');
---

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

`getDataEntryById()`

Type : (collection: string, id: string) => Promise<CollectionEntry<TCollectionName>>

Ajouté à la version : astro@2.5.0

getDataEntryById() est une fonction qui récupère une seule entrée de collection par nom de collection et par id d’entrée.

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

const picardProfile = await getDataEntryById('captains', 'picard');
---

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`

Disponible pour : les collections utilisant type: 'content' ou type: 'data'
Exemple de types :

collections de contenu : 'entry-1.md' | 'entry-2.md' | ...
collections de données : 'author-1' | 'author-2' | ...

Un identifiant unique utilisant le chemin du fichier relatif à src/content/[collection]. Énumère toutes les valeurs de chaîne de caractères possibles en fonction des chemins d’accès au fichier d’entrée de collection. Notez que les collections définies comme type: 'content' incluent l’extension de fichier dans leur identifiant, contrairement aux collections définies comme type: 'data'.

`collection`

Disponible pour : les collections utilisant type: 'content' ou type: 'data'
Exemple de type : 'blog' | 'authors' | ...

Le nom d’un dossier placé à la racine de src/content/ et dans lequel 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`

Disponible pour : les collections utilisant type: 'content' ou type: '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é.

`slug`

Disponible pour : les collections utilisant type: 'content' seulement
Exemple de type : 'entry-1' | 'entry-2' | ...

Un slug d’URL préparé pour les documents Markdown ou MDX. La valeur par défaut est id sans l’extension de fichier, mais peut être remplacée en définissant la propriété slug dans le frontmatter d’un fichier.

`body`

Disponible pour : les collections utilisant type: 'content' seulement
Type : string

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

`render()`

Disponible pour : les collections utilisant type: 'content' seulement
Type : () => Promise<RenderedEntry>

Une fonction pour compiler un document Markdown ou MDX donné à afficher. Cela 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 l’application de plugins Remark or Rehype. Définit sur le type any.

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

const { Content, headings, remarkPluginFrontmatter } = await entry.render();
---

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

`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);
}

`ContentCollectionKey`

Ajouté à la version : astro@3.1.0

Une union de chaînes de caractères de tous les noms des collections type: 'content' définies dans votre fichier src/content/config.*.

`DataCollectionKey`

Ajouté à la version : astro@3.1.0

Une union de chaînes de caractères de tous les noms de la collection type: 'data' définie dans votre fichier src/content/config.*.

`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({
  type: 'content',
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});

Contribuer

Communauté

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

Importations depuis `astro:content`

`defineCollection()`

`type`

`schema`

`reference()`

`getCollection()`

`getEntry()`

`getEntries()`

`getEntryBySlug()`

`getDataEntryById()`

Types d’`astro:content`

`CollectionEntry`

`id`

`collection`

`data`

`slug`

`body`

`render()`

`CollectionKey`

`ContentCollectionKey`

`DataCollectionKey`

`SchemaContext`

Comment pouvons-nous vous aider ?

Créer une issue GitHub

Envoyez-nous un commentaire

Envoyez-nous un commentaire

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

Importations depuis astro:content

defineCollection()

type

schema

reference()

getCollection()

getEntry()

getEntries()

getEntryBySlug()

getDataEntryById()

Types d’astro:content

CollectionEntry

id

collection

data

slug

body

render()

CollectionKey

ContentCollectionKey

DataCollectionKey

SchemaContext

Importations depuis `astro:content`

`defineCollection()`

`type`

`schema`

`reference()`

`getCollection()`

`getEntry()`

`getEntries()`

`getEntryBySlug()`

`getDataEntryById()`

Types d’`astro:content`

`CollectionEntry`

`id`

`collection`

`data`

`slug`

`body`

`render()`

`CollectionKey`

`ContentCollectionKey`

`DataCollectionKey`

`SchemaContext`