メディアライブラリ

メディアライブラリには、再利用できる画像、ドキュメント、動画、音声が保存されます。編集者はファイルを一度アップロードするだけで、コンテンツフィールドや Portable Text から選択でき、ローカルのメディアアイテムを参照しているコンテンツエントリも確認できます。

メディアライブラリを開く

管理画面のサイドバーで Media を選択します。Main library には、フォルダーと、まだフォルダーに入れていないファイルが含まれます。フォルダーを選択するとそのファイルを閲覧でき、グリッド表示とリスト表示を切り替えることもできます。

サイトに外部のメディアプロバイダーがある場合は、各プロバイダーが別のソースとして表示されます。プロバイダーの機能は異なります。ソースによっては、閲覧と選択はできても、フォルダー、ローカルでの画像編集、削除には対応していない場合があります。

ファイルをアップロードする

ライブラリからアップロードする

アップロードは、ファイルを追加するとすぐに始まります。新しいローカルファイルは、アップロード前に別のフォルダーを開いていた場合でも、Main library に入ります。

コンテンツの編集中にアップロードする

画像、ファイル、ギャラリー、Portable Text の画像フィールドでは、メディアピッカーを使用します。フィールドを開き、Upload files を選択して、ファイルを選ぶかドロップします。アップロードが完了したファイルは現在の選択に加わります。失敗したアップロードは表示されたままなので、再試行または削除できます。

ギャラリーの場合は、Selected media を確認し、移動コントロールで順序を設定してから Add images を選択します。単一の画像またはファイルの場合は、アップロードが完了してから Select または Insert image を選択します。

受け入れられるファイルとサイズ制限

ローカルのメディアライブラリは、デフォルトで次のファイルグループを受け入れます。

• PNG、JPEG、GIF、WebP、AVIF の画像
• MP4、WebM、QuickTime 動画などの一般的な動画形式
• MP3、WAV、Ogg 音声などの一般的な音声形式
• PDF ドキュメント

SVG ファイルにはアクティブなコンテンツが含まれる可能性があるため、SVG はデフォルトのアップロード対象から除外されています。コンテンツモデルでより狭い選択肢や別の形式が必要な場合は、画像フィールドまたはファイルフィールドに、独自の受け入れ可能なファイルタイプのリストを定義できます。EmDash は、image/png や application/pdf のようなラベルであるメディアタイプで各ファイルを識別し、コンテンツの保存時にもフィールドのリストを再度確認します。ブラウザーのファイル選択ダイアログを変更しても、このサーバー側のチェックを回避することはできません。

デフォルトの最大サイズは 1 ファイルあたり 50 MB です。サイト開発者は maxUploadSize で変更できます。プロバイダーが形式やサイズに追加の制限を課す場合があり、その失敗はアップロードの行に表示されます。

ファイルを見つけて整理する

検索はファイル名の部分一致で行われます。タイプフィルターを使うと、結果を画像、ドキュメント、動画、音声に絞り込めます。ファイル名の検索は、フォルダーを開いている間もローカルライブラリ全体が対象です。検索せずにフォルダーを閲覧すると、そのフォルダーに割り当てられたファイルだけが表示されます。

編集者は、Main library で Add new folder を選択できます。ローカルファイルを移動するには、そのカードまたは行を表示中のフォルダーにドラッグするか、ファイルを開いて Location を変更し、Save を選択します。ファイルを現在のフォルダーから外すには、場所として Main library を指定します。

作成者は、自分がアップロードしたローカルファイルを移動できます。編集者は、すべてのローカルファイルを移動できます。外部プロバイダーのアイテムは、メディアライブラリのフォルダーに割り当てることができません。

フォルダーを削除すると、その中のファイルは Main library に戻ります。ファイルが削除されたり、URL が変わったり、コンテンツの参照が削除されたりすることはありません。

コンテンツ用にメディアを選択する

Portable Text の画像

Portable Text フィールドにカーソルを置き、ブロックメニューを開いて Image を選択します。画像を選ぶかアップロードしてから、Insert image を選択します。その後、画像ブロックを選択すると、代替テキスト、キャプション、表示サイズ、配置を追加できます。

画像フィールドとファイルフィールド

Select image や Select file などのフィールドアクションを選択し、アイテムを選んで選択を確定します。フィールドの MIME タイプのルールによって、表示されるライブラリのアイテムとメディアソースが絞り込まれます。

ブログテンプレートの featured_image フィールドは、選択したメディアの値を投稿とともに保存します。エントリを保存すると、その参照が下書きに保存されます。公開すると、公開用のコンテンツクエリで利用できるようになります。

ギャラリーフィールド

