共用方式為

影像與影像筆刷

  • 發行項

若要顯示影像，可以使用 Image 物件或 ImageBrush 物件。 Image 物件會轉譯影像，ImageBrush 物件會用影像繪製另一個物件。

這些是正確的元素嗎？

使用 Image 元素在您的應用程式中顯示獨立的影像。

使用 ImageBrush 將影像套用到另一個物件。 ImageBrush 的用途包括文字的裝飾效果，或控制項或版面配置容器的背景。

UWP 和 WinUI 2

重要

本文中的資訊和範例針對使用 Windows App SDK 和 WinUI 3 的應用程式進行了最佳化，但通常適用於使用 WinUI 2 的 UWP 應用程式。 如需平台特定資訊和範例，請參閱 UWP API 參考。

本節包含您在 UWP 或 WinUI 2 應用程式中使用控制項所需的資訊。

此控制項的 API 位於 Windows.UI.Xaml.Controls 和 Windows.UI.Xaml.Media 命名空間中。

建議使用最新的 WinUI 2 來取得所有控制項的最新樣式和範本。

從 Windows 10 版本 1607 開始，Image 元素支援動畫 GIF 影像。 當您使用 BitmapImage 作為影像 Source 時，您可以存取 BitmapImage API 來控制播放動畫 GIF 影像。 如需詳細資訊，請參閱 BitmapImage 類別頁面。

注意

當您的應用程式是針對 Windows 10 版本 1607 進行編譯，並在版本 1607 (或更新版本) 上執行時，即可支援動畫 GIF。 當您的應用程式針對早期版本進行編譯或執行時，會顯示 GIF 的第一個畫面，但不會以動畫顯示。

建立映像

開啟 WinUI 3 資源庫應用程式，並查看 ImageBrushes 運作情形。

WinUI 3 資源庫應用程式包含大多數 WinUI 3 控制項和功能的互動式範例。 從 Microsoft Store 取得應用程式，或在 GitHub 上取得原始程式碼

映像

此範例示範如何使用 Image 物件建立影像。

<Image Width="200" Source="sunset.jpg" />

這是轉譯的 Image 物件。

image 元素的範例

