Image 類別

定義

public ref class Image sealed : FrameworkElement

/// [Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Microsoft.UI.Xaml.WinUIContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class Image final : FrameworkElement

[Windows.Foundation.Metadata.Activatable(65536, "Microsoft.UI.Xaml.WinUIContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Microsoft.UI.Xaml.WinUIContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class Image : FrameworkElement

Public NotInheritable Class Image
Inherits FrameworkElement

<Image .../>

繼承

Object Platform::Object IInspectable DependencyObject UIElement FrameworkElement Image

屬性

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

範例

WinUI 3 Gallery 應用程式包含大部分 WinUI 3 控制項、特性和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 GitHub 上取得原始程式碼。

備註

影像檔案格式

影像可以顯示以下影像檔案格式：

• 聯合影像專家組 (JPEG)
• 可攜式網路圖形 （PNG）
• 點陣圖 (BMP)
• 圖形交換格式 (GIF)
• 標記的影像檔案格式 （TIFF）
• JPEG XR
• 圖示 (ICO)
• 可縮放向量圖形 (SVG)

Image 元素支援動畫圖形交換格式（GIF）影像。 當你使用 BitmapImage 作為影像 來源時，可以存取 BitmapImage API 來控制動畫圖形交換格式（GIF）影像的播放。 如需詳細資訊，請參閱 BitmapImage 類別頁面。

Image 元素支援透過 SvgImageSource 的靜態可縮放向量圖形（SVG）影像。 SvgImageSource 支援 SVG 規範中的安全靜態模式，且不支援動畫或互動。 Direct2D 提供底層的 SVG 渲染支援，關於特定 SVG 元素與屬性支援的更多資訊，請參見 SVG 支援。 想了解更多如何在應用程式中插入 SVG，請造訪 SvgImageSource 類別頁面。

設定圖片來源

要設定圖片所顯示的影像原始碼檔案，你可以設定它的 原始碼 屬性，可以是用 XAML 或程式碼。 這裡有一個簡單的 XAML 設定 Source 範例：

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

這種用法是透過統一資源識別碼（URI）設定 來源 ，這是 XAML 啟用的捷徑。 請注意，這裡的統一資源識別碼（URI）似乎是相對的統一資源識別碼（URI）;支援部分統一資源識別碼（URI）是另一個 XAML 捷徑。 此統一資源識別碼（URI）的根節點是應用程式專案的基礎資料夾。 這通常是載入包含 Image 標籤的 XAML 檔案的同一個位置。 在這個例子中，影像來源檔案位於應用程式檔案結構中的 Images 子資料夾中。

設定 Source 屬性本質上是一個非同步動作。 因為這是屬性，沒有明確的語法，但大多數情況下你不需要處理影像載入的非同步部分。 框架會等待影像來源回傳，當影像原始檔案可用並解碼後，會開始版面設計循環。

將來源設定為無法解析為有效影像原始碼檔案的統一資源識別碼（URI）值，並不會拋出例外。 取而代之的是，它會觸發 一個 ImageFailed 事件。 你可以寫一個 ImageFailed 處理器並將其附加到 Image 物件上，並可能利用事件資料中的 ErrorMessage 來判斷失敗的性質。 解碼錯誤也可能觸發 ImageFailed。 如果你想驗證影像來源檔案是否正確載入，可以在影像元素上處理 ImageOpened 事件。

你通常會使用你附在應用程式下載套件中的圖片來源檔案。 對於大型檔案，若是首次使用原始檔案，解碼時可能會有非常小的延遲。 欲了解更多應用程式資源及如何在應用程式套件中打包影像原始檔案，請參閱 定義應用程式資源。

你也可以使用應用程式以外的圖片來源檔案，例如來自外部伺服器的圖片。 這些映像檔由內部 HTTP 請求下載，然後解碼。 如果影像原始檔案是大型檔案，或有連線問題，外部影像在影像元素中顯示可能會有延遲。

使用程式碼設定 Image.Source

如果你用程式碼建立 Image 物件，呼叫預設建構子，然後設定 Image.Source 屬性。 設定 Image.Source 屬性需要一個 BitmapImage 類別的實例，而你也必須建構這個類別。 如果你的影像來源是由統一資源識別碼（URI）參考的檔案，請使用採用統一資源識別碼（URI）參數的 BitmapImage 建構器。 當你參考本地內容時，必須在你作為 BitmapImage 建構參數的絕對統一資源識別碼（URI）中包含 ms-appx： 方案。 在程式碼中，你不會有將相對的統一資源識別碼（URI）部分合併的處理捷徑，以及如果你指定 Source 為 XAML 屬性時會自動發生的 ms-appx： 方案。 相反地，你必須明確構建一個絕對統一資源識別碼（URI），並搭配相應的方案。 你通常會用 ms-appx： 方案來處理作為應用程式一部分的圖片檔案。

這裡有一個在 C# 中設定 Image.Source 的範例。 在這個例子中，Image 物件是以 XAML 建立的，但沒有原始碼或其他屬性值;這些值會在從 XAML 載入映像檔的執行時提供。

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
    // don't need to set Height, system maintains aspect ratio, and calculates the other
    // dimension, so long as one dimension measurement is provided
    bitmapImage.UriSource = new Uri(img.BaseUri,"Assets/StoreLogo.png");
    img.Source = bitmapImage;
}

使用串流來源作為影像來源

如果你的映像來源是串流，你必須寫程式碼設定你的映像實例使用串流。 這無法僅靠 XAML 完成。 建構映像檔以使用，或參考現有的映像實例（該實例可能在 XAML 標記中定義，但沒有來源）。 接著使用 BitmapImage 的非同步 SetSourceAsync 方法，定義串流中的影像資訊，並將串流傳遞作為 streamSource 參數。 使用串流作為影像來源相當常見。 例如，如果你的應用程式允許使用者使用 FileOpenPicker 控制項選擇影像檔案，代表該檔案的物件可以作為串流開啟，但不會提供該檔案的統一資源識別碼（URI）參考。

在這個例子中，程式碼已經是可等待的，因為它正在等待使用者選擇檔案，且只有在選擇檔案後才會執行。 要使用的串流會從 StorageFile.OpenAsync 從非同步選擇器動作回傳 StorageFile 實例後取得。

FileOpenPicker open = new FileOpenPicker(); 
// Open a stream for the selected file 
StorageFile file = await open.PickSingleFileAsync(); 
// Ensure a file was selected 
if (file != null) 
{ 
    using (IRandomAccessStream fileStream = await file.OpenAsync(Windows.Storage.FileAccessMode.Read)) 
    { 
        // Set the image source to the selected bitmap 
         BitmapImage bitmapImage = new BitmapImage(); 
         bitmapImage.DecodePixelWidth = 600; //match the target Image.Width, not shown
         await bitmapImage.SetSourceAsync(fileStream); 
         Scenario2Image.Source = bitmapImage; 
    } 
}

更多範例程式碼請參見 XAML 圖片範例 。

影像檔與效能

大型影像檔案會影響效能，因為它們會載入記憶體。 如果你參考的是一張圖片檔案，知道來源檔案是一張大型高解析度圖片，但你的應用程式顯示在一個比圖片自然大小還小的 UI 區域，你應該設定 DecodePixelWidth 屬性，或 DecodePixelHeight。 DecodePixel* 屬性允許您直接將資訊傳送給格式專用的編解碼器，編解碼器能利用這些資訊更有效率地解碼，並減少記憶體佔用。 把 DecodePixelWidth 設定成你想讓應用程式實際顯示的區域的像素寬度。 換句話說，BitmapImage 來源的 DecodePixelWidth 應該與顯示該來源的 Image 控制項的 Width 或 Width（實際寬度）值相同。

你可以設定 DecodePixelWidth，或設定 DecodePixelHeight。 如果你設定這兩個屬性中的一個，系統會計算匹配屬性以維持正確的長寬比。 你也可以同時設定兩個屬性，但通常應該使用維持該長寬比的數值。 如果你想改變長寬比，有更好的方法，例如用 TranslateTransform 當作 RenderTransform。

要在 XAML 中設定 DecodePixelWidth （或 DecodePixelHeight），你必須使用稍微冗長一點的 XAML 語法，並且包含明確的 BitmapImage 元素作為屬性元素值，如下：

<Image>
  <Image.Source>
    <BitmapImage DecodePixelWidth="200" UriSource="images/myimage.png"/>
  </Image.Source>
</Image>

DecodePixelWidth （或 DecodePixelHeight）是 BitmapImage 的屬性，因此你需要一個明確的 BitmapImage XAML 物件元素，才能在 XAML 中設定 DecodePixel* 屬性。

如果你在程式碼中建立 Image 實例，你很可能已經在建立一個 BitmapImage 實例作為 Source 屬性的值，所以在設定 UriSource 屬性之前，先在 BitmapImage 實例上設定 DecodePixelWidth（或 DecodePixelHeight）。 DecodePixelType 屬性也會影響解碼操作對像素值的解讀。

為防止影像被解碼超過一次，請盡可能將影像來源屬性指派於統一資源識別碼（URI），而非使用記憶體串流。 XAML 框架可以在多個地方與一個解碼映像關聯相同的統一資源識別碼（URI），但即使包含相同資料，也無法對多個記憶體串流做到同樣的事。

你可以將所有相關的 Image.Source 值設為 空值，從影像快取中移除影像檔案。

欲了解更多關於影像類別與效能的資訊，請參閱 「優化動畫與媒體」。

影像檔案編碼與解碼

影像檔案的底層編碼支援由 Windows 影像元件（WIC）API 提供。 如需更多關於編解碼器特定影像格式的資訊，請參閱 原生 WIC 編碼器。

Image、 BitmapImage 和 BitmapSource 的 API 並不包含任何專門用於媒體格式編碼與解碼的方法。 所有解碼操作皆內建於設定或重置來源時所執行的動作。 這使得類別在建構 UI 時更容易使用，因為它們預設有一套支援的原始碼檔案格式和解碼行為。 像 BitmapImage 這類類別會將部分解碼選項和邏輯作為 ImageOpened 或 ImageFailed 事件的事件資料一部分。 如果你需要進階的影像檔案解碼或影像編碼，應該使用 Windows 的 API。Graphics.Imaging命名空間。 如果你的應用程式涉及圖片檔案格式轉換，或是圖片操作，使用者可以將結果儲存成檔案，你可能需要這些 API。 編碼 API 也被 Windows 的 Windows 影像元件（WIC）支援。

影像 寬度與高度

Image 類別繼承了 FrameworkElement 的 Width 和 Height 屬性，這些屬性可能控制 Image 控件在 UI 顯示時所渲染的大小。 如果你沒有設定 寬度 或 高度，那麼寬度和高度會由影像來源的自然大小決定。 例如，若你載入一張高300像素、寬400像素的點陣圖，依原始檔案格式記錄，這些測量值用於影像控制計算其自然大小時的寬度與高度。 你可以在影像渲染後的執行時檢查 ActualHeight 和 ActualWidth ，取得測量資訊。 或者，你可以處理 ImageOpened，並在影像渲染前立即檢查影像檔案屬性，如 PixelHeight 和 PixelWidth。

如果你只設定其中一個 寬度 或高度屬性，但不 設 兩個屬性，系統就可以用該維度作為指引，計算另一個維度，保持長寬比。 如果你不確定原始檔案的尺寸，可以選擇在佈局情境中最需要控制的尺寸，讓系統計算另一個尺寸，然後容器的佈局行為通常會調整配置以配合。

如果你沒有設定 寬度 和/或 高度，且保持圖片的自然大小，圖片的 拉伸 屬性可以控制圖片來源檔案如何填滿你指定的 寬度 和 高度空間。 預設的 拉伸 值為 統一，當影像放入版面容器時，會保持長寬比。 如果容器的尺寸不相同，就會有空位仍屬於影像，但不會顯示任何影像像素，至少在使用 Stretch 的 Uniform 值時是這樣。 UniformToFill for Stretch 不會留下空白，但如果尺寸不同，可能會裁剪影像。 Stretch 的填充不會留下空白，但可能會改變長寬比。 你可以嘗試這些數值，看看在你的版面配置中，哪個值最適合顯示影像。 另外，請注意，某些版面容器可能會對沒有特定 寬 度和 高度 的圖片進行尺寸調整，無法填滿整個版面空間，這時你可以選擇在圖片或容器上設定特定尺寸。

NineGrid

使用 NineGrid 技術是另一種選擇，可以調整與顯示區域自然大小不同的影像大小，若影像有不應該均勻縮放的區域。 舉例來說，你可以使用一張背景圖片，其內在邊框只應該在一維上拉伸，角落則完全不應該被拉伸，但影像中心可以在兩維度中拉伸以符合版面需求。 更多資訊請參見 NineGrid。

影像資源資格與本地化

影像 來源檔案與縮放

你應該建立多個建議大小的圖片來源，以確保 Windows 放大時你的應用程式看起來很棒。 在指定映像 來源 時，你可以使用資源命名慣例，以符合裝置特定的縮放因子。 這是應用程式在執行時自動決定的。 關於命名慣例的細節及更多資訊，請參見 快速入門：使用檔案或映像資源。

想了解如何正確設計圖片以進行縮放，請參閱版 面與縮放的使用者體驗指引。

使用不合格的資源

未限定資源是一種技術，基本資源參考指向預設資源，資源管理流程能自動找到相應的在地資源。 你可以使用自動處理來存取帶有當前規模與文化限定條件的未合格資源，或使用 ResourceManager 和 ResourceMap 的文化與規模限定條件直接取得資源。 如需詳細資訊，請參閱資源管理系統。

影像的 FlowDirection

如果你將 FlowDirection 設定為 RightToLeft ，圖片的視覺內容會被水平翻轉。 然而，影像元素不會繼承任何父元素的 FlowDirection 值。 通常你只希望在與版面設計相關的圖片中出現圖片翻轉行為，而不一定是那些嵌入文字或其他對從右到左的觀眾來說不合理的元素。 要達到影像翻轉的行為，你必須將 Image 元素的 FlowDirection 設定為 RightToLeft，或在 code-behind 中設定 FlowDirection 屬性。 考慮以 x：Uid 指令來識別影像元素，並將 FlowDirection 值指定為Windows 執行階段資源，這樣你的在地化專家日後可以在不更改 XAML 或程式碼的情況下更改此值。

Image 類別與無障礙性

影像類別並非真正的控制類別，因為它不是 控制的後代類別。 你不能呼叫焦點到影像元素，或是把影像元素放在制表序列中。 關於使用圖片及 UI 中圖片元素的無障礙資訊，請參閱 基本無障礙資訊。

圖片資源

資源可以使用資源限定符模式，根據裝置特定的縮放方式載入不同的資源。 任何原本為你的應用程式擷取的資源，如果在應用程式執行時縮放因子改變，都會自動重新評估。 此外，當該資源是影像物件的影像來源時，系統請求新資源並將其套用到映像檔時，會觸發其中一個原始碼載入事件（ImageOpened 或 ImageFailed）。 執行時尺度變更的情況是，當使用者將應用程式移至不同螢幕時，且螢幕多於一台可用。 因此，當處理尺度變更時，即使原始碼設定為 XAML，也可能在執行時發生 ImageOpened 或 ImageFailed 事件。

另請參閱

• FrameworkElement
• BitmapSource
• FlowDirection
• Source
• Image 與 ImageBrush
• XAML 影像範例
• 優化動畫與媒體
• Windows.Graphics.Imaging
• 動畫 GIF 播放（XAML）範例（Windows 10）