Biblioteca de mídia

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

Acessando a biblioteca de mídia

Abra a biblioteca de mídia pela barra lateral do admin clicando em Media. A biblioteca exibe todos os arquivos enviados com previews, nomes de arquivo e datas de upload.

Fazendo upload de arquivos

Da biblioteca de mídia

1. Clique em Media na barra lateral do admin

2. Clique em Upload ou arraste arquivos para a área de upload

3. Selecione um ou mais arquivos do seu computador

4. Aguarde os uploads serem concluídos

Do editor de conteúdo

1. No editor de texto rico, clique no botão de imagem

2. Clique em Upload no seletor de mídia

3. Selecione um arquivo do seu computador

4. Adicione texto alternativo e clique em Inserir

Tipos de arquivo suportados

O EmDash suporta tipos de arquivo web comuns:

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 EmDash usa URLs assinadas para uploads seguros:

1. O cliente solicita uma URL de upload da API

2. O servidor gera uma URL assinada com expiração

3. O cliente faz upload diretamente para o armazenamento usando a URL assinada

4. O servidor registra os metadados do arquivo no banco de dados

Essa abordagem mantém arquivos grandes fora do seu servidor de aplicação e permite uploads diretos para o armazenamento em nuvem.

Organizando mídia

Pastas

Crie pastas para organizar sua mídia:

1. Clique em New Folder na biblioteca de mídia

2. Digite um nome para a pasta

3. Clique em Criar

4. Arraste arquivos para pastas para organizá-los

Busca

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

Filtros

Filtre mídia por:

• Tipo - Imagens, Documentos, Vídeo, Áudio
• Data - Intervalo de data de upload
• Pasta - Pasta específica

Usando mídia no conteúdo

No editor de texto rico

1. Posicione seu cursor onde deseja a imagem

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

3. Selecione uma imagem da biblioteca de mídia ou faça upload de uma nova

4. Digite o texto alternativo

5. Clique em Inserir

Como imagem destacada

1. Abra uma entrada de conteúdo no editor

2. Encontre o campo Featured Image na barra lateral

3. Clique em Selecionar imagem

4. Escolha da biblioteca de mídia ou faça upload

5. Clique em Salvar

Em campos personalizados

Para campos configurados como tipos de imagem ou arquivo, clique no campo para abrir o seletor de mídia.

Exibindo mídia em templates

Acesse URLs de mídia a partir 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 acima da dobra. 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.

Excluindo mídia

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

2. Clique em Excluir

3. Confirme a exclusão

API de mídia

Acesse mídia programaticamente usando a API de administração.

Fazer upload de um arquivo

Faça upload de mídia como dados de formulário multipart:

POST /_emdash/api/media
Content-Type: multipart/form-data
Authorization: Bearer YOUR_API_TOKEN

file=<binary file data>

Um upload bem-sucedido retorna o item de mídia armazenado:

{
	"success": true,
	"data": {
		"item": {
			"id": "01ABC123",
			"filename": "hero-image.jpg",
			"mime_type": "image/jpeg",
			"storage_key": "media/abc123/hero-image.jpg",
			"width": 1200,
			"height": 800
		}
	}
}

Listar mídia

A seguinte requisição lista mídia sob um prefixo:

GET /_emdash/api/media?prefix=images/&limit=20
Authorization: Bearer YOUR_API_TOKEN

Excluir mídia

A seguinte requisição exclui um arquivo armazenado:

DELETE /_emdash/api/media/images/hero.jpg
Authorization: Bearer YOUR_API_TOKEN

Provedores de mídia

Além do armazenamento local, o EmDash suporta provedores de mídia externos para hospedagem especializada de imagens e vídeos. Os 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,
          // Opcional: domínio de entrega personalizado
          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,
          // Opcional: configurações do player
          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 “Library”) está sempre disponível junto com quaisquer provedores configurados.

Renderizando mídia do provedor

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 a partir do valor armazenado
• Renderiza um elemento <img> otimizado
• Aplica otimizações específicas do provedor (ex. transformações do Cloudflare Images)

Tipo MediaValue

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

interface MediaValue {
  provider?: string;    // ID do provedor, padrão "local"
  id: string;           // ID específico do provedor
  src?: string;         // URL direta (para mídia local ou valores de string simples)
  previewUrl?: string;  // URL de preview para exibição no admin (provedores externos)
  filename?: string;    // Nome do arquivo original
  mimeType?: string;    // Tipo MIME
  width?: number;       // Largura da imagem/vídeo
  height?: number;      // Altura da imagem/vídeo
  alt?: string;         // Texto alternativo
  meta?: Record<string, unknown>; // Metadados específicos do provedor
}

Isso permite ao EmDash renderizar mídia corretamente independentemente 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 do blog
• Consultando conteúdo - Exibir mídia em templates