BitmapImage クラス
定義
重要
一部の情報は、リリース前に大きく変更される可能性があるプレリリースされた製品に関するものです。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。
Image.Source プロパティと ImageBrush.ImageSource プロパティの実用的なオブジェクト ソースの種類を提供します。 BitmapImage は、イメージ ソース ファイルを参照する Uniform Resource Identifier (URI) を使用するか、 SetSourceAsync を呼び出してストリームを提供することで定義できます。
public ref class BitmapImage sealed : BitmapSource/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory, 65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.Activatable(65536, Windows.Foundation.UniversalApiContract)]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class BitmapImage final : BitmapSource/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BitmapImage final : BitmapSource[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory), 65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.Activatable(65536, typeof(Windows.Foundation.UniversalApiContract))]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class BitmapImage : BitmapSource[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BitmapImage : BitmapSourcePublic NotInheritable Class BitmapImage
Inherits BitmapSource<BitmapImage .../>
- 継承
- 属性
Windows の要件
| デバイス ファミリ |
Windows 10 (10.0.10240.0 で導入)
|
| API contract |
Windows.Foundation.UniversalApiContract (v1.0 で導入)
|
例
次に、BitmapImage オブジェクトを使用して C# で Image.Source を設定する例を示します。 この例では、 Image オブジェクトは XAML で作成されましたが、ソースやその他のプロパティ値はありません。代わりに、 実行時にイメージ が XAML から読み込まれるときに、これらの値が提供されます。
<Image Loaded="Image_Loaded"/>
void Image_Loaded(object sender, RoutedEventArgs e)
{
Image img = sender as Image;
BitmapImage bitmapImage = new BitmapImage();
img.Width = bitmapImage.DecodePixelWidth = 80;
// Natural px width of image source.
// You don't need to set Height; the system maintains aspect ratio, and calculates the other
// dimension, as long as one dimension measurement is provided.
bitmapImage.UriSource = new Uri(img.BaseUri,"Assets/StoreLogo.png");
img.Source = bitmapImage;
}
注釈
BitmapImage は、次のイメージ ファイル形式からソースにすることができます。
- Joint Photographic Experts Group (JPEG)
- ポータブル ネットワーク グラフィックス (PNG)
- ビットマップ (BMP)
- グラフィックス交換形式 (GIF)
- Tagged Image File Format (TIFF)
- JPEG XR
- アイコン (ICO)
イメージ ソースがストリームの場合、そのストリームには、これらの形式のいずれかでイメージ ファイルが含まれている必要があります。
BitmapImage クラスは抽象化を表します。そのため、イメージ ソースは非同期的に設定できますが、XAML マークアップではプロパティ値として、または待機可能な構文を使用しないオブジェクトとしてコードで参照できます。 BitmapImage オブジェクトをコードで作成すると、最初は有効なソースがありません。 その後、次のいずれかの手法を使用してソースを設定する必要があります。
- 既定のコンストラクターではなく 、BitmapImage(Uri) コンストラクターを使用します。 これはコンストラクターですが、これは暗黙的な非同期動作を持つものとして考えることができます。BitmapImage は、非同期ソース セット操作が成功したことを示す ImageOpened イベントが発生するまで使用できる状態になりません。
- UriSource プロパティを設定します。 Uri コンストラクターの使用と同様に、このアクションは暗黙的に非同期であり、ImageOpened イベントが発生するまで BitmapImage は使用できる状態になりません。
- SetSourceAsync を使用します。 このメソッドは明示的に非同期です。 Image.Source などの BitmapImage を使用する可能性があるプロパティは、この非同期動作用に設計されており、完全なソースがない BitmapImage を使用して設定されている場合は例外をスローしません。 例外を処理するのではなく、 ImageOpened イベントまたは ImageFailed イベントを BitmapImage で直接処理するか、ソースを使用するコントロールで処理する必要があります (これらのイベントがコントロール クラスで使用可能な場合)。
ImageFailed と ImageOpened は相互に排他的です。 BitmapImage オブジェクトのソース値が設定またはリセットされるたびに、1 つのイベントまたはもう一方のイベントが常に発生します。
BitmapImage とエンコード
イメージ ファイルの基になるコーデックのサポートは、Windows の Windows イメージング コンポーネント (WIC) API によって提供されます。 コーデックに関するドキュメントに記載されている特定のイメージ形式の詳細については、「 ネイティブ WIC コーデック」を参照してください。 形式と、Uniform Resource Identifier (URI) を使用して、アプリ リソースから取得されたイメージ ソース ファイルにアクセスする方法の詳細については、「 Image and ImageBrush」を参照してください。
Image、BitmapImage、BitmapSource の API には、メディア形式のエンコードとデコードのための専用のメソッドは含まれていません。 エンコード操作とデコード操作はすべてビルトインであり、せいぜいエンコードまたはデコードの局面が読み込みイベント用のイベント データの一部として現れる程度です。 イメージエンコードまたはデコードで特別な作業を行う場合は、アプリが画像変換や操作を行っている場合に使用する可能性があります。 Windows.Graphics.Imaging 名前空間で使用できる API を使用する必要があります。 これらのイメージング API は、C++、C#、または JavaScript を使用する Visual Basic または Windows アプリを使用する UWP アプリで使用できます。 これらの API は、Windows 8 の Windows イメージング コンポーネント (WIC) コンポーネントでもサポートされています。
アニメーション画像
バージョン 1607 Windows 10以降、XAML Image 要素はアニメーション GIF イメージをサポートしています。 Image Source として BitmapImage を使用すると、BitmapImage API にアクセスして、アニメーション GIF イメージの再生を制御できます。
- アニメーション化されたビットマップが読み込まれるとすぐに再生するかどうかを指定するには、 AutoPlay プロパティ (既定値は true) を使用します。
- ビットマップをアニメーション化するかどうかをチェックするには、IsAnimatedBitmap プロパティを使用します。
- アニメーションビットマップの再生を制御するには、 IsPlaying プロパティと Play メソッドと Stop メソッドを使用します。
注意
ほとんどのアプリでは、ユーザーのアクセシビリティのニーズをサポートするために、UISettings.AnimationsEnabled が false の場合は AutoPlay を false に設定することをお勧めします。 アニメーション GIF のコンテンツがアプリの使いやすさにとって重要な場合は、この操作を行わないでください。
アプリがバージョン 1607 より前のWindows 10のリリースで実行されている場合は、ApiInformation クラスを使用して、これらのメンバーが存在するかどうかをチェックしてから使用する必要があります。 詳細については、「 バージョン アダプティブ コード: 以前のバージョンとの互換性を維持しながら新しい API を使用する」を参照してください。
この例では、アニメーション GIF の使用方法を示します。 ボタンを使用すると、ユーザーはアニメーションを開始または停止できます。 この例では、バージョン アダプティブ コードを使用して、すべてのバージョンのWindows 10で実行できます。 バージョン 1607 より前のバージョンでは、GIF の最初のフレームが表示されますが、アニメーション化されません。
<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
<Image Loaded="Image_Loaded">
<Image.Source>
<BitmapImage x:Name="imageSource"
UriSource="Assets/example.gif"
ImageOpened="imageSource_ImageOpened"/>
</Image.Source>
</Image>
<AppBarButton x:Name="playButton"
Icon="Play"
Visibility="Collapsed"
Click="playButton_Click"/>
</Grid>
// Set the AutoPlay property.
private void Image_Loaded(object sender, RoutedEventArgs e)
{
if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "AutoPlay") == true)
{
imageSource.AutoPlay = false;
}
}
// Show the play/stop button if the image is animated.
private void imageSource_ImageOpened(object sender, RoutedEventArgs e)
{
var bitmapImage = (BitmapImage)sender;
// At this point you can query whether the image is animated or not.
if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsAnimatedBitmap")
&& bitmapImage.IsAnimatedBitmap == true)
{
// Enable the play button
playButton.Visibility = Visibility.Visible;
}
}
// Play or stop the animated bitmap.
void playButton_Click(object sender, RoutedEventArgs e)
{
if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsPlaying"))
{
// You can call the Play and Stop methods safely because is the IsPlaying property is
// present, these methods are also present.
if (imageSource.IsPlaying == true)
{
playButton.Icon = new SymbolIcon(Symbol.Play);
imageSource.Stop();
}
else
{
playButton.Icon = new SymbolIcon(Symbol.Stop);
imageSource.Play();
}
}
}
その他の例については、 アニメーション GIF 再生のサンプルを参照してください。
バージョン履歴
| Windows のバージョン | SDK バージョン | 追加された値 |
|---|---|---|
| 1607 | 14393 | AutoPlay |
| 1607 | 14393 | IsAnimatedBitmap |
| 1607 | 14393 | IsPlaying |
| 1607 | 14393 | Play |
| 1607 | 14393 | Stop |
コンストラクター
| BitmapImage() |
BitmapImage クラスの新しいインスタンスを初期化します。 |
| BitmapImage(Uri) |
指定された Uniform Resource Identifier (URI) を使用して、 BitmapImage クラスの新しいインスタンスを初期化します。 |
プロパティ
| AutoPlay |
アニメーション化されたイメージが読み込まれたらすぐに再生するかどうかを示す値を取得または設定します。 |
| AutoPlayProperty |
AutoPlay 依存関係プロパティを識別します。 |
| CreateOptions |
BitmapImage の BitmapCreateOptions を取得または設定します。 |
| CreateOptionsProperty |
CreateOptions 依存関係プロパティを識別します。 |
| DecodePixelHeight |
イメージのデコード操作に使用する高さを取得または設定します。 |
| DecodePixelHeightProperty |
DecodePixelHeight 依存関係プロパティを識別します。 |
| DecodePixelType |
デコード操作で DecodePixelWidth 値と DecodePixelHeight 値を解釈する方法を決定する値を取得または設定します。 |
| DecodePixelTypeProperty |
DecodePixelType 依存関係プロパティを識別します。 |
| DecodePixelWidth |
イメージのデコード操作に使用する幅を取得または設定します。 |
| DecodePixelWidthProperty |
DecodePixelWidth 依存関係プロパティを識別します。 |
| Dispatcher |
このオブジェクトが関連付けられている CoreDispatcher を取得します。 CoreDispatcher は、コードが UI 以外のスレッドによって開始された場合でも、UI スレッド上の DependencyObject にアクセスできる機能を表します。 (継承元 DependencyObject) |
| IsAnimatedBitmap |
イメージがアニメーション化されているかどうかを示す値を取得します。 |
| IsAnimatedBitmapProperty |
IsAnimatedBitmap 依存関係プロパティを識別します。 |
| IsPlaying |
アニメーション化されたイメージが再生されているかどうかを示す値を取得します。 |
| IsPlayingProperty |
IsPlaying 依存関係プロパティを識別します。 |
| PixelHeight |
ビットマップの高さ (ピクセル単位) を取得します。 (継承元 BitmapSource) |
| PixelWidth |
ビットマップの幅 (ピクセル単位) を取得します。 (継承元 BitmapSource) |
| UriSource |
この BitmapImage を生成したグラフィックス ソース ファイルの Uniform Resource Identifier (URI) を取得または設定します。 |
| UriSourceProperty |
UriSource 依存関係プロパティを識別します。 |
メソッド
イベント
| DownloadProgress |
BitmapImage コンテンツのダウンロードの進行状況で大きな変更が発生したときに発生します。 |
| ImageFailed |
イメージの取得または形式に関連するエラーがある場合に発生します。 |
| ImageOpened |
イメージ ソースがダウンロードされ、エラーなしでデコードされたときに発生します。 このイベントを使用して、イメージをレンダリングする前にイメージのサイズを決定できます。 |