DropzoneJS
DropzoneJSライブラリのDrupal統合モジュール。画像プレビュー付きのドラッグ＆ドロップファイルアップロード機能を提供します。
dropzonejs
インストール
composer require 'drupal/dropzonejs:8.x-2.11'
概要
DropzoneJSは、人気のあるDropzoneJS JavaScriptライブラリとの統合を提供するDrupalモジュールで、Drupalサイト全体でモダンなドラッグ＆ドロップファイルアップロード機能を実現します。このモジュールは、ファイルアップロードが必要なDrupalのあらゆる場所で使用できるカスタムフォーム要素を提供します。
このモジュールは、画像、動画、音声、ファイルのメディアソースに対して、Media Libraryのデフォルトアップロードフォームを自動的に置き換え、シームレスなドラッグ＆ドロップ体験を提供します。複数ファイルのアップロード、ファイルサイズの検証、許可されたファイル拡張子のフィルタリングをサポートし、画像プレビュー付きでアップロードの進捗を表示します。
追加機能として、アップロード前のクライアントサイドでの画像リサイズ（exif-jsライブラリを使用、オプション）、セキュリティのためのファイル名の音訳とサニタイズ、大きなファイルのチャンクアップロードがあります。また、Entity Browser統合用のサブモジュールも提供しており、Entity Browserウィジェット内でDropzoneJSアップローダーを使用してファイルやメディアエンティティの選択とアップロードが可能です。
Features
- 視覚的フィードバックと進捗インジケーター付きのドラッグ＆ドロップファイルアップロードインターフェース
- 画像、動画、音声、ファイルのメディアタイプに対するDrupalのMedia Libraryとの自動統合
- 任意のDrupalフォームで使用できるカスタム「dropzonejs」フォーム要素
- アップロード前のクライアントサイド画像リサイズ（オプション、exif-jsライブラリが必要）
- 最大ファイルサイズ、許可する拡張子、最大ファイル数を含む設定可能なアップロード設定
- セキュリティを確保するためのアップロードファイルのファイル名サニタイズと音訳
- 視覚的な削除アイコンによるフォーム送信前のアップロード済みファイルの削除
- セキュリティのためのアップロードエンドポイントでのCSRF保護
- Dropzone 5とDropzone 6の両方のライブラリバージョンをサポート
- アップロード中のメディアエンティティ作成に他のモジュールが反応できるイベントシステム
Use Cases
Media Libraryでのファイルアップロード
サイトビルダーは、コンテンツエディターにMedia Libraryでの直感的なドラッグ＆ドロップファイルアップロード体験を提供したいと考えています。DropzoneJSをインストールすると、エディターはファイルブラウザダイアログをクリックする代わりに、単純にファイルをアップロードエリアにドラッグできます。複数のファイルを一度にドロップでき、アップロードの進捗がリアルタイムで表示されます。
カスタムフォームでのファイルアップロード
カスタムフォームを構築する開発者は、「dropzonejs」フォーム要素タイプを使用してドラッグ＆ドロップファイルアップロードを追加できます。#max_filesize、#extensions、#max_filesなどのプロパティを設定してアップロード動作を制御します。この要素は、フォーム送信ハンドラーで処理できる一時ファイルパスの配列を返します。
Entity Browserでのメディア選択
メディア選択にEntity Browserを使用しているサイトは、dropzonejs_eb_widgetサブモジュールを有効にしてDropzoneJSを使用したアップロードウィジェットを提供できます。基本ファイルアップロード、自動メディアエンティティ作成、または即座にフィールドを入力できるインライン編集付きメディアエンティティ作成から選択できます。
クライアントサイドでの画像最適化
サーバー帯域幅を削減しアップロードを高速化するには、exif-jsライブラリをインストールし、DropzoneJS要素でクライアントサイドリサイズを有効にします。画像はアップロード前にブラウザでリサイズされ、EXIFデータから正しい向きが維持されます。最大幅、高さ、品質、リサイズ方法を設定できます。
大量の画像アップロード
写真サイトやギャラリーでは、多くの画像を素早くアップロードする必要があります。DropzoneJSでは、画像フォルダ全体をドラッグし、サムネイルをプレビューとして表示し、アップロードを並列処理できます。Entity Browserウィジェットの自動選択機能により、アップロード完了時にファイルを自動的に保存して選択できます。
Tips
- アップロード機能を使用する必要がある認証済みユーザーまたは特定のロールに「Dropzone upload files」権限を付与してください
- upload_location設定でトークン置換を使用して（例：public://[date:custom:Y]-[date:custom:m]）、日付ごとにファイルを整理できます
- Entity Browserサブモジュールでは、「Inherit settings from the media type」を有効にすると、ファイルフィールドの設定から最大サイズと許可される拡張子を自動的に使用します
- dropzone要素は#max_filesを0に設定すると無制限のファイルアップロードが可能で、正の整数を設定するとアップロード数を制限できます
- 帯域幅の使用を削減し、大きな画像のアップロード速度を向上させるために、画像アップロードのクライアントサイドリサイズを有効にすることを検討してください
Technical Details
権限 1
Hooks 1
hook_media_source_info_alter
画像、video_file、audio_file、ファイルのメディアソースに対して、デフォルトのMedia Library追加フォームをDropzoneJSバージョンに置き換えるためにモジュール内部で使用されます。
Troubleshooting 5
DropzoneJSライブラリがlibraries/dropzoneフォルダにインストールされていることを確認してください。モジュールはいくつかの場所でdropzone-min.jsまたはdropzone.min.jsを探します。GitHubからライブラリのdist.zipをダウンロードし、正しく展開してください。
ユーザーに「Dropzone upload files」権限があることを確認してください。この権限がないと、dropzone要素にアクセスできず、アップロードはサイレントに失敗します。
libraries/exif-js/exif.jsにexif-jsライブラリをインストールしてください。このライブラリはクライアントサイドリサイズ機能に必要です。これがないと、ウィジェット設定でclientside_resizeオプションが無効になります。
PHPのupload_max_filesizeとpost_max_sizeの設定を確認してください。モジュールはこれらの制限を尊重します。また、アップロードがタイムアウトする場合はupload_timeout_ms設定も確認してください。
モジュールはセキュリティのためにファイル名をサニタイズします。Drupal 10.2以降を使用している場合は、コア設定でファイル名のサニタイズを設定してください。レガシーのfilename_transliteration設定は非推奨であり、将来のバージョンで削除されます。
Security Notes 5
- すべてのアップロードは、クロスサイトリクエストフォージェリ攻撃から保護するためにCSRFトークン検証が必要です
- 実行可能なファイル拡張子（php、pl、py、cgi、asp、js）は、コード実行を防ぐために自動的に.txt拡張子にリネームされます
- ファイルはセキュリティのため、最初は.txt拡張子が追加された状態でアップロードされ、検証後にのみ削除されます
- アップロードエンドポイントは「dropzone upload files」権限を必要とし、認可されたユーザーのみがファイルをアップロードできることを保証します
- ファイル検証には、拡張子チェック、ファイルサイズ制限、ファイル名の長さ検証が含まれます