.NET MAUIでSVGを使う：SVGを保持しPNG名を参照する

.NET MAUIのバンドル画像の仕組みでSVGを使うには、プロジェクト内にSVGを保持し、XAMLやC#から生成されたPNG名を参照します。MAUIはビルド時にベクターの元データを処理します。そのため、追加したファイルがcompass.svgでも、compass.pngを指すImageは正しい指定になり得ます。この変換はMicrosoftのプロジェクト画像ガイドに記載されています。

ファイル名の理由は分かりましたが、どのサイズで生成し、その後何を確認すべきかというデザイン上の疑問が残ります。小さなコンパスの紋章を例に、元データ、プロジェクトのメタデータ、表示宣言を順に追います。

元データからビルドまでを追う

編集可能なSVGとパッケージに含める画像は、役割が異なります。形、余白、色を後から調整できるように元データを保持し、表示するビューでは生成された名前を使います。

Imageコントロールの資料では、対象の画素密度に対応する画像がアプリのパッケージに入り、OSが適切な解像度を選ぶ仕組みを説明しています。SVGマスターを保持していても、このワークフローでビューにSVG文書そのものが渡されるわけではありません。

描画範囲が明確な小さなSVGを追加する

この独自の例をResources/Images/compass.svgとして保存します。

<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96">
  <circle cx="48" cy="48" r="34" fill="none" stroke="#173e52" stroke-width="8"/>
  <path d="M58 28L52 52L28 58Z" fill="#ed765e"/>
</svg>

リングの中央は透明で、サンゴ色の針は別の図形です。これらはインポート後に確認する具体的な箇所になります。宣言した寸法と正方形のviewBoxも、意図した構図を明確にします。ベクター形状と、SVGの外枠内に埋め込んだビットマップの違いについては、SVGファイルのガイドを参照してください。

プロジェクトで、ファイルのビルドアクションがMauiImageになっていることを確認します。Microsoftは通常の配置場所としてResources/Imagesを案内しています。XMLを追加する前に既存のプロジェクト項目を確認してください。ワイルドカードですでにそのフォルダーを含めている場合があります。プロジェクト画像の設定に配置とビルドアクションの説明があります。

既存の項目を一度更新する

既存のMauiImageワイルドカードがコンパスのファイルを含めている場合は、その宣言の後に次のメタデータ更新を置きます。

<ItemGroup>
  <MauiImage Update="Resources\Images\compass.svg" BaseSize="48,48" />
</ItemGroup>

Updateは既存の項目のメタデータを変更します。項目リストにないファイルを追加する処理ではありません。一致する取り込み宣言がなければ、MauiImageビルドアクションか明示的なIncludeで一度だけ追加します。MicrosoftのMSBuild Itemリファレンスは、これらの操作を区別しています。

こうすれば、画像が見つからない原因を調べる際にIncludeを何度も追加するという、つい行いがちな修正を避けられます。まずファイルが含まれているかを確かめ、それからメタデータを変更します。

PNGを参照し表示領域を設定する

既存のMAUIページやレイアウト内に次の宣言を置きます。

<Image Source="compass.png"
       WidthRequest="48"
       HeightRequest="48"
       Aspect="AspectFit"
       SemanticProperties.Description="Compass" />

.png拡張子は意図的な指定です。幅と高さは正方形の表示領域を要求し、AspectFitは画像全体をその中に収めます。長方形のイラストなら、正方形いっぱいに引き伸ばすのではなく、形に合う表示領域を使ってください。Microsoftの画像の拡大縮小リファレンスでは、全体を収める、切り抜く、引き伸ばす動作を区別しています。

コンパスのコードは独自の設定例で、端末での描画テストを記録したものではありません。実際の対象プロジェクトでビルドし、結果のビューを確認してください。ファイル名が正しいだけでは、アートワークが意図どおりに描画されると判断できません。

BaseSizeとレイアウトサイズの役割は異なる

BaseSize="48,48"は、MAUIが画素密度ごとの画像を生成するための基準寸法を指定します。明示的な基準サイズがなければ、SVG自体の寸法が使われます。両方の規則はMicrosoftの画像のサイズ変更に記載されています。

この例では、元の描画は96×96の座標空間を使い、指定した基準サイズとビューは48×48です。これらは意図的に選んだ制作上の値であり、ビルド出力から測定した寸法ではありません。縮小してもリングの縦横比は保持されるはずです。

後で同じ紋章を大きなビューで使う場合は、ビルドサイズを見直し、その用途でも確認してください。WidthRequestを変更しても元のアートワークやビルドのメタデータは変わりません。逆に、BaseSizeを変更してもSVG内の空白の余白は消えません。ビュー自体のサイズは正しいのに紋章が小さく見える場合は、元データの描画範囲を詰めます。

