Bibliothèque de médias

EmDash inclut une bibliothèque de médias pour gérer les images, documents et autres fichiers. Ce guide couvre le téléchargement, la recherche et l’utilisation des médias dans votre contenu.

Accéder à la bibliothèque de médias

Ouvrez la bibliothèque de médias depuis la barre latérale d’administration en cliquant sur Médias. La bibliothèque principale affiche les dossiers et les fichiers qui ne sont pas assignés à un dossier. Ouvrez un dossier pour voir ses fichiers.

Utilisé dans

Ouvrez un fichier dans la bibliothèque de médias d’EmDash pour voir les entrées de contenu qui le référencent. Pendant qu’EmDash analyse le contenu existant, la liste inclut les références trouvées jusqu’à présent et peut être incomplète.

Activer le suivi d’utilisation des médias

Si le suivi d’utilisation des médias est désactivé, un administrateur peut l’activer :

1. Terminez toute modification de contenu. Si une autre application écrit directement dans la base de données de contenu, mettez-la en pause et attendez que les écritures en cours soient terminées.
2. Ouvrez Paramètres → Suivi d’utilisation des médias, sélectionnez Activer le suivi, puis confirmez.
3. Lorsque la page affiche Indexation du contenu existant, les modifications et autres écritures de base de données peuvent reprendre.
4. Gardez la page ouverte jusqu’à ce qu’elle affiche Prêt. Si vous quittez, revenez pour continuer depuis la progression sauvegardée.

Une fois le suivi d’utilisation des médias activé, il ne peut pas être désactivé.

Télécharger des fichiers

Depuis la bibliothèque de médias

1. Ouvrez Médias dans la barre latérale d’administration.

2. Sélectionnez Télécharger des fichiers, puis Parcourir les fichiers pour choisir un ou plusieurs fichiers. Vous pouvez aussi glisser-déposer des fichiers n’importe où dans la bibliothèque de médias.

3. Les téléchargements démarrent automatiquement. La boîte de dialogue affiche le statut de chaque fichier et permet d’annuler ou de réessayer des fichiers individuels.

Depuis l’éditeur de contenu

1. Ouvrez un champ image, fichier ou galerie dans l’éditeur de contenu.

2. Recherchez, filtrez par type, parcourez un dossier ou basculez entre les sources de médias disponibles.

3. Sélectionnez des médias existants, ou sélectionnez Télécharger des fichiers et choisissez des fichiers depuis votre ordinateur. Vous pouvez aussi déposer des fichiers sur le sélecteur. Chaque téléchargement apparaît dans les résultats avec son statut actuel.

4. Si un téléchargement échoue, sélectionnez Réessayer ou Supprimer sur cet élément. Un téléchargement réussi devient une carte de média sélectionnée.

5. Pour une galerie, utilisez les contrôles de flèches sous Médias sélectionnés pour définir l’ordre.

6. Sélectionnez l’action du sélecteur, comme Sélectionner, Insérer l’image ou Ajouter 3 images.

Types de fichiers supportés

EmDash accepte ces types de fichiers par défaut :

Les champs image et fichier peuvent autoriser d’autres types MIME, y compris image/svg+xml pour les fichiers SVG.

Backends de stockage

EmDash supporte plusieurs backends de stockage. Configurez le stockage dans votre configuration Astro :

import { defineConfig } from "astro/config";
import emdash, { local } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: local({
        directory: "./uploads",
        baseUrl: "/_emdash/api/media/file",
      }),
    }),
  ],
});

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      storage: r2({
        binding: "MEDIA_BUCKET",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

{
	"r2_buckets": [
		{
			"binding": "MEDIA_BUCKET",
			"bucket_name": "my-media-bucket",
		},
	],
}

import { defineConfig } from "astro/config";
import emdash, { s3 } from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      storage: s3({
        endpoint: "https://s3.amazonaws.com",
        bucket: "my-media-bucket",
        accessKeyId: process.env.S3_ACCESS_KEY_ID,
        secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
        region: "us-east-1",
        publicUrl: "https://media.example.com",
      }),
    }),
  ],
});

Comment fonctionnent les téléchargements

L’admin utilise le flux de cible de téléchargement :

1. Le client demande une cible de téléchargement, et EmDash crée un élément multimédia en attente.

2. Le client télécharge le fichier vers la cible retournée.

3. Le client confirme le téléchargement.

4. EmDash valide le fichier stocké et marque l’élément multimédia comme prêt.

Le stockage compatible S3 retourne une URL signée pour que le fichier puisse contourner le runtime de l’application. Le stockage local et R2 natif retournent un endpoint de streaming de même origine.

Trouver des médias

