Biblioteca de mídia

A Biblioteca de mídia armazena imagens, documentos, vídeo e áudio reutilizáveis. Os editores podem enviar arquivos uma vez, selecioná-los a partir de 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 pelos arquivos ou alterne entre as visualizações em grade e lista.

Se o site tiver provedores de mídia externos, cada provedor aparece como outra fonte. Os recursos do provedor variam: uma fonte pode oferecer suporte a navegação e seleção, mas não a pastas, edição local de imagem ou exclusão.

Enviar arquivos

Enviar pela biblioteca

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

Enviar ao editar 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 passa a fazer parte da seleção atual; uploads com falha permanecem visíveis para que você possa tentar de novo 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 imagem ou arquivo único, 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; e
• documentos PDF.

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 de outro formato. O EmDash identifica cada arquivo pelo tipo de mídia, um rótulo como image/png ou application/pdf, e verifica novamente a lista do campo ao salvar o conteúdo. 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 relatará 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 com uma pasta aberta; navegar por uma pasta sem busca mostra apenas os arquivos atribuídos a essa pasta.

Os 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 local para remover um arquivo da 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 à biblioteca principal. Não exclui os arquivos, não altera suas URLs e não remove suas referências de conteúdo.

Selecionar mídia para o conteúdo

Imagens Portable Text

Coloque o cursor em um campo Portable Text, abra o menu de blocos e selecione Image. Escolha ou envie uma imagem e selecione Insert image. Depois selecione o bloco de imagem 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 de um 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 a postagem. Salvar a entrada salva essa referência no rascunho; publicar a torna disponível para consultas de conteúdo públicas.

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 escolhe a nova cópia para o uso atual. Imagens Portable Text e de galeria mantêm o texto alternativo, a legenda, o layout e a 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 envia novos bytes por trás de um item existente da Biblioteca de mídia. Use-o quando todos os lugares 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, o nome do arquivo, a URL, o texto alternativo, a legenda e a pasta. Assim, as referências de conteúdo existentes continuam funcionando 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 em vez disso quando apenas um campo ou bloco de imagem deve mudar.

Definir um ponto focal

Um ponto focal marca a parte de uma 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. Ao escolher 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 de novo. Abrir Edit asset a partir 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 as outras proporções. Uma cópia recortada permanece na mesma pasta da fonte e recebe um nome de arquivo exclusivo.

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 as entradas de conteúdo e as configurações do site que fazem referência a ele. Cada resultado de conteúdo 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. Um resultado Site Settings nomeia as configurações que selecionam o arquivo: Logo, Favicon ou Default Social Image.

Used in verifica estas referências:

• campos de imagem e arquivo
• campos de imagem dentro de repetidores
• campos de imagem, arquivo e Portable Text dentro de campos blocks
• blocos de imagem e galeria em campos Portable Text
• o logo do site, o favicon e a imagem social padrão

Quando a cobertura de uso está completa e o arquivo não tem nenhuma dessas referências, a lista mostra No tracked references found. Até a cobertura estar completa, uma lista vazia mostra No usage to show yet.

O rastreamento de uso de mídia deve estar ativo antes que os resultados de conteúdo possam estar completos. As configurações do site são listadas independentemente de o rastreamento estar ativo. Um administrador ativa o rastreamento uma vez para o site:

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

Se a visualização Used in informar que a indexação está em execução, desatualizada, parcial ou com falha, trate seus resultados como incompletos. Um administrador pode voltar a Media usage tracking para o status atual e a 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 baseadas em provedor 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. Ele solicita carregamento eager e dá ao navegador uma dica de alta prioridade de busca. Outras imagens devem manter o lazy-loading padrão do componente.

Se o campo tiver uma contraparte de modo escuro, Image renderiza ambas as fontes e seleciona uma com base no esquema de cores do visitante. Veja Imagens em modo escuro para a configuração do campo e do 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 exigir os metadados mais recentes do provedor, solicite esse item explicitamente e evite uma busca por 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 pelo adaptador de armazenamento configurado do site. Sites Node.js podem usar disco local ou armazenamento compatível com S3; sites Cloudflare costumam usar um binding R2. O adaptador decide onde os bytes são armazenados, enquanto a Biblioteca de mídia mantém o mesmo fluxo de criação. 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 baseados no provedor. Itens do provedor permanecem gerenciados por esse serviço, então pastas locais, pontos focais, recorte e substituição ficam indisponí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 do provedor somente quando essa fonte expõe a 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 da CLI. Continue com Trabalhar com conteúdo para publicar entradas que usam a mídia selecionada.