Médiathèque

La médiathèque stocke des images, documents, vidéos et fichiers audio réutilisables. Les éditeurs téléversent un fichier une seule fois, le sélectionnent dans des champs de contenu et dans Portable Text, et voient quelles entrées de contenu référencent un élément multimédia local.

Ouvrir la médiathèque

Sélectionnez Media dans la barre latérale de l’administration. La Main library contient des dossiers ainsi que les fichiers qui ne sont pas encore dans un dossier. Sélectionnez un dossier pour parcourir ses fichiers, et basculez entre la vue en grille et la vue en liste si nécessaire.

Si votre site dispose de fournisseurs de médias externes, chaque fournisseur apparaît comme une source supplémentaire. Les capacités des fournisseurs varient : une source peut prendre en charge la navigation et la sélection, mais pas les dossiers, la modification locale des images ni la suppression.

Téléverser des fichiers

Téléverser depuis la médiathèque

Les téléversements démarrent dès que vous ajoutez des fichiers. Les nouveaux fichiers locaux vont dans la Main library, même si un autre dossier était ouvert avant le téléversement.

Téléverser pendant la modification d’un contenu

Les champs image, fichier, galerie et image Portable Text utilisent le sélecteur de médias. Ouvrez le champ, sélectionnez Upload files, puis choisissez ou déposez des fichiers. Les téléversements terminés font partie de la sélection en cours ; les téléversements en échec restent visibles afin que vous puissiez les réessayer ou les retirer.

Pour une galerie, examinez Selected media et définissez l’ordre avec les commandes de déplacement avant de sélectionner Add images. Pour une image ou un fichier unique, sélectionnez Select ou Insert image une fois le téléversement terminé.

Fichiers acceptés et limites de taille

La médiathèque locale accepte par défaut ces groupes de fichiers :

• images PNG, JPEG, GIF, WebP et AVIF ;
• formats vidéo courants, tels que MP4, WebM et vidéo QuickTime ;
• formats audio courants, tels que MP3, WAV et audio Ogg ; et
• documents PDF.

Le format SVG est absent de la liste de téléversement par défaut, car les fichiers SVG peuvent contenir du contenu actif. Un champ image ou fichier peut définir sa propre liste de types de fichiers acceptables lorsque votre modèle de contenu nécessite une sélection plus restreinte ou d’autres formats. EmDash identifie chaque fichier par son type de média, une étiquette telle que image/png ou application/pdf, et revérifie la liste du champ lors de l’enregistrement du contenu. Modifier le sélecteur de fichiers du navigateur ne contourne pas cette vérification côté serveur.

La taille maximale par défaut est de 50 Mo par fichier. Les développeurs du site peuvent la modifier avec maxUploadSize. Les fournisseurs peuvent imposer des restrictions supplémentaires de format ou de taille, et signalent cet échec dans la ligne de téléversement.

Trouver et organiser les fichiers

La recherche correspond à des portions de nom de fichier. Le filtre de type limite les résultats aux images, documents, vidéos ou fichiers audio. La recherche par nom de fichier porte sur l’ensemble de la médiathèque locale même si un dossier est ouvert ; en parcourant un dossier sans rechercher, seuls les fichiers attribués à ce dossier s’affichent.

Les éditeurs peuvent sélectionner Add new folder dans la Main library. Pour déplacer un fichier local, faites glisser sa carte ou sa ligne vers un dossier visible, ou ouvrez le fichier, modifiez Location, puis sélectionnez Save. Utilisez Main library comme emplacement pour sortir un fichier de son dossier actuel.

Les auteurs peuvent déplacer les fichiers locaux qu’ils ont eux-mêmes téléversés. Les éditeurs peuvent déplacer n’importe quel fichier local. Les éléments d’un fournisseur externe ne peuvent pas être attribués à des dossiers de la médiathèque.

La suppression d’un dossier renvoie ses fichiers dans la Main library. Cela ne supprime aucun fichier, ne modifie pas leurs URL et ne retire pas leurs références de contenu.

Sélectionner des médias pour un contenu

Images Portable Text

Placez le curseur dans un champ Portable Text, ouvrez le menu des blocs, puis sélectionnez Image. Choisissez ou téléversez une image, puis sélectionnez Insert image. Sélectionnez ensuite le bloc d’image pour ajouter un texte alternatif, une légende, une taille d’affichage et un alignement.

Champs image et fichier

Sélectionnez l’action du champ, par exemple Select image ou Select file, choisissez un élément et confirmez la sélection. Les règles de type MIME du champ limitent les éléments de la médiathèque et les sources de médias affichés.

Le champ featured_image du modèle de blog enregistre la valeur multimédia sélectionnée avec l’article. L’enregistrement de l’entrée stocke cette référence dans le brouillon ; la publication la rend disponible pour les requêtes de contenu publiques.

