Biblioteca de multimédia

O EmDash inclui uma biblioteca de multimédia para gerir imagens, documentos e outros ficheiros. Este guia abrange o carregamento, a organização e a utilização de multimédia no seu conteúdo.

Aceder à biblioteca de multimédia

Abra a biblioteca a partir da barra lateral de administração ao clicar em Media. A biblioteca mostra todos os ficheiros carregados com pré-visualizações, nomes e datas de carregamento.

Carregar ficheiros

A partir da biblioteca de multimédia

1. Clique em Media na barra lateral de administração

2. Clique em Upload ou arraste ficheiros para a zona de carregamento

3. Selecione um ou mais ficheiros no seu computador

4. Aguarde a conclusão dos carregamentos

A partir do editor de conteúdos

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

2. Clique em Upload no seletor de multimédia

3. Selecione um ficheiro no seu computador

4. Adicione texto alternativo e clique em Insert

Tipos de ficheiro suportados

O EmDash suporta tipos de ficheiro Web habituais:

Backends de armazenamento

O EmDash suporta vários backends de armazenamento. Configure o armazenamento na 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, { r2 } from "emdash/astro";

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 funcionam os carregamentos

O EmDash utiliza URLs assinados para carregamentos seguros:

1. O cliente pede um URL de carregamento à API

2. O servidor gera um URL assinado com expiração

3. O cliente carrega diretamente para o armazenamento usando esse URL

4. O servidor regista os metadados do ficheiro na base de dados

Assim, ficheiros grandes não passam pelo servidor da aplicação e podem ir diretamente para armazenamento na nuvem.

Organizar multimédia

Pastas

Crie pastas para organizar a sua multimédia:

1. Clique em New Folder na biblioteca de multimédia

2. Introduza o nome da pasta

3. Clique em Create

4. Arraste ficheiros para as pastas para os organizar

Pesquisa

Utilize a caixa de pesquisa para encontrar ficheiros pelo nome. A pesquisa corresponde a partes do nome do ficheiro.

Filtros

Filtre a multimédia por:

• Type — Imagens, documentos, vídeo, áudio
• Date — Intervalo de datas de carregamento
• Folder — Pasta específica

Utilizar multimédia no conteúdo

No editor de texto formatado

1. Coloque o cursor onde pretende a imagem

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

3. Selecione uma imagem na biblioteca ou carregue uma nova

4. Introduza o texto alternativo

5. Clique em Insert

Como imagem em destaque

1. Abra uma entrada de conteúdos no editor

2. Localize o campo Featured Image na barra lateral

3. Clique em Select Image

4. Escolha na biblioteca de multimédia ou carregue um ficheiro

5. Clique em Save

Em campos personalizados

Para campos configurados como imagem ou ficheiro, clique no campo para abrir o seletor de multimédia.

Apresentar multimédia nos templates

Aceda aos URLs da multimédia a partir dos dados do 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, utilize o componente Image do Astro com URLs externos:

Imagens responsivas

Para imagens responsivas, utilize o componente Image do Astro com URLs externos:

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

Eliminar multimédia

1. Selecione o(s) ficheiro(s) que pretende eliminar

2. Clique em Delete

3. Confirme a eliminação

API de multimédia

Aceda à multimédia por programação com a API de administração.

Carregar um ficheiro

Carregue multimédia como dados multipart/form-data:

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

file=<binary file data>

Resposta:

{
	"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 multimédia

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

Eliminar multimédia

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

Fornecedores de multimédia

Além do armazenamento local, o EmDash suporta fornecedores externos para alojamento especializado de imagem e vídeo. Os fornecedores aparecem como separadores no seletor de multimédia, permitindo escolher entre várias origens.

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

Utilizar vários fornecedores

Pode configurar vários fornecedores. Cada um aparece como um separador no seletor de multimé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 multimédia local (separador «Library») está sempre disponível junto de qualquer fornecedor configurado.

Renderizar multimédia do fornecedor

Utilize o componente Image para renderizar multimé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:

• Deteta o fornecedor a partir do valor guardado
• Renderiza um elemento <img> otimizado
• Aplica otimizações específicas do fornecedor (por exemplo, transformações do Cloudflare Images)

Tipo MediaValue

Os campos de multimédia guardam um objeto MediaValue com informação do fornecedor:

interface MediaValue {
  provider?: string;    // Provider ID, defaults to "local"
  id: string;           // Provider-specific ID
  src?: string;         // Direct URL (for local media or legacy data)
  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
}

Isto permite ao EmDash renderizar a multimédia corretamente independentemente do local de alojamento.

Próximos passos

• Working with Content — Utilizar multimédia no seu conteúdo
• Create a Blog — Adicionar imagens às publicações do blog
• Querying Content — Apresentar multimédia nos templates