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.

Acessar a Biblioteca de Mídia

Abra a biblioteca de mídia na barra lateral do admin clicando em Media. A biblioteca exibe todos os arquivos carregados com prévias, nomes de arquivo e datas de upload.

Fazer 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 a conclusão dos uploads

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 Insert

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

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

Organizar Mídia

Pastas

Crie pastas para organizar sua mídia:

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

2. Digite um nome de pasta

3. Clique em Create

4. Arraste arquivos para pastas para organizá-los

Pesquisa

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

Filtros

Filtre mídia por:

• Type - Imagens, Documentos, Vídeo, Áudio
• Date - Intervalo de data de upload
• Folder - Pasta específica

Usar Mídia no Conteúdo

No Editor de Texto Rico

1. Posicione seu cursor onde você quer 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 Insert

Como Imagem em Destaque

1. Abra uma entrada de conteúdo no editor

2. Encontre o campo Featured Image na barra lateral

3. Clique em Select Image

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

5. Clique em Save

Em Campos Personalizados

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

Exibir 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 imagens responsivas, use o componente Image do Astro com URLs externas:

---
import { Image } from "astro:assets";
import { getEmDashEntry } from "emdash";

const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
---

{post?.data.featured_image && (
  <Image
    src={post.data.featured_image}
    alt={post.data.featured_image_alt ?? ""}
    width={800}
    height={450}
  />
)}

Excluir Mídia

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

2. Clique em Delete

3. Confirme a exclusão

API de Mídia

Acesse mídia programaticamente usando a API admin.

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 solicitaçã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 solicitaçã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 os 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({
      // ... database, storage config
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          // Optional: custom delivery domain
          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({
      // ... database, storage config
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          // Optional: player settings
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

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

Renderizar 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 (por exemplo, transformações Cloudflare Images)

Tipo MediaValue

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

interface MediaValue {
  provider?: string;    // Provider ID, defaults to "local"
  id: string;           // Provider-specific ID
  src?: string;         // Direct URL (for local media or plain-string values)
  previewUrl?: string;  // Preview URL for admin display (external providers)
  filename?: string;    // Original filename
  mimeType?: string;    // MIME type
  width?: number;       // Image/video width
  height?: number;      // Image/video height
  alt?: string;         // Alt text
  meta?: Record<string, unknown>; // Provider-specific metadata
}

Isso permite que o EmDash renderize mídia corretamente independentemente de onde esteja hospedada.

Próximos Passos

• Trabalhar com Conteúdo - Usar mídia no seu conteúdo
• Criar um Blog - Adicionar imagens a posts de blog
• Consultar Conteúdo - Exibir mídia em templates