映像

  • 發行項

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

Image 會定義下列屬性：

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

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

注意

藉由將字型圖示資料指定為 FontImageSource 物件，即可顯示 Image 字型圖示。 如需詳細資訊，請參閱 顯示字型圖示 。

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

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

在 XAML 中，您可以將檔案名或 URI 指定為 屬性的 Source 字串值，以從檔案和 URI 載入影像。 您也可以透過自訂標記延伸，從 XAML 中的資料流程載入影像。

重要

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

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

載入本機映射

您可以將影像拖曳至您專案的 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。
  • CacheValidity型 TimeSpan 別為 的 ，會指定將映射儲存在本機的時間長度。 此屬性的預設值為 1 天。
  • CachingEnabled型 bool 別為 的 ，定義是否啟用映射快取。 此屬性的預設值為 true。

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

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

<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 類別相同的功能，但提供更簡潔的標記法。

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

  • 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 縮寫版本是用來在 中顯示 XBox 圖示，來自 Atedons 字型系列： Image

Screenshot of the FontImage markup extension.

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

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

載入動畫 GIF

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

<Image Source="demo.gif" />

重要

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

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

控制影像縮放比例

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

  • AspectFit - 信箱影像（如有需要），讓整個影像符合顯示區域，並將空白空間新增至頂端/底部或側邊，視影像寬或高而定。
  • AspectFill - 裁剪影像使其填滿顯示區域，同時保留外觀比例。
  • Fill - 完全自動縮放影像並剛好填滿顯示區域。 這可能會導致影像扭曲。
  • Center - 將影像置中顯示區域，同時保留外觀比例。