定義和使用資源

5 分鐘

資源就像程式設計語言中的符號常數。您可以在一個地方定義它，然後在需要它的任何地方參考它。您的程式碼會更易於閱讀，因為您會使用描述性名稱，而不是 "magic" 值。如果需要變更值，您只需更新定義即可。

在此課程模組中，您會了解如何使用資源來消除 XAML 中的硬式編碼值。

什麼是資源？

資源是可跨 UI 共用的任何物件。最常見的範例包括字型、色彩與大小。不過，您也可以將 Style 和 OnPlatform 執行個體這類複雜物件儲存為資源。

您可以在 XAML 或程式碼中定義資源。然後將它套用在 XAML 或程式碼中。通常，您會完全使用 XAML，儘管我們稍後會向您展示一些程式碼有用的案例。

請考慮使用一個範例。假設您想要跨頁面上的控制項使用相同的 TextColor 值。如果您使用了硬式編碼值，則 XAML 將如下所示。請注意如何在兩個控制項中重複文字色彩的值。

<Label TextColor="Blue" FontSize="14">
<Button TextColor="Blue" FontSize="14">

您可以不重複該文字色彩，而是將它定義為資源。該定義看起來會像此 XAML：

<Color x:Key="PageControlTextColor">Blue</Color>

請注意，已定義的元素如何具有 x:Key 屬性，而此屬性提供資源的名稱。您可以使用此索引鍵來查閱 XAML 中的資源。

您必須先將資源儲存至資源字典，才能使用資源。

什麼是 ResourceDictionary？

ResourceDictionary 是一種為與 UI 資源一起使用而自訂的 .NET MAUI 程式庫類別。它是一個字典，因此它會儲存機碼/值組。索引鍵的類型會限制為 String，而值則可以是任何物件。

每個 .NET MAUI XAML 頁面都會有一個名為 Resources 的屬性，而此屬性可以保存 ResourceDictionary 物件。該屬性預設為 Null，因此您需要先建立字典執行個體，才能使用該屬性。下列程式碼顯示如何建立 ResourceDictionary 物件，並將其指派給 ContentPage 的 Resources 屬性：

<ContentPage.Resources>
    <ResourceDictionary>
        ...
    </ResourceDictionary>
</ContentPage.Resources>

.NET MAUI XAML 具有內建便利語法，只要您開始使用 Resources 屬性，就會自動建立字典執行個體。先前範例可以簡化為下列程式碼：

<ContentPage.Resources>
    ...
</ContentPage.Resources>

應用程式中的每個頁面都可以有自己的字典。您可以使用這些頁面特定的字典來儲存專用於該頁面的資源。

注意

頁面上的每個控制項也可以有自己的資源字典。例如，您可以將資源字典新增至 Label 控制項，如下所示：

<Label Text="Hello, World!"
        ...
        <Label.Resources>
           ...
        </Label.Resources>
</Label>

除了可保存子元素的版面配置和檢視之外，不常在控制項層級執行此動作。

建立資源

若要建立資源，請在頁面的 Resources 屬性內進行宣告。下列的範例會建立稍早所述的文字色彩資源

<ContentPage.Resources>
    <Color x:Key="PageControlTextColor">Blue</Color>
</ContentPage.Resources>

當您選取資源的索引鍵時，請選擇可反映使用量的名稱，而不是資源的值。例如，若要將標籤的背景設定為 [紅色]，請不要使用 RedColor 作為索引鍵，而是改用 BackgroundColor。

使用 StaticResource 來套用資源

StaticResource 是一個可在資源字典中查閱資源的標記延伸。您提供資源的機碼，而標記延伸則會傳回對應的值。下列的 XAML 標記所顯示的範例可建立和使用名為 PageControlTextColor 的 Color 資源。範例中 label 控制項的 XAML 標記使用 StaticResource 標記延伸來擷取值。

<ContentPage.Resources>
    <Color x:Key="PageControlTextColor">Blue</Color>
</ContentPage.Resources>

...

<Label TextColor="{StaticResource PageControlTextColor}" ... />

此延伸只會評估一次，因此稱為 StaticResource。字典查閱會在建立目標物件時發生。當字典中的資源值發生變更時，目標屬性並不會更新。

警告

如果找不到該索引鍵，則 StaticResource 會擲回執行階段例外狀況。

XAML 內建型別

此單元開頭所呈現的原始範例會設定 TextColor 屬性和 FontSize 屬性：

<Label TextColor="Blue" FontSize="14">
<Button TextColor="Blue" FontSize="14">

FontSize 的類型為 Double。若要為此值建立資源，您可以使用 XAML 規格中所定義的其中一種 XAML 內建類型。 XAML 規格可定義許多 C# 簡單類型的類型名稱。下列程式碼顯示每種內建型別的範例資源。

<ContentPage.Resources>
    <x:String x:Key="...">Hello</x:String>
    <x:Char x:Key="...">X</x:Char>
    <x:Single x:Key="...">31.4</x:Single>
    <x:Double x:Key="...">27.1</x:Double>
    <x:Byte x:Key="...">8</x:Byte>
    <x:Int16 x:Key="...">16</x:Int16>
    <x:Int32 x:Key="...">32</x:Int32>
    <x:Int64 x:Key="...">64</x:Int64>
    <x:Decimal x:Key="...">12345</x:Decimal>
    <x:TimeSpan x:Key="...">1.23:5959</x:TimeSpan>
    <x:Boolean x:Key="...">True</x:Boolean>
</ContentPage.Resources>

設定資源的平台特定值

通常在平台之間需要稍微調整應用程式的 UI。可定義平台特定值的標準方式，是在定義資源時使用 OnPlatform 物件。例如，下列程式碼顯示如何建立資源，而此資源在 iOS、Android、macOS (Mac Catalyst) 和 Windows (WinUI) 上參考不同的文字色彩。

<ContentPage.Resources>
    <OnPlatform x:Key="textColor" x:TypeArguments="Color">
        <On Platform="iOS" Value="Silver" />
        <On Platform="Android" Value="Green" />
        <On Platform="WinUI" Value="Yellow" />
        <On Platform="MacCatalyst" Value="Pink" />
    </OnPlatform> 
</ContentPage.Resources>
...

<Label TextColor="{StaticResource textColor}" ... />