メディアライブラリ | EmDash CMS Everything

EmDash には、画像、ドキュメント、その他のファイルを管理するためのメディアライブラリが含まれています。このガイドでは、コンテンツ内でのメディアのアップロード、検索、使用について説明します。

メディアライブラリへのアクセス

管理サイドバーの メディア をクリックしてメディアライブラリを開きます。メインライブラリには、フォルダに割り当てられていないフォルダとファイルが表示されます。フォルダを開いてそのファイルを確認します。

アップロードボタン付きの画像グリッドを表示する EmDash メディアライブラリ

使用場所

EmDash のメディアライブラリでファイルを開くと、そのファイルを参照しているコンテンツエントリを確認できます。EmDash が既存のコンテンツをスキャンする間、リストにはこれまでに見つかった参照が含まれ、不完全な場合があります。

メディア使用状況トラッキングを有効にする

メディア使用状況トラッキングが無効な場合、管理者は以下の手順で有効にできます：

すべてのコンテンツ編集を完了します。別のアプリケーションがコンテンツデータベースに直接書き込んでいる場合は、一時停止して進行中の書き込みが完了するのを待ちます。
設定 → メディア使用状況トラッキング を開き、トラッキングを有効にする を選択して確認します。
ページに 既存コンテンツのインデックス作成中 と表示されたら、編集やその他のデータベース書き込みを再開できます。
準備完了 と表示されるまでページを開いたままにします。ページを離れた場合は、戻って保存された進行状況から続行します。

メディア使用状況トラッキングが有効になると、無効にすることはできません。

ファイルのアップロード

メディアライブラリから

管理サイドバーの メディア を開きます。
ファイルをアップロード を選択し、次に ファイルを参照 を選択して1つ以上のファイルを選びます。メディアライブラリの任意の場所にファイルをドラッグすることもできます。
アップロードは自動的に開始されます。ダイアログには各ファイルのステータスが表示され、個別のファイルのキャンセルや再試行が可能です。

コンテンツエディターから

コンテンツエディターで画像、ファイル、またはギャラリーフィールドを開きます。
検索、タイプでフィルター、フォルダの参照、または利用可能なメディアソース間の切り替えを行います。
既存のメディアを選択するか、ファイルをアップロード を選択してコンピューターからファイルを選びます。ピッカーにファイルをドロップすることもできます。各アップロードは現在のステータスとともに結果に表示されます。
アップロードに失敗した場合、そのアイテムで 再試行 または削除を選択します。成功したアップロードは選択済みメディアカードになります。
ギャラリーの場合、選択されたメディア の下の矢印コントロールを使用して返される順序を設定します。
選択、画像を挿入、3枚の画像を追加 などのピッカーアクションを選択します。

サポートされるファイルタイプ

EmDash はデフォルトで以下のファイルタイプを受け付けます：

カテゴリ	拡張子
画像	`.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.avif`
ドキュメント	`.pdf`
ビデオ	`.mp4`, `.webm`, `.mov`
オーディオ	`.mp3`, `.wav`, `.ogg`

画像フィールドとファイルフィールドは、SVG ファイル用の image/svg+xml を含む他の MIME タイプを許可できます。

ストレージバックエンド

EmDash は複数のストレージバックエンドをサポートしています。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",
      }),
    }),
  ],
});

ファイルは ./uploads ディレクトリに保存されます。開発やシングルサーバーデプロイメントに適しています。

Cloudflare R2

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

wrangler.jsonc で設定された R2 バケットが必要です：

{
	"r2_buckets": [
		{
			"binding": "MEDIA_BUCKET",
			"bucket_name": "my-media-bucket",
		},
	],
}

S3 互換

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

Cloudflare R2（S3 API 経由）、MinIO、その他の S3 互換サービスで動作します。

アップロードの仕組み

アドミンはアップロードターゲットフローを使用します：

クライアントがアップロードターゲットをリクエストし、EmDash がペンディングのメディアアイテムを作成します。
クライアントが返されたターゲットにファイルをアップロードします。
クライアントがアップロードを確認します。
EmDash が保存されたファイルを検証し、メディアアイテムを準備完了としてマークします。

S3 互換ストレージは署名付き URL を返すので、ファイルはアプリケーションランタイムをバイパスできます。ローカルストレージとネイティブ R2 は代わりに同一オリジンのストリーミングエンドポイントを返します。