1 つ以上の画像を選択し、Selected media の下で並べ替えてから確定します。ギャラリーは、複数の位置がメディアライブラリの同じアイテムを参照している場合でも、独自の順序と、画像ごとの代替テキストおよびキャプションを保持します。

コンテンツで使用中の画像を編集する

選択したローカル画像では、影響範囲の異なる複数のアクションを利用できます。

• Replace は、このフィールド、ブロック、またはギャラリー位置に対して、別のメディアライブラリのアイテムを選びます。元のアイテムを使用している他のエントリは変わりません。
• Edit asset は、元になっているメディアライブラリのアイテムを開きます。メタデータの変更や、元に戻せない画像の変更は、そのアイテムの他の使用箇所にも影響する場合があります。
• Remove は、このコンテンツの参照を解除します。メディアライブラリのアイテムは引き続き利用できます。

Edit asset で切り抜いたコピーを作成すると、ピッカーは現在の使用箇所に対して新しいコピーを選択します。Portable Text とギャラリーの画像は、その使用箇所の代替テキスト、キャプション、レイアウト、位置を保持します。Edit asset で元の画像を置き換えた場合は、メディア ID が変わらないため、そのアイテムのすべての使用箇所に変更後の画像が反映されます。

外部プロバイダーの画像フィールドとファイルフィールドでは Replace と Remove を利用できますが、ローカルのアセットエディターは開きません。

ローカル画像を置き換える

Replace image は、既存のメディアライブラリのアイテムの裏側に新しいバイトデータをアップロードします。そのアイテムを参照しているすべての場所で、画像の新しいバージョンを表示したい場合に使用します。

このアクションは、準備ができている JPEG、PNG、WebP のアイテムで利用できます。作成者は自分がアップロードした画像を置き換えられ、編集者はすべてのローカル画像を置き換えられます。

EmDash は、メディア ID、ファイル名、URL、代替テキスト、キャプション、フォルダーを維持します。そのため、既存のコンテンツの参照は引き続き機能し、置き換え後の画像が表示されます。置き換えを行うと、保存されていたフォーカルポイントは消去されます。その座標が新しい画像に当てはまらない場合があるためです。

1 つのフィールドまたは画像ブロックだけを変更したい場合は、代わりにコンテンツエディターで Replace を使用してください。

フォーカルポイントを設定する

フォーカルポイントは、レイアウトによって画像が正方形、横長、縦長などの固定された形に切り抜かれるときに、表示されたままにしたい画像の部分を示します。

Reset を選択すると、カスタムのポイントが削除されます。フィールドまたはギャラリーに画像を選ぶと、EmDash はアセットの現在のフォーカルポイントを、そのコンテンツの値にコピーします。すでにその画像を使用しているコンテンツは、画像をもう一度選択するまで、保存済みのポイントを保持します。コンテンツフィールドから Edit asset を開いた場合は、保存したポイントでその現在の使用箇所が更新されます。

ローカル画像を切り抜く

切り抜きは、EmDash に保存されている、準備ができている JPEG、PNG、WebP の画像で利用できます。外部プロバイダーの画像は、ローカルのアセットエディターでは切り抜けません。

Replace original が使えるのは、Original のアスペクト比のときだけです。Freeform やその他の比率では、Create cropped copy を使用してください。切り抜いたコピーは元のアイテムと同じフォルダーに置かれ、一意のファイル名が付けられます。

アニメーション WebP を切り抜くと、静止画の WebP になります。切り抜いた結果にアニメーションは残りません。

ファイルの使用箇所を確認する

ローカルファイルを開いて Used in を選択すると、そのファイルを参照しているコンテンツエントリとサイト設定が一覧表示されます。各コンテンツの結果には、参照を含むコレクションとフィールドの名前が示され、そこからエントリを開いて編集できます。ゴミ箱に入っているエントリは、一覧の中で識別できます。Site Settings の結果には、そのファイルを選択している設定（Logo、Favicon、Default Social Image）が示されます。

Used in は、次の参照を確認します。

• 画像フィールドとファイルフィールド
• リピーター内の画像フィールド
• blocks フィールド内の画像、ファイル、Portable Text フィールド
• Portable Text フィールド内の画像ブロック、ギャラリーブロック、動画ブロック
• サイトのロゴ、favicon、デフォルトのソーシャル画像

使用状況の対象範囲が完全で、ファイルにこれらの参照が 1 つもない場合、一覧には No tracked references found と表示されます。対象範囲が完全になるまでは、空の一覧に No usage to show yet と表示されます。

コンテンツの結果が完全になるには、メディア使用状況の追跡が有効になっている必要があります。サイト設定は、追跡が有効かどうかにかかわらず一覧表示されます。管理者は、サイトに対して追跡を一度だけ有効にします。

