Biblioteca de Mídia

O EmDash inclui uma biblioteca de mídia para gerenciar imagens, documentos e outros arquivos. Este guia cobre o upload, busca e uso de mídia no seu conteúdo.

Acessando a biblioteca de mídia

Abra a biblioteca de mídia na barra lateral do admin clicando em Mídia. A biblioteca principal mostra pastas e arquivos que não estão atribuídos a uma pasta. Abra uma pasta para ver seus arquivos.

Usado em

Abra um arquivo na biblioteca de mídia do EmDash para ver as entradas de conteúdo que o referenciam. Enquanto o EmDash escaneia o conteúdo existente, a lista inclui as referências encontradas até o momento e pode estar incompleta.

Ativar rastreamento de uso de mídia

Se o rastreamento de uso de mídia está desativado, um administrador pode ativá-lo:

1. Finalize quaisquer edições de conteúdo. Se outro aplicativo escreve diretamente no banco de dados de conteúdo, pause-o e aguarde quaisquer escritas em andamento terminarem.
2. Abra Configurações → Rastreamento de uso de mídia, selecione Ativar rastreamento e confirme.
3. Quando a página mostrar Indexando conteúdo existente, edições e outras escritas no banco de dados podem ser retomadas.
4. Mantenha a página aberta até mostrar Pronto. Se sair, volte para continuar do progresso salvo.

Uma vez ativado o rastreamento de uso de mídia, ele não pode ser desativado.

Fazendo upload de arquivos

Da biblioteca de mídia

1. Abra Mídia na barra lateral do admin.

2. Selecione Fazer upload de arquivos, depois Procurar arquivos para escolher um ou mais arquivos. Você também pode arrastar arquivos para qualquer lugar na biblioteca de mídia.

3. Os uploads começam automaticamente. O diálogo mostra o status de cada arquivo e permite cancelar ou tentar novamente arquivos individuais.

Do editor de conteúdo

1. Abra um campo de imagem, arquivo ou galeria no editor de conteúdo.

2. Pesquise, filtre por tipo, navegue por uma pasta ou alterne entre as fontes de mídia disponíveis.

3. Selecione mídia existente ou selecione Fazer upload de arquivos e escolha arquivos do seu computador. Você também pode soltar arquivos no seletor. Cada upload aparece nos resultados com seu status atual.

4. Se um upload falhar, selecione Tentar novamente ou Remover nesse item. Um upload bem-sucedido se torna um cartão de mídia selecionado.

5. Para uma galeria, use os controles de setas em Mídia selecionada para definir a ordem retornada.

6. Selecione a ação do seletor, como Selecionar, Inserir imagem ou Adicionar 3 imagens.

Tipos de arquivo suportados

O EmDash aceita estes tipos de arquivo por padrão:

Campos de imagem e arquivo podem permitir outros tipos MIME, incluindo image/svg+xml para arquivos SVG.

Backends de armazenamento

O EmDash suporta múltiplos backends de armazenamento. Configure o armazenamento na sua configuração 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",
      }),
    }),
  ],
});

Como os uploads funcionam

O admin usa o fluxo de destino de upload:

1. O cliente solicita um destino de upload, e o EmDash cria um item de mídia pendente.

2. O cliente faz upload do arquivo para o destino retornado.

3. O cliente confirma o upload.

4. O EmDash valida o arquivo armazenado e marca o item de mídia como pronto.

O armazenamento compatível com S3 retorna uma URL assinada para que o arquivo possa ignorar o runtime da aplicação. O armazenamento local e R2 nativo retornam um endpoint de streaming de mesma origem.

Encontrando mídia

Pesquisa

Use a caixa de pesquisa para encontrar arquivos por nome. A pesquisa corresponde a nomes de arquivo parciais.

Filtrar por tipo

Use o filtro de tipo para mostrar imagens, documentos, arquivos de vídeo ou áudio.

Organizando mídia em pastas

Editores podem selecionar Adicionar nova pasta da biblioteca principal. Abra uma pasta selecionando seu nome. Sem um termo de pesquisa, páginas de pastas mostram apenas a mídia atribuída àquela pasta. Pesquisas por nome de arquivo cobrem toda a biblioteca, incluindo outras pastas e a biblioteca principal.

Para mover um arquivo local para uma pasta visível, arraste seu cartão de grade ou linha de lista para a pasta. Você também pode abrir Detalhes da mídia, escolher um Local e selecionar Salvar. Use Local para devolver um arquivo à biblioteca principal ou movê-lo sem arrastar.

Autores podem mover arquivos locais que fizeram upload. Editores podem mover qualquer arquivo local. Arquivos de provedores externos não podem ser atribuídos a pastas.

Os uploads entram na biblioteca principal. Mova-os para uma pasta após o upload usando qualquer um dos métodos acima.