Recherche

Utilisez la zone de recherche pour trouver des fichiers par nom. La recherche correspond aux noms de fichiers partiels.

Filtrer par type

Utilisez le filtre de type pour afficher les images, documents, fichiers vidéo ou audio.

Organiser les médias dans des dossiers

Les éditeurs peuvent sélectionner Ajouter un nouveau dossier depuis la bibliothèque principale. Ouvrez un dossier en sélectionnant son nom. Sans terme de recherche, les pages de dossiers affichent uniquement les médias assignés à ce dossier. Les recherches par nom de fichier couvrent toute la bibliothèque, y compris les autres dossiers et la bibliothèque principale.

Pour déplacer un fichier local dans un dossier visible, glissez sa carte de grille ou sa ligne de liste sur le dossier. Vous pouvez aussi ouvrir Détails du média, choisir un Emplacement et sélectionner Enregistrer. Utilisez Emplacement pour remettre un fichier dans la bibliothèque principale ou le déplacer sans glisser.

Les auteurs peuvent déplacer les fichiers locaux qu’ils ont téléchargés. Les éditeurs peuvent déplacer n’importe quel fichier local. Les fichiers de fournisseurs externes ne peuvent pas être assignés à des dossiers.

Les téléchargements entrent dans la bibliothèque principale. Déplacez-les dans un dossier après le téléchargement en utilisant l’une des méthodes ci-dessus.

La suppression d’un dossier remet ses médias dans la bibliothèque principale. Les fichiers multimédias, URLs et références de contenu restent inchangés.

Utiliser les médias dans le contenu

Dans l’éditeur de texte enrichi

1. Placez votre curseur où vous voulez l’image

2. Cliquez sur le bouton image dans la barre d’outils

3. Trouvez une image dans le sélecteur ou téléchargez-en une nouvelle.

4. Sélectionnez Insérer l’image.

5. Ajoutez du texte alternatif dans les paramètres de l’image.

Comme image mise en avant

1. Ouvrez une entrée de contenu dans l’éditeur

2. Trouvez le champ Image mise en avant dans la barre latérale

3. Cliquez sur Sélectionner l’image

4. Choisissez une image dans le sélecteur ou téléchargez-en une.

5. Sélectionnez Sélectionner, puis Enregistrer.

Dans les champs personnalisés

Pour les champs configurés comme types image ou fichier, sélectionnez l’action du champ pour ouvrir le même sélecteur de médias. Les règles de type MIME du champ limitent les sources et fichiers que vous pouvez choisir.

Modifier un asset image sélectionné

Les champs d’image locaux, images de texte enrichi et images de galerie fournissent trois actions :

• Remplacer change l’image utilisée dans le champ, bloc ou position de galerie actuel.
• Modifier l’asset ouvre les Détails du média pour l’élément sélectionné de la Bibliothèque de médias. Vous pouvez mettre à jour son texte alternatif, légende, point focal ou recadrage tout en restant dans l’éditeur de contenu.
• Supprimer efface la référence de contenu actuelle. L’élément de la Bibliothèque de médias reste disponible.

Créer une copie recadrée sélectionne la nouvelle copie pour l’utilisation actuelle. Les images de texte enrichi et de galerie conservent leur texte alternatif, légende, disposition et position par utilisation. Remplacer l’original conserve la même référence multimédia et change l’image partout où cet asset est utilisé.

Les images de fournisseurs externes et les champs fichier fournissent Remplacer et Supprimer, mais pas Modifier l’asset.

Remplacer une image

Utilisez Remplacer l’image pour mettre à jour le fichier derrière un élément multimédia local existant. Les auteurs peuvent remplacer les images qu’ils ont téléchargées, et les éditeurs peuvent remplacer n’importe quelle image locale. L’action est disponible pour les images JPEG, PNG et WebP stockées sur disque local, Cloudflare R2 ou stockage compatible S3.

1. Ouvrez Médias, puis sélectionnez une image de la bibliothèque locale.
2. Restez sur Détails, puis sélectionnez Remplacer l’image.
3. Choisissez une image non vide dans le même format que le fichier existant.
4. Vérifiez l’avertissement, puis sélectionnez Remplacer l’image pour confirmer.

Le remplacement peut utiliser des dimensions différentes ou un rapport d’aspect différent de l’image existante. EmDash conserve l’ID du média, le nom de fichier, l’URL, le texte alternatif, la légende et l’emplacement, de sorte que chaque référence existante utilise le remplacement. Remplacer le fichier efface son point focal.

Remplacer l’image télécharge un autre fichier depuis votre ordinateur. Pour recadrer l’image actuelle, sélectionnez Remplacer l’original depuis l’éditeur de Recadrage.

