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

プロパティ値

描画されたイメージのイメージ ソース ファイルを表す オブジェクト。 通常、有効なイメージ ソース ファイルへのパスを記述する 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 が読み込まれる PageBaseUri を呼び出します。 (ソースを設定している 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 がページに追加される前に ImageBaseUri を呼び出すので、例外がスローされます。 '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 がページに追加されるため、BaseUrinull ではありません。 '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 」または 「イメージの解説」を参照してください。

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

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

適用対象

こちらもご覧ください