SVG Formatter
FileフィールドやImageフィールドを通じてDrupalウェブサイト上でSVG画像を表示できるField Formatterを提供します。
svg_formatter
インストール
composer require 'drupal/svg_formatter:^2.0'
composer require 'drupal/svg_formatter:8.x-1.18'
概要
SVG Formatterモジュールは、Drupalの標準的なImageフィールドがSVG（Scalable Vector Graphics）画像をネイティブでサポートしていないという基本的な制限に対処します。このモジュールは、FileフィールドまたはImageフィールド（SVG Imageモジュールと併用時）に適用できる専用のField Formatterを提供し、SVGファイルをウェブサイト上に表示できるようにします。
このモジュールは2つの出力モードを提供します：<img>要素を使用した標準的な画像タグ出力、またはSVGマークアップをHTMLに直接埋め込むインラインSVG出力です。インラインモードは、アニメーション、インタラクティブなグラフィックス、動的な色変更など、CSSやJavaScriptでSVGを操作する必要がある場合に特に便利です。
主要なセキュリティ機能として、enshrined/svg-sanitizeライブラリとの統合があり、インラインSVGコンテンツをサニタイズしてXSS（クロスサイトスクリプティング）攻撃を防止します。悪意のあるSVGにはJavaScriptコードが埋め込まれている可能性があるため、ユーザーにSVGファイルのアップロードを許可する際にこれは重要です。また、このモジュールは設定可能なサイズ、代替テキスト、動的な値のためのToken統合を備えたtitle属性もサポートしています。
Features
- FileおよびImageフィールドタイプ用のSVG Formatter Field Formatterを提供
- SVGグラフィックスのCSSおよびJavaScript操作のためのインラインSVG出力モード
- 悪意のあるSVGアップロードからのXSS攻撃を防止するenshrined/svg-sanitizeライブラリを使用したSVGサニタイズ
- インラインSVG要素とimgタグの両方に適用できる設定可能な画像サイズ（幅と高さ）
- ファイル名からの自動生成またはカスタムTokenベースの値による代替テキスト属性サポート
- アクセシビリティのためのtitle属性サポート、インラインSVGにはaria-labelledbyを自動追加
- Entityフィールドに基づく動的なaltおよびtitle値のためのToken統合（Tokenモジュールが必要）
- image/svg+xml MIMEタイプのファイルのみを処理する自動フィルタリング
- FileフィールドとImageフィールドの両方に対応（ImageフィールドにはSVG Imageモジュールが必要）
Use Cases
CSSカスタマイズを伴うロゴとアイコンの表示
テーマやユーザーインタラクションに基づいて色を変更する必要があるブランドロゴやアイコンを表示するには、インラインSVGモードを使用します。インラインSVGでは、CSSセレクタでSVG要素をターゲットにして、塗りつぶしの色、線の太さを変更したり、ホバーエフェクトを適用したりできます。
レスポンシブなベクターグラフィックス
イラスト、図表、インフォグラフィックを、どの解像度でも完璧にスケールするSVG画像として表示します。Formatterでサイズを設定するか、完全にレスポンシブな動作のためにCSSで制御できるようにします。
アクセシブルなアイコンセット
altおよびtitle属性を有効にして、アクセシブルなアイコンセットを作成します。Tokenを使用してコンテンツに基づいた説明テキストを動的に生成し、スクリーンリーダーが画像を適切に説明できるようにします。
セキュリティを確保したユーザーアップロードSVGコンテンツ
XSS攻撃から保護しながら、コンテンツエディターやサイトユーザーがSVG画像をアップロードできるようにします。サニタイズオプションを有効にして、アップロードされたSVGから潜在的に悪意のあるスクリプトやイベントハンドラを自動的に除去します。
インタラクティブなデータビジュアライゼーション
JavaScriptで操作可能なチャート、グラフ、インタラクティブな地図を表示するには、インラインSVGモードを使用します。インラインモードはSVG DOM要素を公開し、D3.jsなどのライブラリがグラフィックスと連携できるようにします。
Tips
- 最適なCSS操作のためには、インラインSVGモードを使用し、スタイルを適用したい要素にクラスまたはIDが設定されていることを確認してください。
- Tokenモジュール統合により、親Entityに基づく動的なaltおよびtitleテキストに[node:title]や[file:name]などのTokenを使用できます。
- カスタムTokenが指定されていない場合、altテキストはファイル名から自動生成されます - 「my-icon.svg」は「My icon」になります。
- アクセシビリティのため、titleが有効なインラインSVGには、title要素にリンクするaria-labelledby属性が自動的に含まれます。
- Formatterは複数値フィールドで非SVGファイルを自動的にスキップするため、同じフィールドでSVGと他のファイルタイプを混在させることができます。
Technical Details
Hooks 2
hook_help
ヘルプページにモジュールのドキュメントを提供するためにhook_helpを実装します。
hook_theme
変数を持つsvg_formatter Theme hookを登録するためにhook_themeを実装します。
Troubleshooting 5
SVG Imageモジュール（drupal/svg_image）をインストールしてください。DrupalのコアImageフィールドはデフォルトでSVGアップロードをサポートしていないため、FormatterはSVG Imageモジュールがインストールされている場合のみImageフィールドに表示されます。
enshrined/svg-sanitizeライブラリがインストールされていることを確認してください。不足している場合は「composer require enshrined/svg-sanitize」を実行してください。ライブラリが見つからない場合、サニタイズチェックボックスは無効になります。
Tokenサポートのため、Tokenモジュールをインストールして有効にしてください。このモジュールはFormatter設定にTokenブラウザを提供し、Entityタイプに有効なTokenを選択するのに役立ちます。
Formatter設定で「画像サイズを設定」が有効になっていることを確認してください。インラインSVGの場合、サイズはSVGルート要素の属性として設定されます。一部のSVGは内部CSSでこれをオーバーライドする場合があります - SVGソースを確認してください。
SVGファイルに無効なXMLまたはエンコーディングの問題がある可能性があります。SVGが有効なXMLであり、UTF-8エンコーディングを使用していることを確認してください。モジュールはSVGの解析にDOMDocumentを使用しており、整形式のXMLが必要です。
Security Notes 4
- enshrined/svg-sanitizeライブラリが含まれることを確認するため、必ずComposerを使用してモジュールをインストールしてください。このライブラリがないと、インラインSVGはサニタイズされず、サイトがXSS脆弱性にさらされる可能性があります。
- 信頼できないユーザーにSVGファイルのアップロードを許可する場合は、SVGファイルに埋め込まれた潜在的に悪意のあるJavaScriptコードを除去するため、常に「インラインSVGをサニタイズ」オプションを有効にしてください。
- サニタイズライブラリは、インラインモード使用時にSVGファイルからscriptタグ、イベントハンドラ、その他の潜在的に危険な要素を除去します。
- 非インラインモード（imgタグ）を使用する場合、SVGは外部リソースとして扱われ、ブラウザのセキュリティがスクリプト実行を防止するため、サニタイズの重要性は低くなりますが、多層防御のために推奨されます。