共用方式為

圖像

  • 發行項

.NET 多平臺應用程式 UI （.NET MAUI） Image 會顯示可從本機檔案、URI 或數據流載入的影像。 支援標準平臺影像格式，包括動畫 GIF，也支援本機可調整向量圖形 （SVG） 檔案。 如需將映像新增至 .NET MAUI 應用程式專案的詳細資訊，請參閱 將映射新增至 .NET MAUI 應用程式專案。

Image 定義下列屬性：

  • Aspect，類型為 Aspect，定義影像的縮放模式。
  • 類型為 bool的 IsAnimationPlaying會決定動畫 GIF 正在播放或停止。 這個屬性預設值為 false。
  • IsLoading，類型為 bool，表示影像的載入狀態。 這個屬性預設值為 false。
  • IsOpaque，類型為 bool，表示轉譯引擎在轉譯時是否可能將影像視為不透明。 這個屬性預設值為 false。
  • Source，類型為 ImageSource，會指定影像的來源。

這些屬性是由 BindableProperty 物件所支援，這表示可以設定樣式，並成為數據系結的目標。

注意

字型圖示可以透過將字型圖示數據指定為 FontImageSource 物件，以 Image 顯示。 如需詳細資訊，請參閱 顯示字型圖示。

ImageSource 類別會定義下列方法，可用來從不同的來源載入影像：

  • FromFile 會傳回從本機檔案讀取影像的 FileImageSource。
  • FromUri 會傳回從指定 URI 下載和讀取影像的 UriImageSource。
  • FromStream 會傳回從提供影像數據的數據流讀取影像的 StreamImageSource。

在 XAML 中，影像可以從檔案和 URI 載入，方法是將檔名或 URI 指定為 Source 屬性的字串值。 您也可以透過自定義標記延伸，從 XAML 中的數據流載入影像。

重要

除非 Image 的大小受限於其版面配置，或指定 Image 的 HeightRequest 或 WidthRequest 屬性，否則影像會以其完整解析度顯示。

如需將應用程式圖示和啟動顯示畫面新增至應用程式的相關信息，請參閱 應用程式圖示 和 啟動顯示畫面。

載入本機映像

您可以將圖片拖曳至專案的 Resources\Images 資料夾，圖片的建置動作會自動設定為 MauiImage，使其新增至您的應用程式專案。 在建置階段，向量影像會調整為目標平臺和裝置的正確解析度，並新增至您的應用程式套件。 這是必要的，因為不同的平台支援不同的映射解析度，而作系統會根據裝置的功能在運行時間選擇適當的映射解析度。

若要符合 Android 資源命名規則，所有本機影像檔名都必須是小寫、開頭和結尾為字母字元，且只包含英數位元或底線。 如需詳細資訊，請參閱 應用程式資源概觀 developer.android.com。

重要

.NET MAUI 會將 SVG 檔案轉換成 PNG 檔案。 因此，將 SVG 檔案新增至 .NET MAUI 應用程式專案時，應該從具有 .png 擴展名的 XAML 或 C# 加以參考。

遵循這些檔案命名和放置規則，可讓下列 XAML 載入和顯示影像：

<Image Source="dotnet_bot.png" />

對等的 C# 程式代碼為：

Image image = new Image
{
    Source = ImageSource.FromFile("dotnet_bot.png")
};

ImageSource.FromFile 方法需要 string 自變數，並傳回從檔案讀取影像的新 FileImageSource 物件。 另外還有一個隱含轉換運算符，可以將檔名指定為 string 參數，並應用到 Image.Source 屬性中。

Image image = new Image { Source = "dotnet_bot.png" };

載入遠端映像

您可以藉由指定 URI 做為 Source 屬性的值來下載並顯示遠端影像：

<Image Source="https://aka.ms/campus.jpg" />

對等的 C# 程式代碼為：

Image image = new Image
{
    Source = ImageSource.FromUri(new Uri("https://aka.ms/campus.jpg"))
};

ImageSource.FromUri 方法需要 Uri 自變數，並傳回從 Uri讀取影像的新 UriImageSource 物件。 字串型 URI 也有隱含轉換：

Image image = new Image { Source = "https://aka.ms/campus.jpg" };

圖像快取

默認會啟用已下載映像的快取，快取的映像會儲存 1 天。 設定 UriImageSource 類別的屬性，即可變更此行為。