有効にした後は、メディア使用状況の追跡を無効にすることはできません。新しいコンテンツの変更は、キャプチャが有効になった後に追跡されます。バックグラウンドのスキャンが、すでに存在していたエントリからの参照を追加します。

Used in ビューが、インデックス作成が実行中、古い、部分的、または失敗していると報告した場合は、その結果を不完全なものとして扱ってください。管理者は Media usage tracking に戻って、現在のステータスと復旧のガイダンスを確認できます。

テンプレートで画像をレンダリングする

画像フィールドは、単純な URL ではなくメディアの値を返します。emdash/ui の Image でその値をレンダリングすると、ローカルの画像もプロバイダーが提供する画像も、適切な URL、サイズ、フォーカルポイント、レスポンシブバリアント、低品質プレースホルダーを使用します。

---
import { getEmDashEntry } from "emdash";
import { Image } from "emdash/ui";

const { entry: post, error } = await getEmDashEntry("posts", Astro.params.slug);
if (error) return new Response("Unable to load post", { status: 500 });
if (!post) return Astro.rewrite("/404");
---

{post.data.featured_image && (
  <Image image={post.data.featured_image} width={1200} height={675} priority />
)}

priority は、ページの上部に表示されるメインの画像にだけ使用してください。eager ローディングを要求し、ブラウザーに高い fetch 優先度のヒントを与えます。その他の画像では、コンポーネントのデフォルトである遅延読み込みを維持してください。

フィールドにダークモード用の画像がある場合、Image は両方のソースをレンダリングし、訪問者のカラースキームに応じて一方を選択します。フィールドとテンプレートの設定については、ダーク画像バリアントを参照してください。

テンプレートは、コンテンツの参照とともに保存されているメディアのメタデータを、メディアライブラリへ改めて問い合わせることなく受け取ります。カスタムインテグレーションでプロバイダーの最新のメタデータが必要な場合は、そのアイテムを明示的にリクエストし、コレクションのページで画像ごとにプロバイダーへ問い合わせるのは避けてください。保存されるファイルと画像の値については、フィールドタイプのリファレンスで説明しています。

テンプレートでファイルをレンダリングする

メディアライブラリのファイルフィールドの値には、すぐに使える URL は含まれません。その meta.storageKey を Astro.locals.emdash.getPublicMediaUrl() に渡します。この関数は公開 URL を返し、メディアテーブルを問い合わせずに、設定済みの R2 または S3 の公開ドメインを反映します。ストレージキーを持たない古い値では URL は url に保持され、URL で追加されたファイル（provider: "external" で保存）では src に保持されます。

Cloudflare Stream など、登録済みのメディアプロバイダーのファイルでは、src にはファイル自体ではなくプレビュー画像が入っているため、この方法は使えません。

次のページは、video ファイルフィールドに保存された動画をレンダリングします。

---
import { getEmDashEntry } from "emdash";

const { entry, error } = await getEmDashEntry("videos", Astro.params.slug);
if (error) return new Response("Unable to load video", { status: 500 });
if (!entry) return Astro.rewrite("/404");

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

{url && <video src={url} controls preload="metadata" />}

同じ URL は、ダウンロードリンクや、ファイルのアドレスを必要とするその他の要素にも使えます。値に含まれるファイル名、MIME タイプ、サイズは、ファイルを選択した時点で保存されたものです。

ストレージとプロバイダーを設定する

ローカルライブラリは、サイトに設定されたストレージアダプター経由でファイルを保存します。Node.js のサイトではローカルディスクまたは S3 互換のストレージを使用でき、Cloudflare のサイトでは一般に R2 バインディングを使用します。バイトデータをどこに保存するかはアダプターが決め、メディアライブラリでは同じ作成ワークフローが保たれます。設定と本番環境での永続化の要件については、メディアストレージの選択を参照してください。

Cloudflare Images と Cloudflare Stream は、外部のメディアプロバイダーとして登録できます。これらはピッカーにソースとして表示され、Image はプロバイダーが提供する画像の値を理解します。プロバイダーのアイテムはそのサービスが引き続き管理するため、EmDash のアセットエディターでは、これらのアイテムに対してローカルフォルダー、フォーカルポイント、切り抜き、置き換えは利用できません。

メディアを安全に削除する

メディアライブラリでファイルを開き、Delete を選択して、完全な削除を確定します。作成者は自分がアップロードしたローカルファイルを削除でき、編集者はすべてのローカルファイルを削除できます。プロバイダーのアイテムは、そのソースが削除機能を公開していて、現在のユーザーに権限がある場合にのみ、プロバイダーから削除されます。

自動化されたアップロードやメディア管理については、メディアエンドポイントのリファレンスまたは CLI のメディアコマンドを参照してください。選択したメディアを使用するエントリを公開するには、コンテンツの操作に進んでください。