Champs galerie

Sélectionnez une ou plusieurs images, organisez-les sous Selected media, puis confirmez. La galerie conserve son propre ordre ainsi que le texte alternatif et la légende de chaque image, même si plusieurs emplacements référencent le même élément de la médiathèque.

Modifier une image utilisée dans un contenu

Une image locale sélectionnée offre des actions à portée différente :

• Replace choisit un autre élément de la médiathèque pour ce champ, ce bloc ou cet emplacement de galerie. Les autres entrées qui utilisent l’élément d’origine ne changent pas.
• Edit asset ouvre l’élément de la médiathèque sous-jacent. Les modifications de métadonnées et les modifications destructives de l’image peuvent affecter les autres utilisations de cet élément.
• Remove supprime cette référence de contenu. L’élément de la médiathèque reste disponible.

Lorsque Edit asset crée une copie recadrée, le sélecteur choisit la nouvelle copie pour l’utilisation en cours. Les images Portable Text et de galerie conservent le texte alternatif, la légende, la mise en page et la position de cette utilisation. Lorsque Edit asset remplace l’original, l’ID du média reste le même, de sorte que chaque utilisation de cet élément reçoit l’image modifiée.

Les champs image et fichier d’un fournisseur externe proposent Replace et Remove, mais n’ouvrent pas l’éditeur de ressources local.

Remplacer une image locale

Replace image téléverse de nouveaux octets derrière un élément existant de la médiathèque. Utilisez-le lorsque tous les emplacements qui référencent cet élément doivent afficher la nouvelle version de l’image.

L’action est disponible pour les éléments JPEG, PNG et WebP prêts. Les auteurs peuvent remplacer les images qu’ils ont eux-mêmes téléversées ; les éditeurs peuvent remplacer n’importe quelle image locale.

EmDash conserve l’ID du média, le nom de fichier, l’URL, le texte alternatif, la légende et le dossier. Les références de contenu existantes continuent donc de fonctionner et affichent l’image remplacée. Le remplacement efface le point focal enregistré, car ses coordonnées peuvent ne plus s’appliquer à la nouvelle image.

Si un seul champ ou bloc d’image doit changer, utilisez plutôt Replace dans l’éditeur de contenu.

Définir un point focal

Un point focal marque la partie d’une image qui doit rester visible lorsqu’une mise en page recadre l’image dans une forme carrée, paysage, portrait ou une autre forme fixe.

Sélectionnez Reset pour retirer le point personnalisé. Lorsque vous sélectionnez une image pour un champ ou une galerie, EmDash copie le point focal actuel de la ressource dans cette valeur de contenu. Les contenus qui utilisent déjà l’image conservent leur point enregistré jusqu’à ce que vous sélectionniez de nouveau l’image. Lorsque vous ouvrez Edit asset depuis un champ de contenu, le point que vous enregistrez met à jour cette utilisation en cours.

Recadrer une image locale

Le recadrage est disponible pour les images JPEG, PNG et WebP prêtes et stockées par EmDash. Les images d’un fournisseur externe ne peuvent pas être recadrées dans l’éditeur de ressources local.

Replace original n’est disponible qu’avec le rapport d’aspect Original. Pour Freeform et les autres rapports, utilisez Create cropped copy. Les copies recadrées sont placées dans le même dossier que leur élément source et reçoivent un nom de fichier unique.

Le recadrage d’un WebP animé produit un WebP statique. L’animation n’est pas conservée dans le résultat recadré.

Voir où un fichier est utilisé

Ouvrez un fichier local et sélectionnez Used in pour lister les entrées de contenu et les paramètres du site qui le référencent. Chaque résultat de contenu indique la collection et le champ qui contiennent la référence, et ouvre l’entrée pour la modifier. Les entrées placées dans la corbeille sont identifiées dans la liste. Un résultat Site Settings indique le paramètre qui sélectionne le fichier : Logo, Favicon ou Default Social Image.

Used in vérifie ces références :

• les champs image et fichier
• les champs image à l’intérieur de répéteurs
• les champs image, fichier et Portable Text à l’intérieur des champs blocks
• les blocs d’image, de galerie et de vidéo dans les champs Portable Text
• le logo du site, le favicon et l’image sociale par défaut

Lorsque la couverture de l’utilisation est complète et que le fichier ne possède aucune de ces références, la liste affiche No tracked references found. Tant que la couverture n’est pas complète, une liste vide affiche No usage to show yet.

Le suivi de l’utilisation des médias doit être activé pour que les résultats de contenu puissent être complets. Les paramètres du site sont listés que le suivi soit activé ou non. Un administrateur n’active le suivi qu’une seule fois pour le site :

