Image.Source 屬性

  • 參考

定義

命名空間:
Windows.UI.Xaml.Controls
編輯

取得或設定影像的來源。

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

物件，表示所繪製影像的影像來源檔案。 您通常會使用 BitmapImage 物件來設定此專案，此物件會使用統一資源識別元 (URI 建構，) 描述有效影像來源檔案的路徑。 或者，您可以使用資料流程來初始化 BitmapSource ，可能是來自儲存體檔案的資料流程。

備註

設定 Source 屬性原本就是非同步動作。 因為它是屬性，所以沒有可等候的語法，但在大部分情況下，您不需要與影像來源檔案載入的非同步層面互動。 架構會等候傳回映射來源，並在映射來源檔案可供使用時重新執行配置。

將來源設定為統一資源識別元 (URI) 無法解析為有效映射來源檔案的值，並不會擲回例外狀況。 相反地，它會引發 ImageFailed 事件。 解碼失敗也會引發 ImageFailed。 您可以撰寫 ImageFailed 處理常式，並將其附加至 Image 物件以偵測此情況，而且可能會使用事件資料中的 ErrorMessage 來判斷失敗的本質。 此外，如果您想要確認影像來源檔案已正確載入，您可以在Image元素上處理ImageOpened事件。

在 XAML 中設定來源

您可以將 Source 屬性設定為 XAML 中的屬性。 在此情況下，您會將 [來源] 屬性值設定為統一資源識別項 (URI) 字串，以描述來源影像檔的位置。 此行為依賴基礎類型轉換，以統一資源識別元 (URI) 處理字串，並呼叫 點陣圖Image (Uri) 建構函式的對等專案。 使用統一資源識別項設定來源屬性 (URI) 字串是 XAML 所啟用的快捷方式。 請注意，此處的統一資源識別項 (URI) 看起來是相對的統一資源識別項 (URI) ;支援部分統一資源識別項 (URI) 是另一個 XAML 快捷方式。

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

XAML 剖析器會使用所剖析之 XAML 頁面的基底統一資源識別項 (URI) ，解譯代表相對統一資源識別元 () URI 的任何字串。 例如，如果您在 XAML 中指定 「Images/myImage.png」 值，該字串會解譯為附加至基底統一資源識別元的相對路徑尾碼， (URI) XAML 頁面本身所在的應用程式套件內的位置。 如果先前的 Image 元素新增至應用程式套件根目錄中的頁面，則會將統一資源識別項 (URI) 解譯為 ms-appx:///Images/myImage.png。 如果 影像 新增至應用程式中 Pages 資料夾中的頁面，則會將統一資源識別元 (URI) 解譯為 ms-appx:///Pages/Images/myImage.png。

如果來源映射不是應用程式套件的一部分，您必須使用絕對統一資源識別項 (URI) ，才能在 XAML 中設定 Source 屬性。 如需詳細資訊，請參閱 如何載入檔資源，以及本檔稍後的範例。

您也可以使用 XAML 中的屬性專案語法，將具有有效來源的 BitmapImage 物件專案指定為屬性值。

在程式碼中設定原始程式碼

若要在程式碼中設定 Image.Source 屬性，則需要 BitmapImage (實例或 BitmapSource) ，您也必須建構此屬性。 如果您的影像來源是資料流程，請使用BitmapImage的async SetSourceAsync方法來定義資料流程中的影像資訊。

如果您的影像來源是統一資源識別項 (URI) 所參考的檔案，請設定 BitmapImage.UriSource 屬性，或使用採用統一資源識別項 (URI) 參數的 BitmapImage 建構函式。 Windows 執行階段會強制執行統一資源識別元 (URI) 必須是絕對;您無法在Windows 執行階段程式碼中使用相對統一資源識別項 (URI) 。 如果您使用 .NET Framework System.Uri值，而且您使用需要UriKind值的簽章，請務必指定Absolute。

