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:contentdefineCollection()
Titre de la section defineCollection()Type : (input: CollectionConfig) => CollectionConfig
defineCollection()
est un utilitaire pour configurer une collection dans un fichier src/content/config.*
.
Cette fonction accepte les propriétés suivantes :
Type : 'content' | 'data'
Par défaut : 'content'
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
)
Cela signifie que les collections ne peuvent pas stocker un mélange de contenus et de formats de données. Vous devez diviser ces entrées en collections distinctes par type.
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()
Titre de la section reference()Type : (collection: string) => ZodEffects<ZodString, { collection, id: string } | { collection, slug: string }>
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
:
Consultez le guide Collections de contenu pour un exemple d’utilisation.
getCollection()
Titre de la section 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
.
Consultez le guide Collections de contenu pour un exemple d’utilisation.
getEntry()
Titre de la section 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()
:
Consultez le guide Collections de contenu pour des exemples d’interrogation des entrées de collection.
getEntries()
Titre de la section 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.
getEntryBySlug()
Titre de la section getEntryBySlug()Type : (collection: string, slug: string) => Promise<CollectionEntry<TCollectionName>>
Utilisez la fonction getEntry()
pour interroger les entrées de contenu. Elle accepte les mêmes arguments que getEntryBySlug()
et prend en charge les requêtes par id
pour les collections JSON ou YAML.
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.
Consultez le guide Collections de contenu pour un exemple d’utilisation.
getDataEntryById()
Titre de la section getDataEntryById()Type : (collection: string, id: string) => Promise<CollectionEntry<TCollectionName>>
astro@2.5.0
Utilisez la fonction getEntry()
pour interroger les entrées de données. Cela accepte les mêmes arguments que getDataEntryById()
et prend en charge l’interrogation par slug
pour les formats de création de contenu comme Markdown.
getDataEntryById()
est une fonction qui récupère une seule entrée de collection par nom de collection et par id
d’entrée.
Types d’astro:content
Titre de la section Types d’astro:contentCollectionEntry
Titre de la section CollectionEntryLes 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
:
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 :
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
Titre de la section collectionDisponible 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.
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é.
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.
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()
Titre de la section 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’utilitairegetHeadings()
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 typeany
.
Consultez le guide Collections de contenu pour un exemple d’utilisation.
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.
ContentCollectionKey
Titre de la section 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
Titre de la section 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
Titre de la section SchemaContextL’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émaimage()
qui vous permet d’utiliser des images locales dans les collections de contenu