Crop API
画像クロップのストレージとAPIを提供します。このモジュールは、UIモジュールが画像クロッピング機能を提供するために使用できる基盤となるエンティティ構造とAPIを定義します。
crop
インストール
composer require 'drupal/crop:8.x-2.5'
composer require 'drupal/crop:8.x-2.2'
概要
Crop APIモジュールは、Drupalにおける画像クロッピングの基盤APIを提供します。画像のクロッピング情報（位置、サイズ、アンカー座標）を保存する「Crop」というコンテンツエンティティタイプと、オプションのアスペクト比制約やサイズ制限を持つ異なるタイプのクロップを定義する「Crop Type」という設定エンティティタイプを確立します。
このモジュールはAPIレイヤーとして設計されており、単独ではユーザー向けのクロッピングインターフェースを提供しません。代わりに、Image Widget CropやFocal PointなどのUIモジュールが完全なクロッピングソリューションを提供するために利用できるデータストレージ、サービス、フックを提供します。
このモジュールには、画像派生物を生成する際に保存されたクロップデータを適用するために画像スタイルに追加できる「Manual crop」画像エフェクトが含まれています。また、画像を含む異なるエンティティタイプ（File、Media）との統合を可能にするエンティティプロバイダー用の拡張可能なプラグインシステムも提供します。
主要なアーキテクチャ機能には、クロップデータ変更時の画像派生物の自動フラッシュ、ハッシュパラメータによるURLベースのキャッシュ無効化、イベントシステムを通じた自動クロッププロバイダーのサポート、コンテンツステージングシナリオ向けのDrupalのデフォルトコンテンツエクスポーターとの統合が含まれます。
Features
- 位置（x、y中心座標）、サイズ（幅、高さ）、アンカー（左上角）、およびソースエンティティへの参照を持つ画像クロップデータを保存するための「Crop」コンテンツエンティティタイプを定義
- オプションのアスペクト比（例：16:9）、ソフトリミット（クロップが小さい場合に警告）、ハードリミット（最小クロップサイズ）を持つ異なるクロップタイプを作成するための「CropType」設定エンティティを定義
- 画像スタイルで使用するための「Manual crop」画像エフェクトプラグインを提供し、保存されたクロップデータを画像に適用
- FileおよびMediaエンティティを標準でサポートし、カスタムエンティティタイプ向けに拡張可能なプラグインベースのエンティティプロバイダーシステム
- 手動クロップが存在しない場合に他のモジュールがフォールバッククロッピングを提供できる自動クロッププロバイダー用のイベントシステム
- Cropエンティティが保存されたときに影響を受ける画像スタイル派生物の自動フラッシュ（設定で構成可能）
- クロップ変更時のキャッシュ無効化のためのURLハッシュパラメータ追加、CDN/プロキシキャッシュバスティングを有効化
- クロッピングに使用する画像フィールドを指定するためのMediaタイプ設定との統合
- Cropエンティティの適切なインポート/エクスポートのためのDrupal Coreのデフォルトコンテンツエクスポーター（Drupal 11以降）との統合
- 完全なリビジョン履歴追跡を備えたCropエンティティのリビジョンサポート
- 言語ごとに異なるクロップを許可するCropエンティティの翻訳サポート
- 効率的なクロップルックアップのためのuriおよびtypeフィールドのデータベースインデックス最適化
Use Cases
レスポンシブ画像クロッピング
サイト全体で必要な様々なアスペクト比に対して異なるクロップタイプを作成します（例：ヒーロー画像用の16:9、サムネイル用の1:1、記事画像用の4:3）。各クロップタイプ用にManual cropエフェクトで画像スタイルを設定します。UIモジュールを使用してコンテンツエディターが各画像のクロップを設定できるようにします。同じソース画像が異なる表示コンテキストで異なるクロップを持つことができます。
クロッピング付きメディアライブラリ
Mediaタイプを設定して、クロッピングに使用する画像フィールドを指定します。エディターがMediaアイテムを追加または編集するときに、そのMediaアイテムが表示される場所で一貫して適用されるクロップを定義できます。これにより、サイト全体でブランドの一貫性が確保されます。
デカップルド/ヘッドレスアーキテクチャ
CDN配信でクラウドストレージ（S3など）を使用するサイトでは、flush_derivative_imagesをfalseに設定して自動派生物フラッシュを無効にします。別のビルドプロセスを通じて画像派生物を生成し、クラウドストレージにプッシュします。Crop APIはキャッシュ無効化のためにURLにハッシュパラメータを追加し続けます。
自動フォールバッククロッピング
crop.automatic_cropイベントをサブスクライブして、エディターが手動クロップを設定していない場合に自動クロッピングを提供します。例えば、顔検出を使用してクロップを自動的に顔に中央揃えしたり、フォーカルポイントデータを使用して画像の重要な部分を保持するスマートクロップを作成したりします。
クロップ付きコンテンツステージング
Drupal 11のデフォルトコンテンツエクスポーターを使用する場合、Cropエンティティはエクスポート/インポート時に自動的に処理されます。クロップはソースエンティティへのUUID参照とともにエクスポートされ、インポート時に正しく再リンクされるため、コンテンツステージングワークフローがシームレスになります。
多言語画像クロッピング
Cropエンティティは翻訳可能なため、異なる言語に対して異なるクロップを定義できます。これは、異なる言語バージョンで異なるクロッピングが必要な画像（例：言語によって異なるテキストを含む画像）に便利です。
Tips
- Crop APIと一緒に必ずUIモジュール（Image Widget CropやFocal Pointなど）をインストールしてください - APIモジュール単独ではクロッピングインターフェースを提供しません
- ソフトリミットを使用して、エディターを最小品質のクロップに誘導しながら、必要に応じてより小さなクロップを許可します
- 厳守する必要がある厳格な最小サイズ要件がある場合はハードリミットを使用します
- アスペクト比設定はオプションです - 任意の比率が許容される自由形式のクロッピングには空のままにしてください
- クロップの問題をデバッグする場合は、crop_field_dataデータベーステーブルを確認して、Cropエンティティが正しい値で作成されているかを確認してください
- 「フラッシュ」操作は慎重に使用してください - クロップタイプのすべてのクロップデータを完全に削除します
- 多数のクロップでのパフォーマンス向上のため、モジュールは（uri、type）カラムにデータベースインデックスを作成します
Technical Details
Admin Pages 5
/admin/config/media/crop
システムで設定されているすべてのクロップタイプを一覧表示します。各クロップタイプの名前、説明、アスペクト比、およびどの画像スタイルが使用しているかを表示します。各タイプを編集、削除、またはクロップをフラッシュする操作を提供します。
/admin/config/media/crop/add
設定可能な名前、マシン名、説明、アスペクト比、サイズ制限を持つ新しいクロップタイプを作成するフォーム。
/admin/config/media/crop/manage/{crop_type}
既存のクロップタイプの設定を変更するフォーム。マシン名は作成後に変更できません。
/admin/config/media/crop/manage/{crop_type}/delete
クロップタイプを削除するための確認フォーム。クロップタイプを使用しているCropエンティティがない場合にのみ削除できます。
/admin/config/media/crop/manage/{crop_type}/flush
特定のクロップタイプのすべてのCropエンティティを削除するための確認フォーム。タイプ定義自体を削除せずに特定のタイプのすべてのクロップデータを削除したい場合に便利です。
権限 2
Hooks 1
hook_crop_entity_provider_info_alter
モジュールがCropEntityProviderプラグインによって提供される情報を変更できるようにします。エンティティプロバイダープラグインのラベル、説明、その他のプロパティを変更するために使用できます。
Troubleshooting 5
crop.settingsでflush_derivative_imagesがtrueに設定されていることを確認してください。すべてのキャッシュをクリアし、Cropエンティティが適切に保存されていることを確認してください。クラウドストレージ設定の場合は、派生物を手動で再生成する必要がある場合があります。
以下を確認してください：1）画像スタイルに正しいクロップタイプが選択された「Manual crop」エフェクトがあること、2）画像URIとクロップタイプに対するCropエンティティが存在すること、3）Cropエンティティに有効な位置とサイズの値があること。
まずMediaタイプにファイルまたは画像フィールドを追加してください。クロップ設定フィールドセットは、バンドルに有効なファイル/画像フィールドがある場合にのみ表示されます。
まずそのタイプのすべてのCropエンティティを削除またはフラッシュする必要があります。「フラッシュ」操作を使用してすべてのクロップを削除してから、タイプを削除してください。
アスペクト比が正の整数のみのW:H形式（例：16:9、4:3、1:1）であることを確認してください。小数、パーセンテージ、その他の形式は含めないでください。
Security Notes 3
- モジュールはCropエンティティをクエリする際にアクセスチェックを使用します
- エンティティプロバイダープラグインはURIを返す前にエンティティタイプとフィールド値を検証する必要があります
- クロップデータはURIごとに保存され、uriフィールドを通じてファイルシステム構造が露出する可能性があります