イメージ

  • [アーティクル]

.NET Multi-platform App UI (.NET MAUI) Image には、ローカル ファイル、URI、またはストリームから読み込むことができるイメージが表示されます。 アニメーション GIF を含む標準のプラットフォーム イメージ形式がサポートされており、ローカルのスケーラブル ベクター グラフィックス (SVG) ファイルもサポートされています。 .NET MAUI アプリ プロジェクトへのイメージの追加の詳細については、「.NET MAUI アプリ プロジェクトに画像を追加する」を参照してください。

Image は次の特性を定義します。

  • Aspect 型の Aspect は、イメージ のスケーリング モードを定義します。
  • bool 型の IsAnimationPlaying は、アニメーション GIF の再生中か停止かを決定します。 このプロパティの既定値は false です。
  • bool 型の IsLoading は、画像の読み込み状態を示します。 このプロパティの既定値は false です。
  • bool 型の IsOpaque は、レンダリング エンジンが画像をレンダリング中に不透明として扱えるかどうかを示します。 このプロパティの既定値は false です。
  • ImageSource 型の Source は、画像の種類を指定します。

これらのプロパティは、BindableProperty オブジェクトによってサポートされているので、スタイルを設定したり、データ バインディングの対象にすることができます。

Note

フォント アイコンは、FontImageSource オブジェクトとしてフォント アイコン データを指定することによって Image で表示できます。 詳細については、「フォント アイコンを表示する」を参照してください。

ImageSource クラスは、さまざまなソースから画像を読み込むのに使用できる次のメソッドを定義します。

  • FromFile は、ローカル ファイルから画像を読み取る FileImageSource を返します。
  • FromUri は、指定された URI から画像をダウンロードして読み取る UriImageSource を返します。
  • FromStream は、画像データを提供するストリームから画像を読み取る StreamImageSource を返します。

XAML では、ファイル名または URI を Source プロパティの文字列値として指定することで、ファイルと URI から画像を読み込むことができます。 カスタム マークアップ拡張機能を使用して、XAML のストリームから画像を読み込むこともできます。

重要

Image のサイズがレイアウトによって制限されているか、Image の HeightRequest または WidthRequest プロパティが指定されていない限り、画像は完全な解像度で表示されます。

アプリ アイコンとスプラッシュ スクリーンをアプリに追加する方法の詳細については、「アプリ アイコンとスプラッシュ スクリーン」を参照してください。

ローカル画像を読み込む

画像は、プロジェクトの Resources\Images フォルダーにドラッグすることでアプリ プロジェクトに追加できます。ここで、そのビルド アクションは自動的に MauiImage に設定されます。 ビルド時に、ベクター画像はターゲット プラットフォームとデバイスの適切な解像度にサイズ変更され、アプリ パッケージに追加されます。 これは、異なるプラットフォームが異なる画像解像度をサポートし、オペレーティング システムがデバイスの機能に基づいて実行時に適切な画像解像度を選択するためです。

Android リソースの名前付け規則に準拠するには、すべてのローカル画像ファイル名を小文字にし、先頭と末尾を文字で区切り、英数字またはアンダースコアのみを含める必要があります。 詳細については、developer.android.com の「アプリ リソースの概要」をご覧ください。

重要

.NET MAUI は、SVG ファイルを PNG ファイルに変換します。 そのため、SVG ファイルを .NET MAUI アプリ プロジェクトに追加する場合は、.png 拡張子を持つ XAML または C# から参照する必要があります。

ファイルの名前付けと配置に関するこれらの規則に従うと、次の XAML で画像を読み込んで表示できます。

<Image Source="dotnet_bot.png" />

同等の C# コードを次に示します。

Image image = new Image
{
    Source = ImageSource.FromFile("dotnet_bot.png")
};

このメソッドには ImageSource.FromFile 引数が string 必要であり、ファイルから画像を読み取る新しい FileImageSource オブジェクトが返されます。 ファイル名を Image.Source プロパティの string 引数として指定できるようにする暗黙的な変換演算子もあります。

Image image = new Image { Source = "dotnet_bot.png" };

リモート画像を読み込む

リモート画像をダウンロードして表示するには、Source プロパティの値として URI を指定します。

<Image Source="https://aka.ms/campus.jpg" />

同等の C# コードを次に示します。

Image image = new Image
{
    Source = ImageSource.FromUri(new Uri("https://aka.ms/campus.jpg"))
};

ImageSource.FromUri メソッドには Uri 引数が必要であり、画像を読み取る新しい UriImageSource オブジェクトを Uri から返します。 文字列ベースの URI の暗黙的な変換もあります。

Image image = new Image { Source = "https://aka.ms/campus.jpg" };

画像のキャッシュ

ダウンロードした画像のキャッシュは既定で有効になっており、キャッシュされた画像は 1 日間保存されます。 この動作は、UriImageSource クラスのプロパティを設定することにより変更できます。

