Image.Source プロパティ

リファレンス

定義

名前空間:: Microsoft.UI.Xaml.Controls

重要

一部の情報は、リリース前に大きく変更される可能性があるプレリリースされた製品に関するものです。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。

編集

イメージのソースを取得または設定します。

public:
 property ImageSource ^ Source { ImageSource ^ get(); void set(ImageSource ^ value); };

ImageSource Source();

void Source(ImageSource value);

public ImageSource Source { get; set; }

var imageSource = image.source;
image.source = imageSource;

Public Property Source As ImageSource

<Image Source="uri"/>

プロパティ値

ImageSource

描画されたイメージのイメージソースファイルを表すオブジェクト。通常、有効なイメージソースファイルへのパスを記述する Uniform Resource Identifier (URI) で構築された BitmapImage オブジェクトを使用してこれを設定します。または、ストリーム (ストレージファイルからのストリーム) を使用して BitmapSource を初期化することもできます。

注釈

Source プロパティの設定は、本質的に非同期アクションです。プロパティであるため、待機可能な構文はありませんが、ほとんどのシナリオでは、イメージソースファイルの読み込みの非同期的な側面を操作する必要はありません。フレームワークはイメージソースが返されるのを待ち、イメージソースファイルが使用可能になったときにレイアウトを再実行します。

有効なイメージソースファイルに解決できない URI (Uniform Resource Identifier) 値にソースを設定しても、例外はスローされません。代わりに、 ImageFailed イベントが発生します。デコードエラーでも ImageFailed が発生します。 ImageFailed ハンドラーを記述し、それを Image オブジェクトにアタッチしてこれを検出し、場合によってはイベントデータで ErrorMessage を使用してエラーの性質を判断できます。また、イメージソースファイルが正しく読み込まれたことを確認する場合は、Image 要素で ImageOpened イベントを処理できます。

XAML でのソースの設定

Source プロパティは、XAML で属性として設定できます。この場合、Source 属性値を、ソースイメージファイルの場所を記述する URI (Uniform Resource Identifier) 文字列として設定します。この動作は、文字列を Uniform Resource Identifier (URI) として処理し、 BitmapImage(Uri) コンストラクターと同等のを呼び出す基になる型変換に依存します。 Uri (Uniform Resource Identifier) 文字列を使用して Source プロパティを設定することは、XAML で有効になっているショートカットです。ここでの URI (Uniform Resource Identifier) は、相対 Uniform Resource Identifier (URI) のように見える点に注意してください。部分 UNIFORM Resource Identifier (URI) をサポートすることは、もう 1 つの XAML ショートカットです。

<Image Width="200" Source="Images/myImage.png"/>

XAML パーサーは、解析対象の XAML ページのベース Uniform Resource Identifier (URI) を使用して、相対 Uniform Resource Identifier (URI) を表す文字列を解釈します。たとえば、XAML で値 "Images/myImage.png" を指定した場合、その文字列は、XAML ページ自体が存在するアプリパッケージ内のベース Uniform Resource Identifier (URI) の場所に追加される相対パスサフィックスとして解釈されます。前の Image 要素がアプリパッケージのルートにあるページに追加された場合、Uniform Resource Identifier (URI) は ms-appx://Images/myImage.png として解釈されます。アプリの Pages フォルダーにあるページにイメージが追加された場合、Uniform Resource Identifier (URI) は ms-appx://Pages/Images/myImage.png として解釈されます。

ソースイメージがアプリパッケージに含まれていない場合は、絶対 Uniform Resource Identifier (URI) を使用して、XAML の Source プロパティを設定する必要があります。詳細については、このドキュメントで後述する「ファイルリソースを読み込む方法」と例を参照してください。

XAML のプロパティ要素構文を使用して、プロパティ値として有効なソースを持つ BitmapImage オブジェクト要素を指定することもできます。

コードでのソースの設定