鮮明さを改善する万能な設定としてResize="false"を使わないでください。この処理系ではベクター画像のサイズ変更を無効にします。サイズ変更オプションの資料に従い、その動作が必要な場合だけ選びます。

画像がない、または想定と異なる場合の確認順序

1. ファイル名とプロジェクト項目を確認します。compass.svgのような小文字の名前を使い、同名の画像がないか調べます。Microsoftの命名規則では、画像名の一意性とAndroidで使用できる文字が求められます。
2. ビューの参照元を確認します。バンドルSVGのワークフローでは、XAMLやC#にcompass.pngを指定します。
3. 意図した表示領域と基準サイズを比較します。ビューサイズとビルドサイズは、変更する場所が異なります。
4. アートワーク自体を確認します。リングの中央は開いていますか。サンゴ色の針を見分けられますか。紋章は中央にありますか。それとも見えない元データの余白で片側に寄っていますか。

塗りを変える画像メタデータも確認します。プロジェクト画像ガイドには、色付け用のTintColorと背景色用のColorが記載されています。この2色の例では、外観を変える意図がなければ両方とも未設定にします。透明な穴が失われた場合に気付きやすいよう、実際のページ背景で画像を確認してください。

実行時にSVGの動作が必要な場合

ダウンロードしたSVG、操作可能なパス、実行時の編集には、別の実装判断が必要です。上記のバンドル画像の手順は、これらの用途への対応を保証しません。

たとえばVapoliaのSVGサンプルプロジェクトでは、独自のSvgImage、SvgImageSourceコントロールと埋め込みリソースの設定を説明しています。読み込みの仕組みは別です。導入前に、実際のファイルを使ってレンダラーの対応機能と対象プラットフォームを評価してください。通常のImage宣言で拡張子を変えるだけでは、レンダラーは導入されません。

同じアートワークでも、FlutterのSVG画像ワークフロー、SwiftUIのアセットカタログ、Android VectorDrawableへのインポートでは設定が異なります。元のマスターを再利用し、各出力先の規則に従ってください。

PNGしか残っていない場合にベクターマスターを準備する

コンパスやロゴがPNGでしか存在しない場合は、MAUIプロジェクトに追加する前にPerfectVectorで編集可能なSVGを作成できます。PNGをSVGに変換し、エディターでリングの穴、小さな離れた部品、間隔を確認します。後でサイズや色を変えられるよう、整理したマスターを保持します。

ベクター化はMauiImageの宣言を修復せず、バンドル画像の処理を実行時SVGパーサーに変えるものでもありません。すでに編集可能なSVGなら、プロジェクト設定や描画を直接修正します。写真や質感のある画像はラスターの方が有用な場合があります。アプリがSVGの元データを受け付けるという理由だけでトレースするかどうかは、アートワークとして別途判断する必要があります。

よくある質問

SVGを追加したのにPNGを参照するのはなぜですか？ .NET MAUIはバンドルするSVG画像をビルド時にPNGへ変換します。プロジェクトにはSVGを保持し、XAMLやC#ではPNGファイル名を参照します。

BaseSizeはImageコントロールのサイズを設定しますか？ BaseSizeは画素密度ごとのビルド画像を生成する基準寸法を設定します。表示領域はビューのレイアウトとサイズ要求で制御します。

BaseSizeを変えるためにMauiImage Includeをもう一つ追加すべきですか？ ワイルドカードを含め、ファイルがすでに含まれているか確認します。既存の項目のメタデータ変更にはUpdateを使い、項目の追加が必要な場合だけIncludeを使います。

アプリのビルド後にダウンロードしたSVGも読み込めますか？ バンドル画像のワークフローは、実行時のSVGのダウンロードや解析を扱いません。その要件に合う実行時の描画方法を選び、テストしてください。

参考資料

1. Microsoft — .NET MAUIアプリプロジェクトへの画像の追加 — SVGからPNGへの処理、画像項目、ファイル名、基準サイズ、ビルドメタデータ。
2. Microsoft — Image — ローカル画像の参照、対象の画素密度の選択、ビューサイズ、拡大縮小の動作。
3. Microsoft — Item要素（MSBuild） — Includeによる項目の追加とUpdateによる既存メタデータの変更の違い。
4. Vapolia — SVGサンプル — 別の実行時SVGコントロールとリソース読み込みのワークフロー。

ラスターだけのアプリ紋章から作業していますか。PNGを編集可能なSVGに変換して穴と間隔を確認し、そのマスターをMAUIに追加して、対象アプリで生成画像を確認してください。