Biblioteca de mídia

A biblioteca de mídia armazena imagens, documentos, vídeos e áudios reutilizáveis. Os editores enviam um arquivo uma única vez, selecionam-no em campos de conteúdo e no Portable Text, e veem quais entradas de conteúdo referenciam um item de mídia local.

Abrir a biblioteca de mídia

Selecione Media na barra lateral do administrador. A Main library contém pastas e os arquivos que ainda não estão em nenhuma pasta. Selecione uma pasta para navegar pelos arquivos dela e alterne entre a visualização em grade e a visualização em lista quando precisar.

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

Enviar arquivos

Enviar a partir da biblioteca

Os envios começam assim que você adiciona os arquivos. Os novos arquivos locais vão para a Main library, mesmo que outra pasta estivesse aberta antes do envio.

Enviar durante a edição de conteúdo

Os campos de imagem, arquivo, galeria e imagem do Portable Text usam o seletor de mídia. Abra o campo, selecione Upload files e escolha ou solte os arquivos. Os envios concluídos passam a fazer parte da seleção atual; os envios com falha permanecem visíveis para que você possa tentar de novo ou removê-los.

Em uma galeria, revise Selected media e defina a ordem com os controles de movimentação antes de selecionar Add images. Em uma única imagem ou arquivo, selecione Select ou Insert image quando o envio terminar.

Arquivos aceitos e limites de tamanho

A biblioteca de mídia local aceita por padrão estes grupos de arquivos:

• 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.

O SVG fica fora da lista de envio padrão porque arquivos SVG podem conter conteúdo ativo. Um campo de imagem ou de arquivo pode definir a própria lista de tipos de arquivo aceitáveis quando o seu modelo de conteúdo precisar de uma seleção mais restrita ou de outros formatos. O EmDash identifica cada arquivo pelo tipo de mídia, um rótulo como image/png ou application/pdf, e confere a lista do campo novamente quando o conteúdo é salvo. Alterar o seletor de arquivos do navegador não contorna essa verificação no lado do servidor.

O máximo padrão é de 50 MB por arquivo. Os desenvolvedores do site podem alterá-lo com maxUploadSize. Os provedores podem impor restrições adicionais de formato ou tamanho e informam essa falha na linha de envio.

Encontrar e organizar arquivos

A pesquisa encontra partes do nome do arquivo. O filtro de tipo limita os resultados a imagens, documentos, vídeos ou áudios. A pesquisa por nome de arquivo abrange toda a biblioteca local mesmo quando uma pasta está aberta; ao navegar por uma pasta sem pesquisar, apenas os arquivos atribuídos a essa pasta são exibidos.

Os editores podem selecionar Add new folder na Main library. Para mover um arquivo local, arraste o cartão ou a linha dele para uma pasta visível, ou abra o arquivo, altere Location e selecione Save. Use Main library como local para tirar um arquivo da pasta atual.

Os autores podem mover os arquivos locais que eles mesmos enviaram. Os 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 devolve os arquivos dela para a Main library. Isso não exclui arquivos, não altera as URLs deles e não remove as referências de conteúdo.

Selecionar mídia para o conteúdo

Imagens do Portable Text

Posicione o cursor em um campo do Portable Text, abra o menu de blocos e selecione Image. Escolha ou envie uma imagem e depois selecione Insert image. Em seguida, selecione o bloco de imagem para adicionar texto alternativo, legenda, tamanho de exibição e alinhamento.

Campos de imagem e de arquivo

Selecione a ação do campo, por exemplo Select image ou Select file, escolha um item e confirme a seleção. As regras de tipo MIME do campo limitam quais itens da biblioteca e quais origens de mídia são exibidos.

O campo featured_image do template de blog salva o valor de mídia selecionado junto com a publicação. Ao salvar a entrada, essa referência é armazenada no rascunho; a publicação a torna disponível para as consultas públicas de conteúdo.

Campos de galeria

Selecione uma ou mais imagens, organize-as em Selected media e confirme. A galeria mantém a própria ordem e o texto alternativo e a legenda de cada imagem, mesmo quando várias posições referenciam o mesmo item da biblioteca de mídia.

Editar uma imagem usada no conteúdo

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

• Replace escolhe outro item da biblioteca de mídia para este campo, bloco ou posição da galeria. As 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 continua disponível.

Quando Edit asset cria uma cópia recortada, o seletor escolhe a nova cópia para o uso atual. As imagens do Portable Text e de galerias mantêm o texto alternativo, a legenda, o layout e a posição desse uso. Quando Edit asset substitui o original, o ID da mídia permanece o mesmo, de modo que todo uso desse item recebe a imagem alterada.

Os campos de imagem e de arquivo de provedores externos oferecem Replace e Remove, mas não abrem o editor local de recursos.

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 referenciam esse item devam mostrar a nova versão da imagem.

