From c469d6667e08d731dc704d2ad331f89009ed04e2 Mon Sep 17 00:00:00 2001 From: Armand Philippot Date: Sat, 26 Oct 2024 14:18:06 +0200 Subject: [PATCH] i18n(fr): create `reference/modules/astro-content.mdx` See #9687 and #9821 --- .../fr/reference/modules/astro-content.mdx | 376 ++++++++++++++++++ 1 file changed, 376 insertions(+) create mode 100644 src/content/docs/fr/reference/modules/astro-content.mdx diff --git a/src/content/docs/fr/reference/modules/astro-content.mdx b/src/content/docs/fr/reference/modules/astro-content.mdx new file mode 100644 index 0000000000000..59c90d06611fb --- /dev/null +++ b/src/content/docs/fr/reference/modules/astro-content.mdx @@ -0,0 +1,376 @@ +--- +title: Référence de l'API des collections de contenu +i18nReady: true +tableOfContents: + minHeadingLevel: 2 + maxHeadingLevel: 6 +--- +import Since from '~/components/Since.astro'; +import ReadMore from '~/components/ReadMore.astro'; + +

+ +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](/fr/guides/content-collections/). + +## Importations depuis `astro:content` + +```js +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.*`. + +```ts +// src/content/config.ts +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'`
+ +

+ +`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`) + +:::tip +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. +::: + +#### `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](https://github.com/colinhacks/zod). + +[Consultez le guide Collections de contenu](/fr/guides/content-collections/#définition-dun-schéma-de-collection) pour un exemple d'utilisation. + +### `reference()` + +

+ +**Type :** `(collection: string) => ZodEffects`
+ +

+ +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` : + +```ts +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](/fr/guides/content-collections/#définition-des-références-de-collection) pour un exemple d'utilisation. + +### `getCollection()` + +

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

+ +`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`. + +```astro +--- +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](/fr/guides/content-collections/#interroger-les-collections) pour un exemple d'utilisation. + +### `getEntry()` + +

+ +**Types :** +- `(collection: string, contentSlugOrDataId: string) => CollectionEntry` +- `({ collection: string, id: string }) => CollectionEntry` +- `({ collection: string, slug: string }) => CollectionEntry` + +`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()` : + +```astro +--- +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](/fr/guides/content-collections/#interroger-les-collections). + +### `getEntries()` + +

+ +**Types :** +- `(Array<{ collection: string, id: string }>) => CollectionEntry[]` +- `(Array<{ collection: string, slug: string }>) => CollectionEntry[]` + +`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](/fr/guides/content-collections/#définition-des-références-de-collection) pour accéder à leurs propriétés `data`, `body` et `render()` associées. + +```astro +--- +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>` +

+ +:::caution[Obsolète] +Utilisez la fonction [`getEntry()`](#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. + + +```astro +--- +import { getEntryBySlug } from 'astro:content'; + +const enterprise = await getEntryBySlug('blog', 'enterprise'); +--- +``` + +[Consultez le guide Collections de contenu](/fr/guides/content-collections/#interroger-les-collections) pour un exemple d'utilisation. + +### `getDataEntryById()` + +

+ +**Type :** `(collection: string, id: string) => Promise>`
+ +

+ +:::caution[Obsolète] +Utilisez la [fonction `getEntry()`](#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. + + +```astro +--- +import { getDataEntryById } from 'astro:content'; + +const picardProfile = await getDataEntryById('captains', 'picard'); +--- +``` + +## Types d'`astro:content` + +```ts +import type { + CollectionEntry, + CollectionKey, + ContentCollectionKey, + DataCollectionKey, + SchemaContext, + } from 'astro:content'; +``` + +### `CollectionEntry` + +Les fonctions de requête, notamment [`getCollection()`](#getcollection), [`getEntry()`](#getentry) et [`getEntries()`](#getentries) renvoient chacune des entrées avec le type `CollectionEntry`. Ce type est disponible en tant qu'utilitaire depuis `astro:content` : + +```ts +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'`](#type) 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` + +Un objet de propriétés provenant du frontmatter et déduit de votre schéma de collection ([voir la référence `defineCollection()`](#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`](/fr/guides/content-collections/#définition-dun-slug-personnalisé) 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` + +Une fonction pour compiler un document Markdown ou MDX donné à afficher. Cela renvoie les propriétés suivantes : + +- `` - 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](/fr/guides/markdown-content/#propriétés-disponibles) sur les importations Markdown et MDX. +- `remarkPluginFrontmatter` - L'objet frontmatter modifié après [l'application de plugins Remark or Rehype](/fr/guides/markdown-content/#modification-programmatique-du-frontmatter). Définit sur le type `any`. + +```astro +--- +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](/fr/guides/content-collections/#rendre-le-contenu-en-html) pour un exemple d'utilisation. + +### `CollectionKey` + +

+ +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. + +```ts +import { type CollectionKey, getCollection } from 'astro:content'; + +async function getCollection(collection: CollectionKey) { + return getCollection(collection); +} +``` + +### `ContentCollectionKey` + +

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

+ +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](/fr/guides/images/#images-dans-les-collections-de-contenus) + +```ts +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 }) + }), +}); +```