Deletar uma pasta retorna sua mídia à biblioteca principal. Os arquivos de mídia, URLs e referências de conteúdo permanecem inalterados.

Usando mídia no conteúdo

No editor de texto rico

1. Coloque o cursor onde deseja a imagem

2. Clique no botão de imagem na barra de ferramentas

3. Encontre uma imagem no seletor ou faça upload de uma nova.

4. Selecione Inserir imagem.

5. Adicione texto alternativo nas configurações da imagem.

Como imagem destacada

1. Abra uma entrada de conteúdo no editor

2. Encontre o campo Imagem Destacada na barra lateral

3. Clique em Selecionar Imagem

4. Escolha uma imagem do seletor ou faça upload de uma.

5. Selecione Selecionar, depois Salvar.

Em campos personalizados

Para campos configurados como tipos de imagem ou arquivo, selecione a ação do campo para abrir o mesmo seletor de mídia. As regras de tipo MIME do campo limitam as fontes e arquivos que você pode escolher.

Editar um ativo de imagem selecionado

Campos de imagem locais, imagens de texto rico e imagens de galeria fornecem três ações:

• Substituir muda a imagem usada no campo, bloco ou posição de galeria atual.
• Editar ativo abre os Detalhes da mídia para o item selecionado da Biblioteca de mídia. Você pode atualizar texto alternativo, legenda, ponto focal ou recorte enquanto permanece no editor de conteúdo.
• Remover limpa a referência de conteúdo atual. O item da Biblioteca de mídia permanece disponível.

Criar cópia recortada seleciona a nova cópia para o uso atual. Imagens de texto rico e galeria mantêm seu texto alternativo, legenda, layout e posição por uso. Substituir original mantém a mesma referência de mídia e muda a imagem em qualquer lugar onde esse ativo é usado.

Imagens de provedores externos e campos de arquivo fornecem Substituir e Remover, mas não Editar ativo.

Substituindo uma imagem

Use Substituir imagem para atualizar o arquivo por trás de um item de mídia local existente. Autores podem substituir imagens que fizeram upload, e editores podem substituir qualquer imagem local. A ação está disponível para imagens JPEG, PNG e WebP armazenadas em disco local, Cloudflare R2 ou armazenamento compatível com S3.

1. Abra Mídia, depois selecione uma imagem da biblioteca local.
2. Permaneça em Detalhes, depois selecione Substituir imagem.
3. Escolha uma imagem não vazia no mesmo formato do arquivo existente.
4. Revise o aviso, depois selecione Substituir imagem para confirmar.

A substituição pode usar dimensões ou proporção diferentes da imagem existente. O EmDash mantém o ID da mídia, nome do arquivo, URL, texto alternativo, legenda e local, então toda referência existente usa a substituição. Substituir o arquivo limpa seu ponto focal.

Substituir imagem faz upload de outro arquivo do seu computador. Para cortar a imagem atual, selecione Substituir original do editor de Recorte.

Definindo um ponto focal

Um ponto focal mantém a parte importante de uma imagem local visível quando um cartão, galeria ou outro layout a recorta para preencher uma forma fixa.

1. Abra Mídia e selecione uma imagem da biblioteca local, ou selecione Editar ativo para uma imagem local no editor de conteúdo.
2. Selecione Editar imagem, depois Ponto focal.
3. Clique ou arraste o marcador para a parte importante da imagem. Você também pode usar as teclas de seta.
4. Verifique as prévias quadrada, paisagem e retrato, depois selecione Salvar.

Selecione Redefinir para remover um ponto focal personalizado. O ponto salvo é copiado quando você seleciona a imagem para um campo de conteúdo ou galeria. Outros conteúdos que já usam a imagem mantêm seu ponto armazenado até você selecionar a imagem novamente. Quando você edita um ativo de um campo de conteúdo ou galeria, esse uso atual é atualizado com o ponto focal salvo.

Recortando uma imagem

O recorte está disponível para imagens JPEG, PNG e WebP enviadas ao EmDash. Funciona com armazenamento local, Cloudflare R2 e armazenamento compatível com S3. Imagens de provedores de mídia externos não podem ser recortadas na Biblioteca de mídia.

1. Abra Mídia, depois selecione uma imagem da biblioteca local.
2. Selecione Editar imagem, depois Recortar.
3. Selecione Original, Forma livre ou uma proporção comum. Proporções fixas permanecem travadas durante o redimensionamento. Forma livre permite alterar largura e altura independentemente.
4. Mova o quadro de recorte sobre a imagem. Para uma proporção fixa, arraste um canto para redimensionar. Forma livre também fornece quatro alças de borda. A grade de terços permanece visível. Você pode focar o quadro ou uma alça e usar as teclas de seta. Segure Shift para passos maiores.
5. Selecione uma das ações de recorte:
   • Criar cópia recortada cria um item de mídia separado e deixa o original inalterado. Selecione a cópia recortada em cada entrada de conteúdo onde deseja usá-la.
   • Substituir original substitui a imagem em todo lugar onde o item de mídia é usado. Entradas de conteúdo existentes mantêm a mesma referência de mídia e não são reescritas ou republicadas.