Définir un point focal

Un point focal garde la partie importante d’une image locale visible lorsqu’une carte, galerie ou autre mise en page la recadre pour remplir une forme fixe.

1. Ouvrez Médias et sélectionnez une image de la bibliothèque locale, ou sélectionnez Modifier l’asset pour une image locale dans l’éditeur de contenu.
2. Sélectionnez Modifier l’image, puis Point focal.
3. Cliquez ou glissez le marqueur sur la partie importante de l’image. Vous pouvez aussi utiliser les touches fléchées.
4. Vérifiez les aperçus carré, paysage et portrait, puis sélectionnez Enregistrer.

Sélectionnez Réinitialiser pour supprimer un point focal personnalisé. Le point enregistré est copié lorsque vous sélectionnez l’image pour un champ de contenu ou une galerie. Les autres contenus utilisant déjà l’image conservent leur point stocké jusqu’à ce que vous sélectionniez l’image à nouveau. Lorsque vous modifiez un asset depuis un champ de contenu ou une galerie, cette utilisation actuelle est rafraîchie avec le point focal enregistré.

Recadrer une image

Le recadrage est disponible pour les images JPEG, PNG et WebP téléchargées vers EmDash. Il fonctionne avec le stockage local, Cloudflare R2 et le stockage compatible S3. Les images de fournisseurs de médias externes ne peuvent pas être recadrées dans la Bibliothèque de médias.

1. Ouvrez Médias, puis sélectionnez une image de la bibliothèque locale.
2. Sélectionnez Modifier l’image, puis Recadrer.
3. Sélectionnez Original, Forme libre ou un rapport d’aspect courant. Les rapports fixes restent verrouillés pendant le redimensionnement. Forme libre vous permet de modifier la largeur et la hauteur indépendamment.
4. Déplacez le cadre de recadrage sur l’image. Pour un rapport fixe, glissez un coin pour redimensionner. Forme libre fournit aussi quatre poignées de bord. La grille des tiers reste visible. Vous pouvez focaliser le cadre ou une poignée et utiliser les touches fléchées. Maintenez Shift pour des pas plus grands.
5. Sélectionnez l’une des actions de recadrage :
   • Créer une copie recadrée crée un élément multimédia séparé et laisse l’original inchangé. Sélectionnez la copie recadrée dans chaque entrée de contenu où vous souhaitez l’utiliser.
   • Remplacer l’original remplace l’image partout où l’élément multimédia est utilisé. Les entrées de contenu existantes conservent la même référence multimédia et ne sont pas réécrites ou republiées.

Le recadrage d’un fichier WebP produit une image WebP fixe. Si la source est animée, le résultat recadré ne conserve pas l’animation.

Afficher les médias dans les templates

Accédez aux URLs des médias depuis vos données de contenu :

---
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <img
    src={post.data.featured_image}
    alt={post.data.featured_image_alt ?? ""}
  />
)}

Images responsives

Pour les champs de médias EmDash, utilisez le composant Image de emdash/ui :

---
import { Image } from "emdash/ui";
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    image={post.data.featured_image}
    width={800}
    height={450}
    priority
  />
)}

priority est pour l’image principale above-the-fold. Il définit loading="eager" et fetchpriority="high" : loading contrôle si le chargement est différé, et fetchpriority donne au navigateur un indice de priorité pour la requête.

Quand la valeur du champ comporte une contrepartie sombre, Image rend les deux et affiche celle correspondant au schéma de couleurs du visiteur. Mode sombre couvre l’activation du slot sur un champ et la convention de classe <html> sur laquelle le composant s’appuie.

EmDash installe un endpoint d’image qui produit les variantes redimensionnées à la demande. Sur Cloudflare Workers, cet endpoint utilise le binding IMAGES. Transformation d’images couvre d’où vient le binding et ce qui se passe quand il est absent.

Supprimer des médias

1. Sélectionnez le(s) fichier(s) que vous souhaitez supprimer

2. Cliquez sur Supprimer

3. Confirmez la suppression

API des médias

Utilisez l’API REST pour télécharger, lister, mettre à jour, supprimer et organiser les médias locaux. La référence des endpoints de médias documente le téléchargement multipart direct et les flux de cible de téléchargement, les paramètres de requête, les formes de réponse, les permissions et les opérations de dossiers.

Fournisseurs de médias

En plus du stockage local, EmDash supporte des fournisseurs de médias externes pour l’hébergement spécialisé d’images et de vidéos. Les fournisseurs de médias apparaissent comme des onglets dans le sélecteur de médias, permettant aux éditeurs de choisir parmi plusieurs sources.

