Image.Source プロパティ

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"/>

プロパティ値

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

注釈

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

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

XAML でのソースの設定

Source プロパティは、XAML で属性として設定できます。 この場合、ソース属性値を、ソース イメージ ファイルの場所を記述する 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 プロパティを設定する必要があります。 詳細については、 ファイル リソースを読み込む方法と、このドキュメントの後半の例を参照してください。

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

コード内のソースの設定

コードで 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 属性として指定した場合に自動的に行われます。 代わりに、適切なスキームを使用して絶対 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 プロパティを設定します。

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: スキームを使用して URI (Uniform Resource Identifier) が作成され、XAML ページの場所の一部であるパスが追加されます。 2 番目のパラメーターには、ソース イメージの場所を記述する相対 Uniform Resource Identifier (URI) 文字列を渡します。

C# では、 Uri 型は System.Uri として投影されるため、2 番目のパラメーターとして文字列を受け取る System.Uri(Uri, String) コンストラクターを使用します。 C++ では、 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 を呼び出しているため、例外をスローします。 '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);

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

この例では、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 を使用して Pictures ライブラリからイメージ ファイルにアクセスし、 イメージ コントロールのソースとして設定する方法を示します。 ユーザーがファイルを選択するのを待機しており、その後にのみ実行されるため、コードは既に待機しています。 使用するストリームは、非同期ピッカー アクションから 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 を呼び出します。 Pictures ライブラリにプログラムでアクセスする機能を指定する必要があります。

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) として指定する場合は、システムが実行時に検出した現在のスケーリングに対して適切なイメージ リソースを自動的に参照する名前付け規則を使用できます。 名前付け規則の詳細と詳細については、「 Quickstart: ファイルまたはイメージ リソースの使用」を参照してください。

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

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

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

こちらもご覧ください

• ImageFailed
• ImageOpened
• BitmapSource
• Image と ImageBrush
• XAML イメージのサンプル