コードで Image.Source プロパティを設定するには、BitmapImage (または BitmapSource) のインスタンスが必要です。このインスタンスも構築する必要があります。イメージソースがストリームの場合は、BitmapImage の非同期 SetSourceAsync メソッドを使用して、ストリームからのイメージ情報を定義します。

イメージソースが Uniform Resource Identifier (URI) によって参照されるファイルの場合は、 BitmapImage.UriSource プロパティを設定するか、Uniform Resource Identifier (URI) パラメーターを受け取る BitmapImage コンストラクターを使用します。 Windows ランタイムでは、Uniform Resource Identifier (URI) を絶対にする必要があります。Windows ランタイムコードで相対 Uniform Resource Identifier (URI) を使用することはできません。 .NET Framework System.Uri 値を使用していて、UriKind 値を必要とする署名を使用する場合は、必ず Absolute を指定してください。

ローカルコンテンツを参照する場合は、BitmapImage.UriSource として使用する絶対 Uniform Resource Identifier (URI) に ms-appx: スキームを含める必要があります。コードでは、相対 Uniform Resource Identifier (URI) 部分と ms-appx: スキームを組み合わせるための処理ショートカットは取得されません。これは、XAML 属性として Source を指定した場合に自動的に行われます。代わりに、適切なスキームを使用して絶対 Uniform Resource Identifier (URI) を明示的に構築する必要があります。