Fournisseurs disponibles

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      // ... configuration base de données, stockage
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          // Optionnel : domaine de livraison personnalisé
          deliveryDomain: "images.example.com",
        }),
      ],
    }),
  ],
});

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      // ... configuration base de données, stockage
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          // Optionnel : paramètres du lecteur
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

Utiliser plusieurs fournisseurs

Vous pouvez configurer plusieurs fournisseurs. Chacun apparaît comme un onglet dans le sélecteur de médias :

import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import { cloudflareImages, cloudflareStream } from "@emdash-cms/cloudflare";

export default defineConfig({
  integrations: [
    emdash({
      database: d1({ binding: "DB" }),
      storage: r2({ binding: "MEDIA" }),
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
        }),
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
        }),
      ],
    }),
  ],
});

La bibliothèque de médias locale (onglet « Bibliothèque ») est toujours disponible aux côtés de tous les fournisseurs configurés.

Rendre les médias de fournisseurs

Utilisez le composant Image pour rendre les médias :

---
import { Image } from "emdash/ui";
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    image={post.data.featured_image}
    width={800}
    height={450}
  />
)}

Le composant automatiquement :

• Détecte le fournisseur à partir de la valeur stockée
• Rend un élément <img> optimisé
• Applique les optimisations spécifiques au fournisseur (ex : transformations Cloudflare Images)

Valeurs de fichier et métadonnées actuelles

Un champ fichier stocke une référence et un instantané de métadonnées. Les champs en cache comme url, filename, mimeType et size sont optionnels car les valeurs persistées peuvent les omettre :

interface FileValue {
  id: string;
  url?: string;        // URL en cache legacy
  src?: string;        // URL directe d'un fournisseur externe
  filename?: string;  // Nom de fichier original en cache
  mimeType?: string;  // Type MIME en cache
  size?: number;       // Taille en cache, quand disponible
  provider?: string;   // Par défaut "local"
  meta?: Record<string, unknown>;
}

getEmDashEntry() et getEmDashCollection() retournent cette valeur stockée sans requête média supplémentaire. Pour les métadonnées actuelles, utilisez la méthode get() du fournisseur configuré explicitement. Utilisez getEmbed() pour l’URL de rendu spécifique au fournisseur :

---
const file = post.data.attachment;
const provider = file
  ? Astro.locals.emdash?.getMediaProvider(file.provider ?? "local")
  : undefined;
const current = file ? await provider?.get?.(file.id) : null;
const embed = file && provider ? await provider.getEmbed(file) : null;
---

Les clients HTTP authentifiés peuvent effectuer la même recherche explicite via GET /_emdash/api/media/:id pour les médias locaux ou GET /_emdash/api/media/providers/:providerId/:itemId pour un autre fournisseur.

Pour une URL de fichier local, utilisez le meta.storageKey stocké avec le helper d’URL publique. Cela respecte un domaine public R2 ou S3 configuré sans interroger la table des médias :

---
const storageKey =
  typeof file?.meta?.storageKey === "string" ? file.meta.storageKey : undefined;
const url = storageKey
  ? Astro.locals.emdash?.getPublicMediaUrl?.(storageKey)
  : file?.src ?? file?.url;
---

Les recherches de fournisseurs peuvent effectuer du travail réseau ou base de données. Évitez une recherche par fichier sur les pages de collection déconnectées ; utilisez l’instantané stocké et les composants de rendu sauf si la requête nécessite des métadonnées fraîches.

Type MediaValue

Les champs de médias stockent un objet MediaValue contenant des informations sur le fournisseur :

interface MediaValue {
  provider?: string;    // ID du fournisseur, par défaut "local"
  id: string;           // ID spécifique au fournisseur
  src?: string;         // URL directe (pour les médias locaux ou valeurs de chaîne simple)
  previewUrl?: string;  // URL de prévisualisation pour l'affichage admin (fournisseurs externes)
  filename?: string;    // Nom de fichier original
  mimeType?: string;    // Type MIME
  width?: number;       // Largeur image/vidéo
  height?: number;      // Hauteur image/vidéo
  focalX?: number;      // Position focale horizontale de 0 à 1
  focalY?: number;      // Position focale verticale de 0 à 1
  alt?: string;         // Texte alternatif
  meta?: Record<string, unknown>; // Métadonnées spécifiques au fournisseur
}

Cela permet à EmDash de rendre les médias correctement quel que soit l’endroit où ils sont hébergés.

Prochaines étapes

• Travailler avec le contenu - Utiliser les médias dans votre contenu
• Créer un blog - Ajouter des images aux articles de blog
• Interroger le contenu - Afficher les médias dans les templates