Biblioteca de Mídia

A Biblioteca de Mídia armazena imagens, documentos, vídeos e áudios reutilizáveis. Os editores podem fazer upload de arquivos uma vez, selecioná-los em campos de conteúdo e Portable Text, e ver quais entradas de conteúdo fazem referência a um item de mídia local.

Abrir a Biblioteca de Mídia

Selecione Media na barra lateral de administração. A biblioteca Principal contém pastas e arquivos que não foram colocados em uma pasta. Selecione uma pasta para navegar em seus arquivos ou alterne entre visualização em grade e lista.

Se o site tiver provedores de mídia externos, cada provedor aparece como outra fonte. As capacidades do provedor variam: uma fonte pode suportar navegação e seleção, mas não pastas, edição local de imagens ou exclusão.

Fazer upload de arquivos

Upload a partir da biblioteca

Os uploads começam assim que os arquivos são adicionados. Novos arquivos locais entram na biblioteca Principal, mesmo quando outra pasta estava aberta antes do upload.

Upload durante a edição de conteúdo

Campos de imagem, arquivo, galeria e imagem Portable Text usam um seletor de mídia. Abra o campo, selecione Upload files e escolha ou solte arquivos. Um upload concluído torna-se parte da seleção atual; uploads com falha permanecem visíveis para que você possa tentar novamente ou removê-los.

Para uma galeria, revise Selected media e use os controles de movimentação para definir a ordem antes de selecionar Add images. Para uma única imagem ou arquivo, selecione Select ou Insert image após o upload terminar.

Arquivos aceitos e limite de tamanho

A Biblioteca de Mídia local aceita estes grupos de arquivos por padrão:

• Imagens PNG, JPEG, GIF, WebP e AVIF;
• formatos de vídeo comuns como MP4, WebM e vídeo QuickTime;
• formatos de áudio comuns como MP3, WAV e áudio Ogg;
• documentos PDF.

O SVG é excluído da lista de upload padrão porque arquivos SVG podem conter conteúdo ativo. Um campo de imagem ou arquivo pode definir sua própria lista de tipos de arquivo aceitos quando o modelo de conteúdo precisa de uma seleção mais restrita ou outro formato. O EmDash identifica cada arquivo pelo seu tipo de mídia, um rótulo como image/png ou application/pdf, e verifica a lista do campo novamente quando o conteúdo é salvo. Alterar o seletor de arquivos do navegador não contorna essa verificação do servidor.

O máximo padrão é 50 MB por arquivo. Desenvolvedores do site podem alterá-lo com maxUploadSize. Um provedor pode impor um limite adicional de formato ou tamanho e reportará essa falha na linha de upload.

Encontrar e organizar arquivos

A busca corresponde a nomes de arquivo parciais. O filtro de tipo limita os resultados a imagens, documentos, vídeo ou áudio. Uma busca por nome de arquivo cobre toda a biblioteca local, mesmo quando uma pasta está aberta; navegar em uma pasta sem busca mostra apenas os arquivos atribuídos a essa pasta.

Editores podem selecionar Add new folder na biblioteca Principal. Mova um arquivo local arrastando seu cartão ou linha para uma pasta visível, ou abra o arquivo, altere Location e selecione Save. Use Main library como localização para remover um arquivo de sua pasta atual.

Autores podem mover arquivos locais que enviaram. Editores podem mover qualquer arquivo local. Itens de provedores externos não podem ser atribuídos a pastas da Biblioteca de Mídia.

Excluir uma pasta move seus arquivos de volta para a biblioteca Principal. Isso não exclui os arquivos, altera suas URLs ou remove suas referências de conteúdo.

Selecionar mídia para conteúdo

Imagens Portable Text

Posicione o cursor em um campo Portable Text, abra o menu de blocos e selecione Image. Escolha ou faça upload de uma imagem e selecione Insert image. Selecione o bloco de imagem depois para adicionar texto alternativo, legenda, dimensões de exibição e alinhamento.

Campos de imagem e arquivo

Selecione a ação do campo, como Select image ou Select file, depois escolha um item e confirme a seleção. As regras de tipo MIME do campo limitam quais itens da biblioteca e fontes de mídia aparecem.

O campo featured_image do template de blog armazena o valor de mídia selecionado com o post. Salvar a entrada salva essa referência no rascunho; publicar a torna disponível para consultas de conteúdo público.

Campos de galeria

Selecione uma ou mais imagens, organize-as em Selected media e confirme. Uma galeria mantém sua própria ordem e texto alternativo e legenda por imagem, mesmo quando várias posições fazem referência a itens da Biblioteca de Mídia.

Editar uma imagem usada no conteúdo

Uma imagem local selecionada oferece ações com escopos diferentes:

• Replace escolhe um item diferente da Biblioteca de Mídia para este campo, bloco ou posição da galeria. Outras entradas que usam o item original não mudam.
• Edit asset abre o item subjacente da Biblioteca de Mídia. Alterações de metadados e alterações destrutivas na imagem podem afetar outros usos desse item.
• Remove limpa esta referência de conteúdo. O item da Biblioteca de Mídia permanece disponível.

Quando Edit asset cria uma cópia recortada, o seletor seleciona a nova cópia para o uso atual. Imagens Portable Text e de galeria mantêm o texto alternativo, legenda, layout e posição desse uso. Quando Edit asset substitui o original, o ID de mídia permanece o mesmo, então cada uso desse item recebe a imagem alterada.