メディアの検索

検索

検索ボックスを使用してファイル名で検索します。検索は部分的なファイル名にもマッチします。

タイプでフィルター

タイプフィルターを使用して、画像、ドキュメント、ビデオ、またはオーディオファイルを表示します。

フォルダでメディアを整理

エディターはメインライブラリから 新しいフォルダを追加 を選択できます。フォルダ名を選択してフォルダを開きます。検索語がない場合、フォルダページはそのフォルダに割り当てられたメディアのみを表示します。ファイル名検索は、他のフォルダやメインライブラリを含むライブラリ全体をカバーします。

ローカルファイルを表示されているフォルダに移動するには、そのグリッドカードまたはリスト行をフォルダにドラッグします。メディア詳細 を開き、場所を選択して保存をクリックすることもできます。場所を使用してファイルをメインライブラリに戻したり、ドラッグせずに移動したりできます。

作成者は自分がアップロードしたローカルファイルを移動できます。エディターは任意のローカルファイルを移動できます。外部プロバイダーのファイルはフォルダに割り当てることができません。

アップロードはメインライブラリに入ります。上記のいずれかの方法を使用して、アップロード後にフォルダに移動します。

フォルダを削除すると、そのメディアはメインライブラリに戻ります。メディアファイル、URL、コンテンツ参照は変更されません。

コンテンツでメディアを使用する

リッチテキストエディターで

画像を挿入したい場所にカーソルを置きます
ツールバーの画像ボタンをクリックします
ピッカーで画像を見つけるか、新しい画像をアップロードします。
画像を挿入 を選択します。
画像設定で代替テキストを追加します。

アイキャッチ画像として

エディターでコンテンツエントリを開きます
サイドバーで アイキャッチ画像 フィールドを見つけます
画像を選択 をクリックします
ピッカーから画像を選ぶか、アップロードします。
選択を選び、次に保存を選択します。

カスタムフィールドで

画像またはファイルタイプとして設定されたフィールドの場合、フィールドアクションを選択して同じメディアピッカーを開きます。フィールドの MIME タイプルールにより、選択できるソースとファイルが制限されます。

選択した画像アセットの編集

ローカル画像フィールド、リッチテキスト画像、ギャラリー画像は3つのアクションを提供します：

置換は現在のフィールド、ブロック、またはギャラリー位置で使用されている画像を変更します。
アセットを編集 は選択されたメディアライブラリアイテムのメディア詳細を開きます。コンテンツエディターにいながら、代替テキスト、キャプション、フォーカルポイント、またはクロップを更新できます。
削除は現在のコンテンツ参照をクリアします。メディアライブラリアイテムは引き続き利用可能です。

クロップされたコピーを作成 は現在の使用箇所に新しいコピーを選択します。リッチテキストとギャラリー画像は、使用ごとの代替テキスト、キャプション、レイアウト、位置を保持します。オリジナルを置換 は同じメディア参照を保持し、そのアセットが使用されているすべての場所で画像を変更します。

外部プロバイダーの画像とファイルフィールドは置換と削除を提供しますが、アセットを編集 は提供しません。

画像の置換

画像を置換 を使用して、既存のローカルメディアアイテムの背後にあるファイルを更新します。作成者はアップロードした画像を置換でき、エディターは任意のローカル画像を置換できます。このアクションは、ローカルディスク、Cloudflare R2、または S3 互換ストレージに保存された JPEG、PNG、WebP 画像で利用可能です。

メディア を開き、ローカルライブラリから画像を選択します。
詳細に留まり、画像を置換 を選択します。
既存のファイルと同じ形式の空でない画像を選択します。
警告を確認し、画像を置換 を選択して確定します。

置換は既存の画像とは異なる寸法やアスペクト比を使用できます。EmDash はメディア ID、ファイル名、URL、代替テキスト、キャプション、場所を保持するので、既存のすべての参照が置換を使用します。ファイルを置換するとフォーカルポイントがクリアされます。

画像を置換 はコンピューターから別のファイルをアップロードします。現在の画像をトリミングするには、クロップ エディターから オリジナルを置換 を選択します。

フォーカルポイントの設定

フォーカルポイントは、カード、ギャラリー、その他のレイアウトが固定の形状に合わせてクロップする際に、ローカル画像の重要な部分を表示し続けます。

