> [Site index](https://perfectvector.com/llms.txt) — available pages and descriptions.

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

> .NET MAUIにSVGを追加し、生成されたPNGを参照します。BaseSizeとレイアウトサイズを区別し、ファイル名、画像メタデータ、描画結果を確認します。

Source: https://perfectvector.com/ja/blog/svg-in-dotnet-maui

Language: ja
Author: Claire Yoon
Published: 2026-09-15T08:00:00+09:00
Updated: 2026-09-15T08:00:00+09:00

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

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

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

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

| 段階          | コンパスの例                         | 決めること                         |
| ----------- | ------------------------------ | ----------------------------- |
| アートワークの元データ | `Resources/Images/compass.svg` | 描画範囲を設定し、リングの穴を保持します。         |
| プロジェクト項目    | 基準サイズを持つ`MauiImage`            | 対象の画素密度向け画像を生成するための基準寸法を選びます。 |
| ビュー         | `Image Source="compass.png"`   | 表示領域と拡大縮小の動作を選びます。            |

[Imageコントロールの資料](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/image)では、対象の画素密度に対応する画像がアプリのパッケージに入り、OSが適切な解像度を選ぶ仕組みを説明しています。SVGマスターを保持していても、このワークフローでビューにSVG文書そのものが渡されるわけではありません。

![コンパスのアートワークがSVGの元データからPNG画像出力を経て画像ビューへ進む概念図](https://perfectvector.com/blog/svg-in-dotnet-maui/source-build-view.webp)

*バンドル画像のワークフローの図です。SVGは編集可能な元データとして残り、ビルドがアプリ用のPNG画像を準備します。*

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

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

```xml
<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ファイルのガイド](https://perfectvector.com/ja/blog/what-is-an-svg-file)を参照してください。

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

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

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

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

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

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

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

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

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

`.png`拡張子は意図的な指定です。幅と高さは正方形の表示領域を要求し、`AspectFit`は画像全体をその中に収めます。長方形のイラストなら、正方形いっぱいに引き伸ばすのではなく、形に合う表示領域を使ってください。Microsoftの[画像の拡大縮小リファレンス](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/image#control-image-scaling)では、全体を収める、切り抜く、引き伸ばす動作を区別しています。

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

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

`BaseSize="48,48"`は、MAUIが画素密度ごとの画像を生成するための基準寸法を指定します。明示的な基準サイズがなければ、SVG自体の寸法が使われます。両方の規則はMicrosoftの[画像のサイズ変更](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/images/images#resize-an-image)に記載されています。

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

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

鮮明さを改善する万能な設定として`Resize="false"`を使わないでください。この処理系ではベクター画像のサイズ変更を無効にします。[サイズ変更オプションの資料](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/images/images#resize-an-image)に従い、その動作が必要な場合だけ選びます。

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

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

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

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

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

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

同じアートワークでも、[FlutterのSVG画像ワークフロー](https://perfectvector.com/ja/blog/flutter-svg-images)、[SwiftUIのアセットカタログ](https://perfectvector.com/ja/blog/svg-in-swiftui)、[Android VectorDrawableへのインポート](https://perfectvector.com/ja/blog/convert-png-to-android-vector-drawable)では設定が異なります。元のマスターを再利用し、各出力先の規則に従ってください。

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

コンパスやロゴがPNGでしか存在しない場合は、MAUIプロジェクトに追加する前にPerfectVectorで編集可能なSVGを作成できます。[PNGをSVGに変換](https://perfectvector.com/ja/convert-png-to-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アプリプロジェクトへの画像の追加](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/images/images) — SVGからPNGへの処理、画像項目、ファイル名、基準サイズ、ビルドメタデータ。
2. [Microsoft — Image](https://learn.microsoft.com/en-us/dotnet/maui/user-interface/controls/image) — ローカル画像の参照、対象の画素密度の選択、ビューサイズ、拡大縮小の動作。
3. [Microsoft — Item要素（MSBuild）](https://learn.microsoft.com/en-us/visualstudio/msbuild/item-element-msbuild) — Includeによる項目の追加とUpdateによる既存メタデータの変更の違い。
4. [Vapolia — SVGサンプル](https://github.com/vapolia/Svg-Samples) — 別の実行時SVGコントロールとリソース読み込みのワークフロー。

***

ラスターだけのアプリ紋章から作業していますか。[PNGを編集可能なSVGに変換](https://perfectvector.com/ja/convert-png-to-svg)して穴と間隔を確認し、そのマスターをMAUIに追加して、対象アプリで生成画像を確認してください。

## Explore

- [Read the HTML article](https://perfectvector.com/ja/blog/svg-in-dotnet-maui)
- [fpdf2のSVG画像：PythonのPDFでパスを保つ](https://perfectvector.com/ja/blog/fpdf2-svg-image.md)
- [Inkscapeのコマンドライン書き出し：ページ・描画・オブジェクト](https://perfectvector.com/ja/blog/inkscape-cli-export.md)
- [Product facts](https://perfectvector.com/product-facts.md)
- [FAQ](https://perfectvector.com/faq.md)
- [Pricing and credits](https://perfectvector.com/pricing.md)