在此範例中，Source 屬性指定要顯示影像的位置。 您可以指定絕對 URL (例如 http://contoso.com/myPicture.jpg) 或指定相對於應用程式封裝結構的 URL，以設定 Source。 在我們的範例中，我們將「sunset.jpg」影像檔案放在專案的根資料夾中，並將包含該影像檔案的項目設定宣告為內容。

ImageBrush \(英文\)

透過 ImageBrush 物件，您可以使用影像來繪製採用 Brush 物件的區域。 例如，您可以使用 ImageBrush 當作 Ellipse 的 Fill 屬性值，或是 Canvas 的 Background 屬性值。

下一個範例示範如何使用 ImageBrush 繪製橢圓。

<Ellipse Height="200" Width="300">
   <Ellipse.Fill>
     <ImageBrush ImageSource="sunset.jpg" />
   </Ellipse.Fill>
</Ellipse>

這是由 ImageBrush 繪製的橢圓。

ImageBrush 繪製的橢圓形。

延展影像

如果未設定 Image 的 Width 或 Height 值，則會以 Source 指定的影像維度顯示。 設定寬度和高度會建立一個包含影像的矩形區域。 您可以使用 Stretch 屬性指定影像填入此包含區域的方式。 Stretch 屬性會接受 Stretch 列舉定義的以下值：

  • 注意：影像不會延展以填滿整個輸出尺寸。 請小心此延展設定：如果來源影像大於包含區域，則會裁剪您的影像，這通常不太理想，因為您無法像特意使用 Clip 那樣對檢視區進行任何控制。
  • Uniform：影像縮放到適合輸出尺寸。 但會保留內容的外觀比例。 這是預設值。
  • UniformToFill：縮放影像以完全填滿整個輸出區域，但仍保留原始的外觀比例。
  • Fill：影像縮放到適合輸出尺寸。 因為內容的高度和寬度會分開縮放，所以可能不會保留影像的原始外觀比例。 也就是說，可能會扭曲影像以完全填滿輸出區域。

延展設定的範例。

裁剪影像

您可以使用 Clip 屬性從影像輸出裁剪區域。 您可以將 Clip 屬性設定為 Geometry。 目前不支援非矩形裁剪。

下一個範例示範如何使用 RectangleGeometry 作為影像的裁剪區域。 在此範例中，我們會定義一個高度為 200 的 Image 物件。 RectangleGeometry 定義將要顯示影像區域的矩形。 Rect 屬性設定為「25,25,100,150」，其定義了一個從位置「25,25」開始、寬度為 100、高度為 150 的矩形。 只有矩形區域內的影像部分才會顯示。

<Image Source="sunset.jpg" Height="200">
    <Image.Clip>
        <RectangleGeometry Rect="25,25,100,150" />
    </Image.Clip>
</Image>

以下是在黑色背景上的裁剪影像。

由 RectangleGeometry 裁剪的 Image 物件。

套用不透明度

您可以對影像套用不透明度，使影像以半透明呈現。 不透明度值從 0.0 到 1.0，其中 1.0 是完全不透明，0.0 是完全透明。 此範例示範如何將 0.5 的不透明度套用至影像。

<Image Height="200" Source="sunset.jpg" Opacity="0.5" />

以下是不透明度為 0.5 的轉譯影像，且透過部分不透明度顯示黑色背景。

具有 .5 不透明度的 Image 物件。

影像檔案格式

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

  • Joint Photographic Experts Group (JPEG)
  • Portable Network Graphics (PNG)
  • 點陣圖 (BMP)
  • 圖形交換格式 (GIF)
  • 標記的影像檔案格式 (TIFF)
  • JPEG XR
  • 圖示 (ICO)

Image、BitmapImage 和 BitmapSource 的 API 不包含任何用於媒體格式編碼和解碼的專用方法。 所有編碼和解碼作業都是內建的，並且最多將編碼或解碼的各個方面作為載入事件的事件資料一部分來呈現。 如果您想要對影像編碼或解碼執行任何特殊工作 (如果您的應用程式正在執行影像轉換或操作，則可能會使用這些工作)，則應使用 Windows.Graphics.Imaging 命名空間中提供的 API。 Windows 中的 Windows Imaging Component (WIC) 也支援這些 API。

有關應用程式資源以及如何在應用程式中封裝影像來源的更多資訊，請參閱載入自訂比例、主題、高對比度等的影像和資源。

WriteableBitmap

WriteableBitmap 提供可修改的 BitmapSource，並且不使用 WIC 的基本檔案型解碼。 您可以動態變更影像，並重新轉譯更新後的影像。 若要定義 WriteableBitmap 的緩衝內容，可使用 PixelBuffer 屬性存取緩衝，然後使用資料流或特定語言緩衝類型填滿。 如需範例程式碼，請參閱 WriteableBitmap。

RenderTargetBitmap

RenderTargetBitmap 類別可以從正在執行的應用程式擷取 XAML UI 樹狀結構，然後表示點陣圖影像來源。 擷取後，此影像來源可套用至應用程式的其他部分，由使用者儲存為資源或應用程式資料，或用於其他情境。 其中一個特別有用的情境是為導覽配置建立 XAML 頁面的執行階段縮圖。 RenderTargetBitmap 對擷取影像中顯示的內容有一些限制。 如需詳細資訊，請參閱 RenderTargetBitmap 的 API 參考主題。

影像來源和縮放比例

您應該以幾種建議的尺寸建立影像來源，以確保您的應用程式在 Windows 縮放時擁有適當的外觀。 指定影像來源時，您可以使用命名慣例，其將自動參考目前縮放的正確資源。 有關命名慣例的詳細資料和更多資訊，請參閱快速入門：使用檔案或影像資源。

有關如何設計縮放比例的詳細資訊，請參閱版面配置和縮放比例 UX 指南。

程式碼中的 Image 和 ImageBrush

通常會使用 XAML 而不是程式碼來指定 Image 和 ImageBrush 元素。 這是因為這些元素通常是設計工具的輸出，作為 XAML UI 定義的一部分。

如果使用程式碼定義 Image 或 ImageBrush，請使用預設建構函式，然後設定相關的來源屬性 )Image.Source 或 ImageBrush.ImageSource)。 當您使用程式碼設定來源屬性時，需要的是 BitmapImage (而不是 URI)。 如果您的來源是資料流，則使用 SetSourceAsync 方法初始化該值。 如果您的來源是 URI，包含應用程式中使用 ms-appx 或 ms-resource 配置的內容，則使用採用 URI 的 BitmapImage 建構函式。 如果有任何與影像來源的擷取或解碼相關的時機問題，您也可以考慮處理 ImageOpened 事件，在這種情況下，您可能需要在影像來源可供使用前先顯示替代內容。 有關範例程式碼，請參閱 WinUI Gallery 範例。

注意

如果您使用程式碼建立影像，可以使用自動處理，以目前的比例和文化限定詞存取不完整的資源，或使用 ResourceManager 和 ResourceMap 搭配文化和比例的限定詞，以直接取得資源。 如需詳細資訊，請參閱資源管理系統。

取得範例程式碼