Une fois activé, le suivi de l’utilisation des médias ne peut pas être désactivé. Les nouvelles modifications de contenu sont suivies une fois la capture active ; l’analyse en arrière-plan ajoute les références des entrées qui existaient déjà.

Si la vue Used in signale que l’indexation est en cours, obsolète, partielle ou en échec, considérez ses résultats comme incomplets. Les administrateurs peuvent retourner à Media usage tracking pour voir l’état actuel et les conseils de récupération.

Afficher des images dans les modèles

Un champ image renvoie une valeur multimédia, et non une simple URL. Affichez cette valeur avec Image de emdash/ui afin que les images locales et celles fournies par un fournisseur utilisent l’URL, les dimensions, le point focal, les variantes adaptatives et l’espace réservé basse qualité appropriés :

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

const { entry: post, error } = await getEmDashEntry("posts", Astro.params.slug);
if (error) return new Response("Unable to load post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

{post.data.featured_image && (
  <Image image={post.data.featured_image} width={1200} height={675} priority />
)}

N’utilisez priority que pour l’image principale visible en haut de la page. Il demande un chargement immédiat et donne au navigateur une indication de priorité de récupération élevée. Les autres images doivent conserver le chargement différé, qui est la valeur par défaut du composant.

Si le champ a une image pour le mode sombre, Image affiche les deux sources et en choisit une selon le jeu de couleurs du visiteur. Consultez Variantes d’image sombres pour la configuration du champ et du modèle.

Les modèles reçoivent les métadonnées du média stockées avec la référence de contenu sans interroger de nouveau la médiathèque. Si une intégration personnalisée a besoin des métadonnées les plus récentes du fournisseur, demandez explicitement cet élément et évitez d’interroger le fournisseur pour chaque image dans les pages de collection. La référence des types de champs décrit les valeurs de fichier et d’image stockées.

Afficher un fichier dans un modèle

La valeur d’un champ fichier de la médiathèque ne contient pas d’URL toute prête. Transmettez son meta.storageKey à Astro.locals.emdash.getPublicMediaUrl(), qui renvoie l’URL publique et tient compte d’un domaine public R2 ou S3 configuré, sans interroger la table des médias. Les anciennes valeurs sans clé de stockage conservent leur URL dans url, et les fichiers ajoutés par URL (stockés avec provider: "external") la conservent dans src.

Pour un fichier provenant d’un fournisseur de médias enregistré, comme Cloudflare Stream, src contient une image d’aperçu plutôt que le fichier lui-même ; cette approche ne s’applique donc pas.

La page suivante affiche une vidéo stockée dans un champ fichier video :

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

const { entry, error } = await getEmDashEntry("videos", Astro.params.slug);
if (error) return new Response("Unable to load video", { status: 500 });
if (!entry) return Astro.rewrite("/404");

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

{url && <video src={url} controls preload="metadata" />}

La même URL convient pour un lien de téléchargement ou tout autre élément ayant besoin de l’adresse du fichier. Le nom de fichier, le type MIME et la taille de la valeur sont ceux enregistrés lors de la sélection du fichier.

Configurer le stockage et les fournisseurs

La médiathèque locale stocke les fichiers via l’adaptateur de stockage configuré pour le site. Les sites Node.js peuvent utiliser le disque local ou un stockage compatible S3 ; les sites Cloudflare utilisent généralement une liaison R2. L’adaptateur décide où résident les octets, et la médiathèque conserve le même flux de travail de création. Consultez Choisir le stockage des médias pour la configuration et les exigences de persistance en production.

Cloudflare Images et Cloudflare Stream peuvent être enregistrés comme fournisseurs de médias externes. Ils apparaissent comme des sources dans le sélecteur, et Image comprend les valeurs d’image fournies par un fournisseur. Les éléments du fournisseur restent gérés par ce service ; les dossiers locaux, les points focaux, le recadrage et le remplacement ne sont donc pas disponibles pour ces éléments dans l’éditeur de ressources d’EmDash.

Supprimer des médias en toute sécurité

Ouvrez le fichier dans la médiathèque, sélectionnez Delete, puis confirmez la suppression définitive. Les auteurs peuvent supprimer les fichiers locaux qu’ils ont eux-mêmes téléversés ; les éditeurs peuvent supprimer n’importe quel fichier local. Les éléments d’un fournisseur ne sont supprimés chez le fournisseur que lorsque la source expose la suppression et que l’utilisateur actuel y est autorisé.

Pour l’automatisation des téléversements et la gestion des médias, consultez la référence des points de terminaison médias ou les commandes média de la CLI. Poursuivez avec Travailler avec le contenu pour publier des entrées qui utilisent les médias sélectionnés.