Recortar um arquivo WebP produz uma imagem WebP estática. Se a fonte é animada, o resultado recortado não retém a animação.

Exibindo mídia em templates

Acesse URLs de mídia dos seus dados de conteúdo:

---
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 ?? ""}
  />
)}

Imagens responsivas

Para campos de mídia do EmDash, use o componente 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 é para a imagem principal above-the-fold. Define loading="eager" e fetchpriority="high": loading controla se o carregamento é adiado, e fetchpriority dá ao navegador uma dica de prioridade para a requisição.

Quando o valor do campo carrega uma contraparte escura, Image renderiza ambas e mostra a que corresponde ao esquema de cores do visitante. Modo escuro cobre a habilitação do slot em um campo e a convenção de classe <html> na qual o componente se baseia.

O EmDash instala um endpoint de imagem que produz as variantes redimensionadas sob demanda. No Cloudflare Workers, esse endpoint usa o binding IMAGES. Transformação de imagens cobre de onde o binding vem e o que acontece quando está ausente.

Deletando mídia

1. Selecione o(s) arquivo(s) que deseja deletar

2. Clique em Deletar

3. Confirme a exclusão

API de mídia

Use a API REST para fazer upload, listar, atualizar, deletar e organizar mídia local. A referência de endpoints de mídia documenta o upload multipart direto e fluxos de destino de upload, parâmetros de requisição, formatos de resposta, permissões e operações de pasta.

Provedores de mídia

Além do armazenamento local, o EmDash suporta provedores de mídia externos para hospedagem especializada de imagens e vídeo. Provedores de mídia aparecem como abas no seletor de mídia, permitindo que editores escolham de múltiplas fontes.

Provedores disponíveis

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

export default defineConfig({
  integrations: [
    emdash({
      // ... configuração de banco de dados, armazenamento
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          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({
      // ... configuração de banco de dados, armazenamento
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

Usando múltiplos provedores

Você pode configurar múltiplos provedores. Cada um aparece como uma aba no seletor de mídia:

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,
        }),
      ],
    }),
  ],
});

A biblioteca de mídia local (aba “Biblioteca”) está sempre disponível junto com quaisquer provedores configurados.

Renderizando mídia de provedores

Use o componente Image para renderizar mídia:

---
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}
  />
)}

O componente automaticamente:

• Detecta o provedor do valor armazenado
• Renderiza um elemento <img> otimizado
• Aplica otimizações específicas do provedor (ex: transformações Cloudflare Images)

Valores de arquivo e metadados atuais

Um campo de arquivo armazena uma referência e um snapshot de metadados. Campos em cache como url, filename, mimeType e size são opcionais porque valores persistidos podem omiti-los:

interface FileValue {
  id: string;
  url?: string;
  src?: string;
  filename?: string;
  mimeType?: string;
  size?: number;
  provider?: string;
  meta?: Record<string, unknown>;
}

getEmDashEntry() e getEmDashCollection() retornam este valor armazenado sem uma consulta de mídia extra. Para metadados atuais, use o método get() do provedor configurado explicitamente. Use getEmbed() para a URL de renderização específica do provedor:

---
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;
---

Clientes HTTP autenticados podem fazer a mesma consulta explícita via GET /_emdash/api/media/:id para mídia local ou GET /_emdash/api/media/providers/:providerId/:itemId para outro provedor.

Para uma URL de arquivo local, use o meta.storageKey armazenado com o helper de URL pública. Isso respeita um domínio público R2 ou S3 configurado sem consultar a tabela de mídia:

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

Consultas de provedores podem realizar trabalho de rede ou banco de dados. Evite uma consulta por arquivo em páginas de coleção deslogadas; use o snapshot armazenado e componentes de renderização a menos que a requisição precise de metadados atualizados.

Tipo MediaValue

Campos de mídia armazenam um objeto MediaValue contendo informações do provedor:

interface MediaValue {
  provider?: string;
  id: string;
  src?: string;
  previewUrl?: string;
  filename?: string;
  mimeType?: string;
  width?: number;
  height?: number;
  focalX?: number;
  focalY?: number;
  alt?: string;
  meta?: Record<string, unknown>;
}

Isso permite ao EmDash renderizar mídia corretamente independente de onde está hospedada.

Próximos passos

• Trabalhando com conteúdo - Usar mídia no seu conteúdo
• Criar um blog - Adicionar imagens a posts de blog
• Consultando conteúdo - Exibir mídia em templates