ソースをアプリパッケージのイメージに設定する方法を次に示します。

Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();
Uri uri = new Uri("ms-appx:///Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;

// OR

Image img = new Image();
img.Source = new BitmapImage(new Uri("ms-appx:///Assets/Logo.png"));

Windows::UI::Xaml::Controls::Image img;
Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
Windows::Foundation::Uri uri{ L"ms-appx:///Assets/LockScreenLogo.png" };
bitmapImage.UriSource(uri);
img.Source(bitmapImage);

// OR

Windows::UI::Xaml::Controls::Image img;
img.Source(Windows::UI::Xaml::Media::Imaging::BitmapImage{ Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" } });

auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
auto uri = ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;

// OR

auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png"));

コードで使用する前に Image コントロールの準備ができていることを確認する必要がある場合は、Loaded イベントを処理し、イベントハンドラーで Source プロパティを設定します。

注意

FrameworkElement.Loaded イベントは、イメージコントロールが XAML ページに読み込まれるときに発生します。 ImageOpened イベントは、イメージファイルが Image コントロールで開かれたときに発生します。

Loaded イベントのハンドラーで Image.Source を設定する例を次に示します。この例では、 Image オブジェクトは XAML で作成されましたが、ソースやその他のプロパティ値はありません。代わりに、これらの値は、イメージが XAML から読み込まれるときに実行時に提供されます。

<Image Loaded="Image_Loaded"/>

void Image_Loaded(object sender, RoutedEventArgs e)
{
    Image img = sender as Image;
    if (img != null)
    {
        BitmapImage bitmapImage = new BitmapImage();
        img.Width = bitmapImage.DecodePixelWidth = 280;
        bitmapImage.UriSource = new Uri("ms-appx:///Assets/Logo.png");
        img.Source = bitmapImage;
    }
}

void MainPage::Image_Loaded(winrt::Windows::Foundation::IInspectable const& sender, winrt::Windows::UI::Xaml::RoutedEventArgs const& /* e */)
{
    auto img{ sender.as<Windows::UI::Xaml::Controls::Image>() }; // throws if QI fails, so no need for null-check afterwards.
    Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
    img.Width(280);
    bitmapImage.DecodePixelWidth(280);
    bitmapImage.UriSource(Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" });
    img.Source(bitmapImage);
}

void App1::MainPage::Image_Loaded(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
 auto img = dynamic_cast<Image^>(sender);
 if (img != nullptr)
 {
  auto bitmapImage = ref new BitmapImage();
  img->Width = 280; bitmapImage->DecodePixelWidth = 280;
  bitmapImage->UriSource = ref new Uri("ms-appx:///Assets/Logo.png");
  img->Source = bitmapImage;
 }
}

イメージソースの取得またはデコードにタイミングの問題がある場合は、 ImageOpened イベントを処理できます。イメージソースが使用可能になるまで、代替コンテンツを表示する必要がある場合があります。コード例については、「 XAML イメージのサンプル」を参照してください。

コードでの相対 URI の使用

以前は、XAML パーサーが、解析対象の XAML ページのベースの Uniform Resource Identifier (URI) を使用して、相対 Uniform Resource Identifier (URI) を解釈することを確認しました。コードで同じ結果を得るには、絶対ベースと、その場所内の相対パスを組み合わせることによって Uniform Resource Identifier (URI) を作成するコンストラクターのいずれかを使用して URI を 構築できます。最初のパラメーターでは、Image が読み込まれる Page で BaseUri を呼び出します。 (ソースを設定している Image インスタンスまたはページ上の別の要素で BaseUri を呼び出すこともできます。以下の注意を参照してください。)これにより、ms-appx: スキームを使用して Uniform Resource Identifier (URI) が作成され、XAML ページの場所の一部であるパスが追加されます。 2 番目のパラメーターには、ソースイメージの場所を記述する相対 Uniform Resource Identifier (URI) 文字列を渡します。

C# または Microsoft Visual Basic では、 Uri 型は System.Uri として投影されるため、2 番目のパラメーターとして文字列を受け取る System.Uri(Uri, String) コンストラクターを使用します。 Visual C++ コンポーネント拡張機能 (C++/CX) では、 Uri(String,String) を使用します。

<Image x:Name="capturedPhoto"/>

BitmapImage bitmapImage = new BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage.UriSource = new Uri(this.BaseUri, "Assets/placeholder.png");
capturedPhoto.Source = bitmapImage;

auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage->UriSource = ref new Windows::Foundation::Uri(BaseUri->AbsoluteUri, "Assets/placeholder.png");
capturedPhoto->Source = bitmapImage;

注意

コードで新しい Image をインスタンス化すると、ページのビジュアルツリーに Image が追加されるまで、BaseUri プロパティは null になります。たとえば、次のコードは ArgumentNull 例外をスローします。例外を回避するには、Source プロパティを設定する前に、ビジュアルツリーに Image を追加します。

この例では、Image がページに追加される前に Image で BaseUri を呼び出すので、例外がスローされます。 'stackPanel1' は XAML で宣言された StackPanel 要素であると想定されています。

Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();

// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");

bitmapImage.UriSource = uri;
img.Source = bitmapImage;
stackPanel1.Children.Add(img);

auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();

// AN EXCEPTION IS THROWN BECAUSE img->BaseUri IS NULL AT THIS POINT.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");

bitmapImage->UriSource = uri;
img->Source = bitmapImage;
stackPanel1->Children->Append(img);

このエラーを回避するには、前に示したように、Page 自体で BaseUri を呼び出すか、次に示すように BaseUri を呼び出す前に Image をページに追加します。

この例では、BaseUri の呼び出しの前に Image がページに追加されるため、BaseUri は null ではありません。 'stackPanel1' は XAML で宣言された StackPanel 要素であると想定されています。

Image img = new Image();
// Add the image to the page.
stackPanel1.Children.Add(img);

BitmapImage bitmapImage = new BitmapImage();
// img.BaseUri in not null because img has been added to the page.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;

auto img = ref new Image();
// Add the image to the page.
stackPanel1->Children->Append(img);

auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// img->BaseUri in not null because img has been added to the page.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;

ネットワークからのファイルの使用

ネットワークの場所のファイルをイメージソースとして使用するには、次に示すように http: または https: スキームを使用します。絶対 Uniform Resource Identifier (URI) を指定します。詳細については、「ファイルリソースを読み込む方法」を参照してください。

<Image Source="http://www.contoso.com/images/logo.png"/>

Image img = new Image();
img.Source = new BitmapImage(new Uri("http://www.contoso.com/images/logo.png"));

auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("http://www.contoso.com/images/logo.png"));

ローカルストレージからのファイルの使用

アプリのローカルストレージに配置されたファイルをイメージソースとして使用するには、次に示すように ms-appdata: スキームを使用します。絶対 Uniform Resource Identifier (URI) を指定します。詳細については、「ファイルリソースを読み込む方法」を参照してください。

<!-- Access an image file stored in the local folder -->
<Image Source="ms-appdata:///local/images/logo.png"/>

<!-- Access an image file stored in the roaming folder -->
<Image Source="ms-appdata:///roaming/images/logo.png"/>

<!-- Access an image file stored in the temp folder -->
<Image Source="ms-appdata:///temp/images/logo.png"/>

var uri = new System.Uri("ms-appdata:///local/images/logo.png");
var file = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

Image img = new Image();
img.Source = file;

ストリームソースを使用して画像ライブラリの画像を表示する

アプリでの Image 要素の一般的な用途は、ユーザーの Pictures ライブラリの画像を表示することです。これらの画像は、プログラムによって、または FileOpenPicker を介してアクセスできます。どちらの場合も、取得した StorageFile オブジェクトをストリームとして開くことができますが、イメージファイルへの Uri (Uniform Resource Identifier) 参照は提供されません。ストリームをイメージソースとして使用するには、ストリームを使用するように Image インスタンスを設定するコードを記述する必要があります。これは XAML だけでは実行できません。

個々のイメージを表示するには、ライブラリの列挙から StorageFile オブジェクトを使用し、 OpenAsync を呼び出してストリームを取得します。このストリームを使用して、新しい BitmapImage を作成し、 SetSourceAsync を呼び出し、 streamSource パラメーターとして使用するストリームを渡すことによって、イメージソースを設定します。

この例では、 FileOpenPicker を使用して画像ライブラリからイメージファイルにアクセスし、イメージコントロールのソースとして設定する方法を示します。ユーザーがファイルを選択するのを待ち、その後にのみ実行されるため、コードは既に待機可能です。使用するストリームは、非同期ピッカーアクションから StorageFile インスタンスが返された後、StorageFile.OpenAsync から取得されます。ファイルピッカーの使用方法の詳細については、「ピッカーを使用してファイルとフォルダーを開く」を参照してください。

<Button Content="Get photo" Click="GetPhotoButton_Click"/>

<Image x:Name="image1" Width="300"/>

private async void GetPhotoButton_Click(object sender, RoutedEventArgs e)
{
    // Set up the file picker.
    Windows.Storage.Pickers.FileOpenPicker openPicker = 
        new Windows.Storage.Pickers.FileOpenPicker();
    openPicker.SuggestedStartLocation = 
        Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
    openPicker.ViewMode = 
        Windows.Storage.Pickers.PickerViewMode.Thumbnail;

    // Filter to include a sample subset of file types.
    openPicker.FileTypeFilter.Clear();
    openPicker.FileTypeFilter.Add(".bmp");
    openPicker.FileTypeFilter.Add(".png");
    openPicker.FileTypeFilter.Add(".jpeg");
    openPicker.FileTypeFilter.Add(".jpg");

    // Open the file picker.
    Windows.Storage.StorageFile file = 
        await openPicker.PickSingleFileAsync();

    // 'file' is null if user cancels the file picker.
    if (file != null)
    {
        // Open a stream for the selected file.
        // The 'using' block ensures the stream is disposed
        // after the image is loaded.
        using (Windows.Storage.Streams.IRandomAccessStream fileStream =
            await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
        {
            // Set the image source to the selected bitmap.
            Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
                new Windows.UI.Xaml.Media.Imaging.BitmapImage();

            bitmapImage.SetSource(fileStream);
            image1.Source = bitmapImage;
        }
    }
}

この例では、画像ライブラリからプログラムでイメージファイルにアクセスし、イメージコントロールのソースとして設定する方法を示します。プログラムで Pictures ライブラリのコンテンツにアクセスするには、 StorageFolder.GetFilesAsync を呼び出します。画像ライブラリにプログラムでアクセスする機能を指定する必要があります。

protected async override void OnNavigatedTo(NavigationEventArgs e)
{
    // Get the Pictures library
    Windows.Storage.StorageFolder picturesFolder = 
        Windows.Storage.KnownFolders.PicturesLibrary;
    IReadOnlyList<StorageFolder> folders = 
        await picturesFolder.GetFoldersAsync();

    // Process file folders
    foreach (StorageFolder folder in folders)
    {
        // Get and process files in folder
        IReadOnlyList<StorageFile> fileList = await folder.GetFilesAsync();
        foreach (StorageFile file in fileList)
        {
            Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage = 
                new Windows.UI.Xaml.Media.Imaging.BitmapImage();

            // Open a stream for the selected file.
            // The 'using' block ensures the stream is disposed
            // after the image is loaded.
            using (Windows.Storage.Streams.IRandomAccessStream fileStream = 
                await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
            {
                // Set the image source to the selected bitmap.
                Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
                    new Windows.UI.Xaml.Media.Imaging.BitmapImage();
                bitmapImage.SetSource(fileStream);

                // Create an Image control.  
                Image img = new Image();
                img.Height = 50;
                img.Source = bitmapImage;

                // Add the Image control to the UI. 'imageGrid' is a
                // VariableSizedWrapGrid declared in the XAML page.
                imageGrid.Children.Add(img);
            }
        }
    }
}

画像ソースとスケーリング

アプリにパッケージ化されたイメージを参照している場合は、Windows ランタイムがスケーリングしたときにアプリが適切に表示されるように、いくつかの推奨サイズでイメージソースを作成する必要があります。イメージのソースを UNIFORM Resource Identifier (URI) として指定する場合は、システムによって実行時に検出された現在のスケーリングに対する正しいイメージリソースを自動的に参照する名前付け規則を使用できます。この名前付け規則の詳細や関連情報については、「クイックスタート: ファイルまたは画像リソースの使用」をご覧ください。

スケーリング用に設計する方法の詳細については、「レスポンシブデザイン 101 for 」または「イメージの解説」を参照してください。

イメージソースとリソース修飾子

現在のスケール修飾子とカルチャ修飾子を使用して非修飾リソースにアクセスするために自動処理を使用することも、 ResourceManager と ResourceMap をカルチャとスケールの修飾子と共に使用してリソースを直接取得することもできます。詳細については、「リソース管理システム」または「イメージの解説」を参照してください。アプリリソースの詳細と、アプリでイメージソースをパッケージ化する方法については、「アプリリソースの定義」を参照してください。

適用対象

次の方法で共有

Image.Source プロパティ

定義

プロパティ値

注釈

XAML でのソースの設定

コードでのソースの設定

コードでの相対 URI の使用

ネットワークからのファイルの使用

ローカルストレージからのファイルの使用

ストリームソースを使用して画像ライブラリの画像を表示する

画像ソースとスケーリング

イメージソースとリソース修飾子

適用対象

こちらもご覧ください

フィードバック

その他のリソース

次の方法で共有

Image.Source プロパティ

定義

プロパティ値

注釈

XAML でのソースの設定

コードでのソースの設定

コードでの相対 URI の使用

ネットワークからのファイルの使用

ローカル ストレージからのファイルの使用

ストリーム ソースを使用して画像ライブラリの画像を表示する

画像ソースとスケーリング

イメージ ソースとリソース修飾子

適用対象

こちらもご覧ください

フィードバック

その他のリソース

ローカルストレージからのファイルの使用

ストリームソースを使用して画像ライブラリの画像を表示する

イメージソースとリソース修飾子