A ação está disponível para itens JPEG, PNG e WebP que estejam prontos. Os autores podem substituir as imagens que eles mesmos enviaram; os editores podem substituir qualquer imagem local.

O EmDash mantém o ID da 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 imagem substituída. A substituição limpa o ponto focal salvo, porque as coordenadas dele podem não se aplicar à nova imagem.

Se apenas um campo ou bloco de imagem precisar mudar, use Replace no editor de conteúdo.

Definir um ponto focal

Um ponto focal marca a parte de uma imagem que deve continuar visível quando um layout recorta a imagem em um formato quadrado, paisagem, retrato ou outro formato fixo.

Selecione Reset para remover o ponto personalizado. Quando você seleciona uma imagem para um campo ou galeria, o EmDash copia o ponto focal atual do recurso para esse valor de conteúdo. O conteúdo que já usa a imagem mantém o ponto salvo até que você selecione a imagem novamente. Quando você abre Edit asset a partir de um campo de conteúdo, o ponto que você salva atualiza esse uso atual.

Recortar uma imagem local

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

Replace original só está disponível com a proporção Original. Para Freeform e outras proporções, use Create cropped copy. As cópias recortadas ficam na mesma pasta do item de origem e recebem um nome de arquivo único.

Recortar um WebP animado produz um WebP estático. A animação não é preservada no resultado recortado.

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 o referenciam. Cada resultado de conteúdo informa a coleção e o campo que contêm a referência e abre a entrada para edição. As entradas que estão na lixeira são identificadas na lista. Um resultado de Site Settings informa a configuração que seleciona o arquivo: Logo, Favicon ou Default Social Image.

Used in verifica estas referências:

• campos de imagem e de arquivo
• campos de imagem dentro de repetidores
• campos de imagem, arquivo e Portable Text dentro de campos blocks
• blocos de imagem e de galeria em campos Portable Text
• o logotipo 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. Antes de a cobertura estar completa, uma lista vazia mostra No usage to show yet.

O rastreamento de uso de mídia precisa estar habilitado para que os resultados de conteúdo possam ser completos. As configurações do site são listadas independentemente de o rastreamento estar habilitado. Um administrador habilita o rastreamento uma única vez para o site:

Depois de habilitado, o rastreamento de uso de mídia não pode ser desabilitado. As novas alterações de conteúdo são rastreadas depois que a captura está ativa; a varredura em segundo plano adiciona as referências das 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 os resultados como incompletos. Os administradores podem voltar a Media usage tracking para ver o status atual e as orientações de recuperação.

Renderizar imagens em templates

Um campo de imagem retorna um valor de mídia, não uma URL simples. Renderize esse valor com Image de emdash/ui para que as imagens locais e as fornecidas por provedores usem a URL, as dimensões, o ponto focal, as variantes responsivas e o espaço reservado 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.rewrite("/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 imediato e dá ao navegador uma dica de prioridade alta de busca. As demais imagens devem manter o carregamento adiado, que é o padrão do componente.

Se o campo tiver uma imagem para o modo escuro, Image renderiza as duas origens e escolhe uma com base no esquema de cores do visitante. Consulte Variantes escuras de imagem para a configuração do campo e do template.

Os templates recebem os metadados da mídia armazenados junto com a referência de conteúdo sem consultar a biblioteca de mídia novamente. Se uma integração personalizada precisar dos metadados mais recentes do provedor, solicite esse item explicitamente e evite consultar o provedor para cada imagem em páginas de coleção. A referência de tipos de campo descreve os valores de arquivo e de imagem armazenados.

Configurar armazenamento e provedores

A biblioteca local armazena os arquivos por meio do adaptador de armazenamento configurado para o site. Sites Node.js podem usar disco local ou armazenamento compatível com S3; sites Cloudflare normalmente usam um binding do R2. O adaptador decide onde os bytes ficam, e a biblioteca de mídia mantém o mesmo fluxo de trabalho de criação. Consulte Escolher o armazenamento de mídia para a configuração e os requisitos de persistência em produção.

Cloudflare Images e Cloudflare Stream podem ser registrados como provedores de mídia externos. Eles aparecem como origens no seletor, e Image entende os valores de imagem fornecidos por provedores. Os itens do provedor continuam sendo 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 recursos do EmDash.

Excluir mídia com segurança

Abra o arquivo na biblioteca de mídia, selecione Delete e confirme a exclusão permanente. Os autores podem excluir os arquivos locais que eles mesmos enviaram; os editores podem excluir qualquer arquivo local. Os itens de um provedor só são excluídos no provedor quando a origem expõe a exclusão e o usuário atual tem permissão.

Para automatizar envios e o gerenciamento de mídia, consulte a referência dos endpoints de media ou os comandos de mídia da CLI. Continue com Trabalhar com conteúdo para publicar entradas que usam a mídia selecionada.