UriImageSource 類別會定義下列屬性：

  • Uri，為 Uri類型，代表用於顯示的待下載影像的 URI。
  • 類型為 TimeSpan的 CacheValidity指定了將圖像儲存在本機的時間長度。 此屬性的預設值為1天。
  • CachingEnabled，類型為 bool，定義是否啟用影像快取。 這個屬性預設值為 true。

這些屬性是由 BindableProperty 物件所支援，這表示可以設定樣式，並成為數據系結的目標。

若要設定特定的快取期間，請將 Source 屬性設定為一個設定其 CacheValidity 屬性的 UriImageSource 物件。

<Image>
    <Image.Source>
        <UriImageSource Uri="https://aka.ms/campus.jpg"
                        CacheValidity="10:00:00:00" />
    </Image.Source>
</Image>

對等的 C# 程式代碼為：

Image image = new Image();
image.Source = new UriImageSource
{
    Uri = new Uri("https://aka.ms/campus.jpg"),
    CacheValidity = new TimeSpan(10,0,0,0)
};

在此範例中，快取期間被設為10天。

從數據流載入影像

您可以使用 ImageSource.FromStream 方法從資料流載入影像：

Image image = new Image
{
    Source = ImageSource.FromStream(() => stream)
};

重要

使用 ImageSource.FromStream 方法從數據流載入影像時，Android 上會停用影像快取。 這是因為缺少建立合理快取索引鍵的數據。

載入字型圖示

FontImage 標記延伸允許您在任何能顯示 ImageSource的檢視中顯示字型圖示。 它提供與 FontImageSource 類別相同的功能，但具有更簡潔的表示法。

FontImageExtension 類別支援 FontImage 標記延伸，其定義下列屬性：

  • FontFamily 類型 string，字型圖示所屬的字型系列。
  • Glyph 類型為 string，字型圖示的 Unicode 字元碼值。
  • Color 類型為 Color，顯示字型圖示時要使用的色彩。
  • Size 類型為 double，其尺寸是以裝置獨立單位顯示的已渲染字型圖示。 預設值為 30。 此外，這個屬性也可以設定為指定字型大小。

注意

XAML 剖析器可讓 FontImageExtension 類別縮寫為 FontImage。

Glyph 屬性是 FontImageExtension的內容屬性。 因此，對於以大括號表示的 XAML 標記表示式，您可以排除表示式 Glyph= 部分，前提是它是第一個自變數。

下列 XAML 範例示範如何使用 FontImage 標記延伸：

<Image BackgroundColor="#D1D1D1"
       Source="{FontImage &#xf30c;, FontFamily=Ionicons, Size=44}" />

在這個例子中，FontImageExtension 類別名稱的縮寫版本被用來在 Image中顯示 XBox 圖示，來自 Ionicons 字型系列。

FontImage 標記擴充功能的螢幕快照。

雖然圖示的 unicode 字元是 \uf30c，但它必須在 XAML 中逸出，因此會變成 &#xf30c;。

如需在 FontImageSource 物件中指定字型圖示資料來顯示字型圖示的相關信息，請參閱 顯示字型圖示。

在 FontImageSource 物件中指定字型圖示數據，即可顯示字型圖示。 如需詳細資訊，請參閱 顯示字型圖示。

載入動畫 GIF

.NET MAUI 包含顯示小型動畫 GIF 的支援。 這可藉由將 Source 屬性設定為動畫 GIF 檔案來完成：

<Image Source="demo.gif" />

重要

雖然 .NET MAUI 中的動畫 GIF 支援包含下載檔的能力，但它不支援快取或串流動畫 GIF。

根據預設，載入動畫 GIF 時，將不會播放。 這是因為 IsAnimationPlaying 屬性，控制動畫 GIF 是否正在播放或停止，其預設值為 false。 因此，載入動畫 GIF 時，除非將 IsAnimationPlaying 屬性設定為 true，否則不會播放。 將 IsAnimationPlaying 屬性重設為 false，即可停止播放。 請注意，當顯示非 GIF 影像來源時，這個屬性沒有任何作用。

控制影像縮放比例

Aspect 屬性會決定影像的縮放方式，以符合顯示區域，而且應該設定為 Aspect 列舉的其中一個成員：

  • AspectFit - 如果需要，會在影像的頂端/底部或側邊增加黑邊，使整個影像符合顯示區域，空白空間的添加取決於影像的寬度或高度。
  • AspectFill - 裁剪圖像，以填滿顯示區域，同時保留寬高比。
  • Fill - 延展影像以完整且完全填滿顯示區域。 這可能會導致影像扭曲。
  • Center - 將影像置於顯示區域的中央，同時保持外觀比例。