メディア を開いてローカルライブラリから画像を選択するか、コンテンツエディターでローカル画像の アセットを編集 を選択します。
画像を編集 を選択し、次に フォーカルポイント を選択します。
画像の重要な部分にマーカーをクリックまたはドラッグします。矢印キーも使用できます。
正方形、横長、縦長のプレビューを確認し、保存を選択します。

カスタムフォーカルポイントを削除するには リセット を選択します。保存されたポイントは、コンテンツフィールドやギャラリーに画像を選択するときにコピーされます。画像を既に使用している他のコンテンツは、画像を再度選択するまで保存されたポイントを保持します。コンテンツフィールドやギャラリーからアセットを編集すると、その現在の使用箇所が保存されたフォーカルポイントで更新されます。

画像のクロップ

クロップは EmDash にアップロードされた JPEG、PNG、WebP 画像で利用可能です。ローカルストレージ、Cloudflare R2、S3 互換ストレージで動作します。外部メディアプロバイダーの画像はメディアライブラリでクロップできません。

メディア を開き、ローカルライブラリから画像を選択します。
画像を編集 を選択し、次に クロップ を選択します。
オリジナル、フリーフォーム、または一般的なアスペクト比を選択します。固定比率はリサイズ中ロックされたままです。フリーフォーム では幅と高さを独立して変更できます。
画像上でクロップフレームを移動します。固定比率の場合、角をドラッグしてリサイズします。フリーフォーム では4つのエッジハンドルも提供されます。三分割法グリッドは表示されたままです。フレームまたはハンドルにフォーカスして矢印キーを使用できます。Shift を押すと大きなステップになります。
クロップアクションの1つを選択します：
- クロップされたコピーを作成 は別のメディアアイテムを作成し、オリジナルは変更しません。使用したいコンテンツエントリでクロップされたコピーを選択します。
- オリジナルを置換 はメディアアイテムが使用されているすべての場所で画像を置換します。既存のコンテンツエントリは同じメディア参照を保持し、書き換えや再公開は行われません。

WebP ファイルをクロップすると静止 WebP 画像が生成されます。ソースがアニメーションの場合、クロップされた結果はアニメーションを保持しません。

テンプレートでメディアを表示する

コンテンツデータからメディア URL にアクセスします：

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

レスポンシブ画像

EmDash メディアフィールドには、emdash/ui の Image コンポーネントを使用します：

---
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 はプライマリのアバブザフォールド画像用です。loading="eager" と fetchpriority="high" を設定します：loading は読み込みを遅延させるかを制御し、fetchpriority はリクエストの優先度ヒントをブラウザに与えます。

フィールド値がダークカウンターパートを持つ場合、Image は両方をレンダリングし、訪問者のカラースキームに一致するものを表示します。ダークモードでは、フィールドでスロットを有効にすることと、コンポーネントが依存する <html> クラス規約について説明しています。

EmDash はリクエストに応じてリサイズされたバリアントを生成する画像エンドポイントをインストールします。Cloudflare Workers では、このエンドポイントは IMAGES バインディングを使用します。画像変換では、バインディングの由来と、それが欠落している場合の動作について説明しています。

メディアの削除

削除したいファイルを選択します
削除をクリックします
削除を確認します

メディア API

REST API を使用して、ローカルメディアのアップロード、一覧表示、更新、削除、整理を行います。メディアエンドポイントリファレンスでは、直接マルチパートアップロードとアップロードターゲットフロー、リクエストパラメーター、レスポンス形式、権限、フォルダ操作について文書化しています。

メディアプロバイダー

ローカルストレージに加えて、EmDash は画像やビデオの専門的なホスティング用の外部メディアプロバイダーをサポートしています。メディアプロバイダーはメディアピッカーのタブとして表示され、エディターが複数のソースから選択できます。

利用可能なプロバイダー

Cloudflare Images

Cloudflare Images は自動最適化、リサイズ、フォーマット変換機能付きの画像ホスティングを提供します。

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

export default defineConfig({
  integrations: [
    emdash({
      // ... データベース、ストレージ設定
      mediaProviders: [
        cloudflareImages({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_IMAGES_TOKEN,
          // オプション：カスタム配信ドメイン
          deliveryDomain: "images.example.com",
        }),
      ],
    }),
  ],
});

機能：

