Image Widget Crop
画像フィールドでCrop APIを使用するためのインターフェースを提供し、異なるクロップタイプに対して画像ごとに複数のクロップゾーンを定義できるようにします。
image_widget_crop
インストール
composer require 'drupal/image_widget_crop:^3.0'
composer require 'drupal/image_widget_crop:8.x-2.4'
概要
Image Widget Cropは、Crop APIを使用して画像フィールドにクロップを適用するためのユーザーエクスペリエンスを提供します。このモジュールはDrupalの画像システムと統合され、エディターが異なるクロップタイプ（アスペクト比）に基づいて各画像の最適なクロップゾーンを定義できるようにします。
このモジュールは、同じ画像を異なるアスペクト比で異なるコンテキストに表示する必要がある編集サイトやメディア管理システムに特に有用です。例えば、記事にはワイドなヒーロー画像、正方形のサムネイル、縦長のサイドバー画像が必要な場合がありますが、これらすべてを同じソースファイルから作成できます。
主な機能には、画像ごとの複数クロップタイプのサポート、Cropper.jsライブラリを使用したリアルタイムビジュアルクロッピングインターフェース、アスペクト比の強制、ハードリミットとソフトリミットの検証、必須クロップタイプの検証、File Entity、Entity Browser、IMCE、その他のメディア管理モジュールとの統合が含まれます。
Features
- 異なるアスペクト比をサポートする画像ごとの複数クロップタイプ
- Cropper.jsライブラリを使用したリアルタイムプレビュー付きビジュアルクロッピングインターフェース
- クロップタイプ設定に基づく自動アスペクト比強制
- 最小クロップ寸法に対するハードリミットとソフトリミットの検証
- エディターが必要なクロップを定義することを保証する必須クロップタイプの検証
- ファイル編集フォームから直接画像をクロップするためのFile Entityとの統合
- Entity Browser、IMCE、FileField Sourcesモジュールのサポート
- 柔軟なライブラリ読み込み：ローカルファイル、Libraries API、またはCDNフォールバック
- クロップの適用と更新操作に対する通知システム
- 画像が複数の場所で使用されている場合の警告システム
- カスタムフォーム統合用のForm API要素（image_crop）
- 複数クロップタイプを管理するための縦タブインターフェース
Use Cases
複数の画像配置を持つ編集サイト
記事がホームページ（ワイドバナー）、カテゴリページ（中サイズの正方形）、サイドバー（小さな縦長）、記事ページ（全幅）に表示されるニュースサイト向け。各比率（16:9、1:1、3:4など）のクロップタイプを作成し、Manual cropエフェクトで画像スタイルを設定すれば、エディターは画像をアップロードする際に各配置に最適なクロップゾーンを定義できます。
ECサイトの商品画像
商品画像はカタロググリッド、商品詳細ページ、ズームビュー用に一貫したクロッピングが必要です。各表示コンテキスト用のクロップタイプを設定し、すべての商品が適切にクロップされたサムネイルを持つようにカタログクロップタイプを必須にします。
再利用可能なアセットを持つメディアライブラリ
ファイルエンティティを持つMediaモジュールを使用して、エディターはメディアライブラリで一度画像をクロップし、コンテンツ全体で再利用できます。warn_multiple_usagesオプションは、複数のコンテンツアイテムに影響するクロップを変更する際にエディターに警告します。
クロッピング付きのカスタムフォーム
image_crop Form API要素を使用してカスタムフォームにクロッピングを追加します。ファイルエンティティを読み込み、クロップタイプとプレビュースタイルを設定し、フォーム送信時にimage_widget_crop.managerサービス経由でクロップを処理します。
アートディレクション付きレスポンシブ画像
アートディレクションされたレスポンシブ画像のためにResponsive Imageモジュールと組み合わせます。異なるクロップタイプにより、さまざまなビューポートサイズに最適なフォーカスポイントを定義でき、すべてのブレークポイントで重要なコンテンツが表示されるようにします。
Tips
- クロッププレビューにはアスペクト比を維持して画像全体を表示するために、Scale（Scale and Cropではなく）を使用した画像スタイルを使用してください
- 各ユースケースの最小画像品質を確保するために、クロップタイプに適切なハードリミットを設定してください
- ファイルが再利用される可能性のあるメディアライブラリでは「ファイルが複数使用されている場合にユーザーに警告」を有効にしてください
- 本番フィールドを設定する前にimage_widget_crop_examplesサブモジュールを使用して機能をテストしてください
- CDNフォールバックは追加設定なしで動作します - 基本的な使用にはライブラリのインストールは不要です
- そのフィールドの画像が表示される場所に基づいて、フィールドごとに異なるクロップタイプを設定してください
Technical Details
Admin Pages 1
/admin/config/media/crop-widget
Cropperライブラリのソース、デフォルトのクロッププレビュースタイル、利用可能なクロップタイプ、通知設定を含むImage Widget Cropモジュールのグローバル設定を構成します。
Hooks 7
hook_entity_insert
画像フィールドを持つエンティティが作成されたときにクロップデータを自動的に処理します
hook_entity_update
画像フィールドを持つエンティティが更新されたときにクロップデータを自動的に処理します
hook_form_file_form_alter
画像ファイル用のファイルエンティティ編集フォームにimage_crop要素を追加します
hook_library_info_alter
モジュール設定に基づいてCropperライブラリのソースを動的に設定します（カスタムURL、Libraries API、またはCDN）
hook_libraries_info
Libraries APIモジュール統合用のCropperライブラリを定義します
hook_filefield_sources_widgets
FileField Sourcesモジュールとの互換性のためにimage_widget_cropウィジェットを登録します
hook_imce_supported_widgets_alter
IMCEモジュールがサポートするウィジェットのリストにimage_widget_cropを追加します
Troubleshooting 5
クロップタイプは、少なくとも1つのImage Styleが「Manual crop」エフェクトで使用している場合にのみ表示されます。/admin/config/media/image-stylesに移動し、スタイルを編集または作成して、クロップタイプを選択した「Manual crop」エフェクトを追加してください。
/admin/config/media/crop-widgetの設定を確認してください。カスタムURLがアクセス可能であることを確認するか、Librariesモジュールが有効で/libraries/cropper/dist/にcropperがあることを確認してください。ローカルライブラリが見つからない場合、モジュールはCDNにフォールバックします。
フォーム表示設定で画像フィールドウィジェットが「ImageWidget crop」に設定されていることを確認してください。ウィジェット設定でクロップタイプが選択されていることを確認してください。エンティティでhook_entity_insert/updateがトリガーされていることを確認してください。
クロップエリアがクロップタイプのハードリミット最小寸法より小さいです。より大きなエリアをクロップするか、/admin/config/media/cropのクロップタイプ設定でハードリミット値を減らしてください。
ウィジェット設定で「ファイルが複数使用されている場合にユーザーに警告」を有効にしてください。メディアエンティティを使用する場合、共有クロップを避けるために各メディアアイテムは一意のファイルを参照する必要があります。
Security Notes 3
- モジュールは既存のDrupalパーミッションに依存します - 設定ページには「administer site configuration」が必要
- クロップデータはファイルごとに保存されるため、ファイルにアクセスできるユーザーは、ファイルが共有されている場合、所有していないコンテンツのクロップに影響を与える可能性があります
- 共有メディアライブラリを使用する場合は、ファイルの所有権とアクセスパターンを考慮してください