Imagens de provedores externos e campos de arquivo oferecem Replace e Remove, mas não abrem o editor de ativos local.

Substituir uma imagem local

Replace image faz upload de novos bytes por trás de um item existente da Biblioteca de Mídia. Use quando todos os locais que fazem referência ao item devem mostrar uma nova versão da imagem.

A ação está disponível para itens JPEG, PNG e WebP prontos. Autores podem substituir imagens que enviaram; editores podem substituir qualquer imagem local.

O EmDash mantém o ID de mídia, nome do arquivo, URL, texto alternativo, legenda e pasta. As referências de conteúdo existentes, portanto, continuam a funcionar e mostram a substituição. A substituição limpa o ponto focal salvo porque suas coordenadas podem não descrever a nova imagem.

Use Replace no editor de conteúdo quando apenas um campo ou bloco de imagem deve mudar.

Definir um ponto focal

Um ponto focal marca a parte da imagem que deve permanecer visível quando um layout recorta a imagem para preencher um quadrado, paisagem, retrato ou outra forma fixa.

Selecione Reset para remover o ponto personalizado. Quando você escolhe uma imagem para um campo ou galeria, o EmDash copia o ponto focal atual do ativo para esse valor de conteúdo. Conteúdo que já usa a imagem mantém seu ponto armazenado até você selecionar a imagem novamente. Abrir Edit asset de um campo de conteúdo atualiza esse uso atual com o ponto que você salvar.

Recortar uma imagem local

O recorte está disponível para imagens JPEG, PNG e WebP prontas armazenadas pelo EmDash. Imagens de provedores externos não podem ser recortadas no editor de ativos local.

Replace original está disponível apenas com a proporção Original. Use Create cropped copy para Freeform e outras proporções. Uma cópia recortada permanece na mesma pasta que sua fonte e recebe um nome de arquivo único.

Recortar um WebP animado cria um WebP estático. O resultado recortado não retém a animação.

Ver onde um arquivo é usado

Abra um arquivo local e selecione Used in para listar entradas de conteúdo que fazem referência a ele. Cada resultado nomeia a coleção e os campos que contêm a referência e pode abrir a entrada para edição. Entradas na lixeira são identificadas na lista.

O rastreamento de uso de mídia deve estar ativo antes que esta lista possa estar completa. Um administrador o ativa uma vez para o site:

Uma vez ativado, o rastreamento de uso de mídia não pode ser desativado. Novas alterações de conteúdo são rastreadas após a captura se tornar ativa; o escaneamento em segundo plano adiciona referências de entradas que já existiam.

Se a visualização Used in reportar que a indexação está em execução, desatualizada, parcial ou falhou, trate seus resultados como incompletos. Um administrador pode retornar a Media usage tracking para o status atual e orientação de recuperação.

Renderizar uma imagem em um template

Campos de imagem retornam um valor de mídia em vez de uma URL simples. Renderize esse valor com Image de emdash/ui para que imagens locais e de provedores usem a URL, dimensões, ponto focal, variantes responsivas e placeholder de baixa qualidade apropriados:

---
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.redirect("/404");
---

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

Use priority apenas para a imagem principal visível no topo da página. Ela solicita carregamento imediato e dá ao navegador uma dica de alta prioridade de busca. Outras imagens devem manter o padrão de carregamento lazy do componente.

Se o campo tiver uma contrapartida para modo escuro, Image renderiza ambas as fontes e seleciona uma a partir do esquema de cores do visitante. Veja Imagens em modo escuro para a configuração do campo e template.

O template recebe os metadados de mídia armazenados com a referência de conteúdo sem outra consulta à Biblioteca de Mídia. Se uma integração personalizada precisar dos metadados mais recentes do provedor, solicite esse item explicitamente e evite uma consulta ao provedor por imagem em uma página de coleção. A referência de tipos de campo descreve valores de arquivo e imagem armazenados.

Configurar armazenamento e provedores

A biblioteca local armazena arquivos através do adaptador de armazenamento configurado do site. Sites Node.js podem usar disco local ou armazenamento compatível com S3; sites Cloudflare comumente usam um binding R2. O adaptador decide onde os bytes são armazenados, enquanto a Biblioteca de Mídia mantém o mesmo fluxo de trabalho de autoria. Veja Armazenamento de mídia para configuração e requisitos de persistência em produção.

Cloudflare Images e Cloudflare Stream podem ser registrados como provedores de mídia externos. Eles aparecem como fontes no seletor, e Image entende valores de imagem de provedores. Itens de provedores permanecem gerenciados por esse serviço, então pastas locais, pontos focais, recorte e substituição não estão disponíveis para esses itens no editor de ativos do EmDash.

Excluir mídia com segurança

Abra um arquivo na Biblioteca de Mídia, selecione Delete e confirme a exclusão permanente. Autores podem excluir arquivos locais que enviaram; editores podem excluir qualquer arquivo local. Um item de provedor é excluído de seu provedor apenas quando essa fonte expõe exclusão e o usuário atual tem permissão.

Para uploads automatizados e gerenciamento de mídia, veja a referência de endpoints de mídia ou os comandos de mídia CLI. Continue com Trabalhando com Conteúdo para publicar entradas que usam a mídia selecionada.