アドミンから直接画像を閲覧・アップロード
自動画像最適化とフォーマット変換
URL ベースの変換（リサイズ、クロップ、フォーマット）
レスポンシブ画像用の柔軟なバリアント

Cloudflare Stream

Cloudflare Stream は HLS/DASH アダプティブストリーミング付きのビデオホスティングを提供します。

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

export default defineConfig({
  integrations: [
    emdash({
      // ... データベース、ストレージ設定
      mediaProviders: [
        cloudflareStream({
          accountId: import.meta.env.CF_ACCOUNT_ID,
          apiToken: import.meta.env.CF_STREAM_TOKEN,
          // オプション：プレーヤー設定
          controls: true,
          autoplay: false,
          loop: false,
        }),
      ],
    }),
  ],
});

機能：

アドミンからビデオを閲覧、検索、アップロード
HLS および DASH アダプティブストリーミング
自動サムネイル生成
大きなファイルのダイレクトアップロード

複数のプロバイダーの使用

複数のプロバイダーを設定できます。各プロバイダーはメディアピッカーのタブとして表示されます：

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

ローカルメディアライブラリ（「ライブラリ」タブ）は、設定されたプロバイダーとともに常に利用可能です。

プロバイダーメディアのレンダリング

Image コンポーネントを使用してメディアをレンダリングします：

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

コンポーネントは自動的に：

保存された値からプロバイダーを検出
最適化された <img> 要素をレンダリング
プロバイダー固有の最適化を適用（例：Cloudflare Images 変換）

ファイル値と現在のメタデータ

ファイルフィールドは参照とメタデータスナップショットを保存します。url、filename、mimeType、size などのキャッシュされたフィールドはオプションです。永続化された値がそれらを省略する場合があるためです：

interface FileValue {
  id: string;
  url?: string;        // レガシーキャッシュ URL
  src?: string;        // 外部プロバイダーからのダイレクト URL
  filename?: string;  // キャッシュされたオリジナルファイル名
  mimeType?: string;  // キャッシュされた MIME タイプ
  size?: number;       // キャッシュされたサイズ（利用可能な場合）
  provider?: string;   // デフォルト "local"
  meta?: Record<string, unknown>;
}

getEmDashEntry() と getEmDashCollection() は、追加のメディアクエリなしでこの保存された値を返します。現在のメタデータには、設定されたプロバイダーの get() メソッドを明示的に使用します。プロバイダー固有のレンダー URL には getEmbed() を使用します：

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

認証済み HTTP クライアントは、ローカルメディアの場合は GET /_emdash/api/media/:id、別のプロバイダーの場合は GET /_emdash/api/media/providers/:providerId/:itemId を通じて同じ明示的な検索を行えます。

ローカルファイル URL の場合、保存された meta.storageKey をパブリック URL ヘルパーで使用します。これはメディアテーブルを照会せずに設定された R2 または S3 パブリックドメインを尊重します：

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

プロバイダー検索はネットワークやデータベースの作業を伴う場合があります。ログアウトしたコレクションページでファイルごとに1回の検索を避けてください。リクエストに新鮮なメタデータが必要でない限り、保存されたスナップショットとレンダリングコンポーネントを使用してください。

MediaValue タイプ

メディアフィールドはプロバイダー情報を含む MediaValue オブジェクトを保存します：

interface MediaValue {
  provider?: string;    // プロバイダー ID、デフォルト "local"
  id: string;           // プロバイダー固有の ID
  src?: string;         // ダイレクト URL（ローカルメディアまたはプレーン文字列値用）
  previewUrl?: string;  // アドミン表示用のプレビュー URL（外部プロバイダー）
  filename?: string;    // オリジナルファイル名
  mimeType?: string;    // MIME タイプ
  width?: number;       // 画像/ビデオの幅
  height?: number;      // 画像/ビデオの高さ
  focalX?: number;      // 水平フォーカル位置（0〜1）
  focalY?: number;      // 垂直フォーカル位置（0〜1）
  alt?: string;         // 代替テキスト
  meta?: Record<string, unknown>; // プロバイダー固有のメタデータ
}

これにより、EmDash はホスト場所に関係なくメディアを正しくレンダリングできます。

次のステップ

コンテンツの操作 - コンテンツでメディアを使用する
ブログの作成 - ブログ投稿に画像を追加する
コンテンツのクエリ - テンプレートでメディアを表示する