當您參考本機內容時，您必須在絕對統一資源識別項 (URI 中包含 ms-appx： 配置，) 您做為 BitmapImage.UriSource。 在程式碼中，您不會取得將相對統一資源識別元 (URI) 元件和 ms-appx ：將 Source 指定為 XAML 屬性時自動發生的處理快捷方式。 相反地，您必須使用適當的配置明確地建構絕對統一資源識別項 (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 屬性。

注意

當Image控制項載入 XAML 頁面時，就會發生FrameworkElement.Loaded事件。 ImageOpened事件發生于映射控制項中開啟映射檔時。

以下是在 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 頁面的基底統一資源識別項 (URI) ，解譯相對統一資源識別元 (URI) 。 若要在程式碼中達到相同的結果，您可以使用其中一個建構函式來建構 URI ，此建構函式會藉由結合絕對基底和該位置內的相對路徑， (URI) 。 針對第一個參數，在載入Image的Page上呼叫BaseUri。 (您也可以在設定來源的Image實例上呼叫BaseUri，或在頁面上呼叫另一個專案。請參閱下列警告。) 這會使用ms-appx：配置建立統一資源識別項 (URI) ，並新增屬於 XAML 頁面位置一部分的路徑。 針對第二個參數，傳遞相對統一資源識別元 (URI) 字串，以描述來源影像位置。

在 C# 或 Microsoft Visual Basic 中， Uri 類型會投影為 System.Uri，因此請使用 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 = winrt::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(winrt::Windows::Foundation::Uri(BaseUri().AbsoluteUri(), L"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 ， 則 BaseUri 屬性會是 Null ，直到 Image 新增至頁面的視覺化樹狀結構為止。 例如，下列程式碼會擲回 ArgumentNull 例外狀況。 若要避免例外狀況，請先將 Image 新增至視覺化樹狀結構，再設定 Source 屬性。

這個範例會擲回例外狀況，因為它會在將 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);

Image img;
BitmapImage bitmapImage;

// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri(img.BaseUri(), L"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新增至頁面，如下所示。

在此範例中， Image 會在呼叫 BaseUri之前新增至頁面，因此 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;

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

BitmapImage bitmapImage;
// img.BaseUri in not null because img has been added to the page.
Uri uri(img.BaseUri(), L"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： 配置，如下所示。 (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"));

Image img;
img.Source(BitmapImage(Uri(L"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： 配置，如下所示。 (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;

使用串流來源顯示圖片媒體櫃中的影像

應用程式中 影像 元素的一般用法是顯示使用者圖片庫中的圖片。 這些圖片可以透過程式設計方式或透過 FileOpenPicker來存取。 不論是哪一種情況，您取得的 StorageFile 物件都可以以資料流程的形式開啟，但不會提供統一資源識別項 (URI) 映射檔的參考。 若要使用資料流程作為影像來源，您必須撰寫程式碼，以將 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;
        }
    }
}

此範例示範如何以程式設計方式從圖片庫存取影像檔，並將其設定為 影像 控制項的來源。 若要以程式設計方式存取圖片庫的內容，請呼叫 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 執行階段時看起來很棒。 將 影像 的來源指定為統一資源識別元 (URI) 時，您可以使用命名慣例，自動參考系統在執行時間偵測到之目前縮放比例的正確映射資源。 如需命名慣例的細節及其他資訊，請參閱快速入門：使用檔案或影像資源。

如需如何設計調整的詳細資訊，請參閱 螢幕大小和中斷點 或 影像中的。

影像來源和資源限定詞

您可以使用自動處理來存取具有目前縮放比例和文化特性限定詞的非限定資源，也可以使用 ResourceManager 和 ResourceMap 搭配文化特性和規模限定詞，直接取得資源。 如需詳細資訊，請參閱 資源管理系統 或 映射中的。 如需應用程式資源以及如何封裝應用程式中映射來源的詳細資訊，請參閱 定義應用程式資源。

適用於

另請參閱