UriImageSource クラスでは、次のプロパティが定義されます。

  • Uri 型の Uri は、表示用にダウンロードされるイメージの URI を表します。
  • TimeSpan 型の CacheValidity は、画像をローカルに保存する期間を指定します。 このプロパティの既定値は 1 日です。
  • bool 型の CachingEnabled は、画像のキャッシュを有効にするかどうかを定義します。 このプロパティの既定値は true です。

これらのプロパティは、BindableProperty オブジェクトによってサポートされているので、スタイルを設定したり、データ バインディングの対象にすることができます。

特定のキャッシュ期間を設定するには、CacheValidity プロパティを設定する UriImageSource オブジェクトに Source プロパティを設定します。

<Image>
    <Image.Source>
        <UriImageSource Uri="https://aka.ms/campus.jpg"
                        CacheValidity="10:00:00:00" />
    </Image.Source>
</Image>

同等の C# コードを次に示します。

Image image = new Image();
image.Source = new UriImageSource
{
    Uri = new Uri("https://aka.ms/campus.jpg"),
    CacheValidity = new TimeSpan(10,0,0,0)
};

この例では、キャッシュ期間は 10 日に設定されています。

ストリームから画像を読み込む

ImageSource.FromStream メソッドを使用してストリームから画像を読み込むことができます。

Image image = new Image
{
    Source = ImageSource.FromStream(() => stream)
};

重要

ImageSource.FromStream メソッドを使用してストリームから画像を読み込む場合、Android では画像キャッシュが無効になります。 これは、適切なキャッシュ キーを作成するデータがないためです。

フォント アイコンを読み込む

FontImage マークアップ拡張機能を使用すると、ImageSource を表示できる任意のビューでフォント アイコンを表示できます。 FontImageSource クラスと同じ機能が提供されますが、より簡潔な表現が提供されます。

FontImage マークアップ拡張機能は、次のプロパティを定義する FontImageExtension クラスによってサポートされています。

  • string 型の FontFamily は、フォント アイコンが属するフォント ファミリーです。
  • string 型の Glyph は、フォント アイコンの Unicode 文字値です。
  • Color 型の Color は、フォント アイコンを表示する際に使用される色です。
  • double 型の Size は、レンダリングされたフォント アイコンのサイズ (デバイスに依存しない単位) です。 既定値は 30 です。 さらに、このプロパティは名前付きのフォント サイズに設定できます。

Note

XAML パーサーでは、FontImageExtension クラスを FontImage に短縮できます。

Glyph プロパティは、FontImageExtension のコンテンツ プロパティです。 したがって、中かっこで表現された XAML マークアップ拡張機能の場合、それが最初の引数であれば、式の Glyph= 部分を削除できます。

次の XAML 例は、FontImage マークアップ拡張機能の使用方法を示しています。

<Image BackgroundColor="#D1D1D1"
       Source="{FontImage &#xf30c;, FontFamily=Ionicons, Size=44}" />

この例では、FontImageExtension クラス名の省略形を使用して、Ionicons フォント ファミリの XBox アイコンを Image で表示します。

Screenshot of the FontImage markup extension.

アイコンの Unicode 文字は \uf30c ですが、XAML ではエスケープする必要があるため、&#xf30c; になります。

FontImageSource オブジェクトでフォント アイコン データを指定してフォント アイコンを表示する方法については、「フォント アイコンの表示」をご覧ください。

アニメーション GIF の読み込み

.NET MAUI には、小さいアニメーション GIF の表示のサポートが含まれています。 これを行うには、Source プロパティをアニメーション GIF ファイルに設定します。

<Image Source="demo.gif" />

重要

.NET MAUI でのアニメーション GIF のサポートにはファイルをダウンロードする機能が含まれていますが、アニメーション GIF のキャッシュやストリーミングはサポートされていません。

既定では、アニメーション GIF が読み込まれると再生されません。 これは、アニメーション GIF の再生または停止を制御する IsAnimationPlaying プロパティの既定値が false であるためです。 したがって、アニメーション GIF が読み込まれると、IsAnimationPlaying プロパティが true に設定されるまで再生されません。 再生を停止するには、IsAnimationPlaying プロパティを false にリセットします。 GIF 以外の画像ソースを表示する場合、このプロパティは効果がないことに注意してください。

画像のスケーリングを制御する

Aspect プロパティは、表示領域に合わせて画像を拡大縮小する方法を決定し、Aspect 列挙のメンバーのいずれかに設定する必要があります。

  • AspectFit は、画像全体が表示領域に収まるように画像をレターボックス化します (必要な場合)。画像が横長か縦長かに応じて、上下または左右に空白スペースを追加します。
  • AspectFill - 画像をクリップして、縦横比を維持したまま、表示領域を満たすようにします。
  • Fill - 画像を完全に拡大し、表示領域を完全に塗りつぶします。 これにより、画像の歪みが発生する可能性があります。
  • Centerは、縦横比を維持しながら、画像を表示領域の中央に配置します。