XAML 標記延伸

發行項
09/25/2024

.NET 多平臺應用程式 UI （.NET MAUI） XAML 標記延伸可讓屬性設定為從其他來源間接參考的物件或值。 XAML 標記延伸對於共用對象和參考整個應用程式中使用的常數特別重要，但它們在數據系結中找到其最大的公用程式。

一般而言，您可以使用 XAML 將物件的屬性設定為明確的值，例如字串、數位、列舉成員，或轉換成幕後值的字串。不過，有時候，屬性必須改為參考在其他位置定義的值，或者可能需要在運行時間透過程式代碼處理一點。針對這些用途，可以使用 XAML 標記延伸 。

XAML 標記延伸因此命名，因為它們是由實作的 IMarkupExtension類別中的程式碼所支援。您也可以撰寫自己的自訂標記延伸。

在許多情況下，XAML 標記延伸在 XAML 檔案中可立即辨識，因為它們會以大括號 { 和 }分隔的屬性值出現，但有時標記延伸也會以傳統元素的形式出現在標記中。

重要

標記延伸可以有屬性，但是它們不會像 XML 屬性一樣設定。在標記延伸中，屬性設定會以逗號分隔，而且大括弧內不會顯示引號。

共用的資源

某些 XAML 頁面包含數個檢視，其中屬性設定為相同的值。例如，這些 Button 物件的許多屬性設定都相同：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.SharedResourcesPage"
             Title="Shared Resources Page">
    <StackLayout>
        <Button Text="Do this!"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                BorderWidth="3"
                Rotation="-15"
                TextColor="Red"
                FontSize="24" />
        <Button Text="Do that!"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                BorderWidth="3"
                Rotation="-15"
                TextColor="Red"
                FontSize="24" />
        <Button Text="Do the other thing!"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                BorderWidth="3"
                Rotation="-15"
                TextColor="Red"
                FontSize="24" />
    </StackLayout>
</ContentPage>

如果需要變更其中一個屬性，您可能偏好只進行一次變更，而不是三次變更。如果這是程式代碼，您可能會使用常數和靜態只讀對象，協助保持這類值一致且易於修改。

在 XAML 中，一個熱門的解決方案是將這類值或物件儲存在資源字典中。類別 VisualElement 會定義名為 Resources 類型的 ResourceDictionary屬性，這是具有型 string 別索引鍵和型 object別值的字典。您可以將物件放入此字典中，然後從標記參考它們，全部都在 XAML 中。

若要在頁面上使用資源字典，請在頁面頂端包含一對 Resources 屬性元素標記，並在這些標籤新增資源。各種類型的物件和值可以新增至資源字典。這些類型必須具現化。例如，它們不能是抽象類。這些類型也必須有公用無參數建構函式。每個專案都需要以 x:Key 屬性指定的字典索引鍵：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.SharedResourcesPage"
             Title="Shared Resources Page">
    <ContentPage.Resources>
        <LayoutOptions x:Key="horzOptions"
                       Alignment="Center" />
        <LayoutOptions x:Key="vertOptions"
                       Alignment="Center" />
    </ContentPage.Resources>
    ...
</ContentPage>

在此範例中，這兩個資源是結構類型的 LayoutOptions值，而且每個資源都有唯一索引鍵和一或兩個屬性集。在程式代碼和標記中，使用的 LayoutOptions靜態字段比較常見，但在這裡，設定屬性比較方便。

注意

選擇性 ResourceDictionary 標籤可以包含為標記的 Resources 子系。

然後，物件可以使用 Button XAML 標記延伸來設定其 HorizontalOptions 和 VerticalOptions 屬性，來取用StaticResource資源：

<Button Text="Do this!"
        HorizontalOptions="{StaticResource horzOptions}"
        VerticalOptions="{StaticResource vertOptions}"
        BorderWidth="3"
        Rotation="-15"
        TextColor="Red"
        FontSize="24" />

標記 StaticResource 延伸一律以大括號分隔，並包含字典索引鍵。 StaticResource名稱會區分它與 DynamicResource，.NET MAUI 也支援此名稱。 DynamicResource 適用於與在運行時間可能會變更之值的字典索引鍵，而 StaticResource 只會在建構頁面上的專案時，從字典存取元素一次。每當 XAML 剖析器遇到 StaticResource 標記延伸時，就會搜尋可視化樹狀結構，並使用包含該索引鍵的第一個 ResourceDictionary 。

您必須在、 Rotation和 FontSize 屬性的BorderWidth字典中儲存雙精度浮點數。 XAML 可方便定義常見資料類型的標籤，例如 x:Double 與 x:Int32：

<ContentPage.Resources>
        <LayoutOptions x:Key="horzOptions"
                       Alignment="Center" />
        <LayoutOptions x:Key="vertOptions"
                       Alignment="Center" />
        <x:Double x:Key="borderWidth">3</x:Double>
        <x:Double x:Key="rotationAngle">-15</x:Double>
        <x:Double x:Key="fontSize">24</x:Double>        
</ContentPage.Resources>

這些額外的三個資源可以使用與值相同的方式 LayoutOptions 來參考：

<Button Text="Do this!"
        HorizontalOptions="{StaticResource horzOptions}"
        VerticalOptions="{StaticResource vertOptions}"
        BorderWidth="{StaticResource borderWidth}"
        Rotation="{StaticResource rotationAngle}"
        TextColor="Red"
        FontSize="{StaticResource fontSize}" />

針對類型的 Color資源，您可以使用直接指派這些型別屬性時所使用的相同字串表示法。建立資源時，會叫用 .NET MAUI 中包含的類型轉換器。您也可以使用 OnPlatform 資源字典內的類別來定義平臺的不同值。下列範例會使用此類別來設定不同的文字色彩：

<OnPlatform x:Key="textColor"
            x:TypeArguments="Color">
    <On Platform="iOS" Value="Red" />
    <On Platform="Android" Value="Aqua" />
</OnPlatform>

資源 OnPlatform 會取得 x:Key 屬性，因為它是字典中的物件，而 x:TypeArguments 屬性是因為它是泛型類別。初始化 iOS物件時，和 Android 屬性會轉換成 Color 值。

下列範例顯示存取六個共用值的三個按鈕：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.SharedResourcesPage"
             Title="Shared Resources Page">
    <ContentPage.Resources>
        <LayoutOptions x:Key="horzOptions"
                       Alignment="Center" />
        <LayoutOptions x:Key="vertOptions"
                       Alignment="Center" />
        <x:Double x:Key="borderWidth">3</x:Double>
        <x:Double x:Key="rotationAngle">-15</x:Double>
        <x:Double x:Key="fontSize">24</x:Double>    
        <OnPlatform x:Key="textColor"
                    x:TypeArguments="Color">
            <On Platform="iOS" Value="Red" />
            <On Platform="Android" Value="Aqua" />
            <On Platform="WinUI" Value="#80FF80" />
        </OnPlatform>
    </ContentPage.Resources>

    <StackLayout>
        <Button Text="Do this!"
                HorizontalOptions="{StaticResource horzOptions}"
                VerticalOptions="{StaticResource vertOptions}"
                BorderWidth="{StaticResource borderWidth}"
                Rotation="{StaticResource rotationAngle}"
                TextColor="{StaticResource textColor}"
                FontSize="{StaticResource fontSize}" />
        <Button Text="Do that!"
                HorizontalOptions="{StaticResource horzOptions}"
                VerticalOptions="{StaticResource vertOptions}"
                BorderWidth="{StaticResource borderWidth}"
                Rotation="{StaticResource rotationAngle}"
                TextColor="{StaticResource textColor}"
                FontSize="{StaticResource fontSize}" />
        <Button Text="Do the other thing!"
                HorizontalOptions="{StaticResource horzOptions}"
                VerticalOptions="{StaticResource vertOptions}"
                BorderWidth="{StaticResource borderWidth}"
                Rotation="{StaticResource rotationAngle}"
                TextColor="{StaticResource textColor}"
                FontSize="{StaticResource fontSize}" />
    </StackLayout>
</ContentPage>

下列螢幕快照會驗證一致的樣式：

樣式控件的螢幕快照。

雖然在頁面頂端定義 Resources 集合很常見，但您可以在頁面上的其他元素上擁有 Resources 集合。例如，下列範例會顯示新增至 StackLayout的資源：

<StackLayout>
    <StackLayout.Resources>
        <Color x:Key="textColor">Blue</Color>
    </StackLayout.Resources>
    ...
</StackLayout>

儲存在資源字典中最常見的物件類型之一是 .NET MAUI Style，它會定義屬性設定的集合。如需樣式的詳細資訊，請參閱使用 XAML 設定應用程式樣式。

注意

資源字典的目的是共享物件。因此，將或之類的Label Button控件放在資源字典中並無意義。無法共用視覺元素，因為相同的實例無法在頁面上出現兩次。

x:Static 標記延伸

除了 StaticResource 標記延伸之外，還有標記 x:Static 延伸。不過，從資源字典傳回物件時 StaticResource ，x:Static 會存取公用靜態字段、公用靜態屬性、公用常數位段或列舉成員。

注意

定義 StaticResource 資源字典的 XAML 實作支持標記延伸，而 x:Static 它是 XAML 的內部部分，如 x 前置詞所示。

下列範例示範如何 x:Static 明確參考靜態字段和列舉成員：

<Label Text="Hello, XAML!"
       VerticalOptions="{x:Static LayoutOptions.Start}"
       HorizontalTextAlignment="{x:Static TextAlignment.Center}"
       TextColor="{x:Static Colors.Aqua}" />

標記延伸的主要 x:Static 用途是從您自己的程式代碼參考靜態欄位或屬性。例如，以下是一個 AppConstants 類別，其中包含一些您可能想要在整個應用程式中於多個頁面上使用的靜態字段：

namespace XamlSamples
{
    static class AppConstants
    {
        public static readonly Color BackgroundColor = Colors.Aqua;
        public static readonly Color ForegroundColor = Colors.Brown;
    }
}

若要參考 XAML 檔案中這個類別的靜態欄位，您必須使用 XML 命名空間宣告來指出此檔案所在的位置。每個額外的 XML 命名空間宣告都會定義新的前置詞。若要存取根應用程式命名空間的本機類別，例如 AppConstants，您可以使用前置詞 local。命名空間宣告必須指出 CLR （Common Language Runtime）命名空間名稱，也稱為 .NET 命名空間名稱，也就是出現在 C# namespace 定義或指示詞中 using 的名稱：

xmlns:local="clr-namespace:XamlSamples"

您也可以定義 .NET 命名空間的 XML 命名空間宣告。例如，以下是 sys 標準 .NET System 命名空間的前置詞，其位於元件中 netstandard 。因為這是另一個元件，因此您也必須指定元件名稱，在此情況下 netstandard：

xmlns:sys="clr-namespace:System;assembly=netstandard"

注意

關鍵詞 clr-namespace 後面接著冒號，然後是 .NET 命名空間名稱，後面接著分號、關鍵詞 assembly、等號和元件名稱。

在宣告 XML 命名空間之後，就可以取用靜態欄位：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:local="clr-namespace:XamlSamples"
             xmlns:sys="clr-namespace:System;assembly=netstandard"
             x:Class="XamlSamples.StaticConstantsPage"
             Title="Static Constants Page"
             Padding="5,25,5,0">
    <StackLayout>
       <Label Text="Hello, XAML!"
              TextColor="{x:Static local:AppConstants.BackgroundColor}"
              BackgroundColor="{x:Static local:AppConstants.ForegroundColor}"
              FontAttributes="Bold"
              FontSize="30"
              HorizontalOptions="Center" />
      <BoxView WidthRequest="{x:Static sys:Math.PI}"
               HeightRequest="{x:Static sys:Math.E}"
               Color="{x:Static local:AppConstants.ForegroundColor}"
               HorizontalOptions="Center"
               VerticalOptions="CenterAndExpand"
               Scale="100" />
    </StackLayout>
</ContentPage>

在這裡範例中 BoxView ，維度會設定為 Math.PI 和 Math.E，但縮放比例為 100：

使用 x：Static 標記延伸的控件螢幕快照。

其他標記延伸

數個標記延伸是 XAML 的內建，且在 .NET MAUI XAML 中受到支援。其中一些不是經常使用，但當您需要它們時非常重要：

如果屬性預設有非 null 值，但您想要將它設定為 null，請將它設定為 {x:Null} 標記延伸。
如果屬性的類型Type為，您可以使用標記延伸{x:Type someClass}將它指派給 Type 物件。
您可以使用標記延伸在 XAML x:Array 中定義陣列。此標記延伸具有名為 Type 的必要屬性，表示陣列中的項目類型。

如需 XAML 標記延伸的詳細資訊，請參閱取用 XAML 標記延伸。

下一步

.NET MAUI 數據系結允許連結兩個對象的屬性，讓其中一個對象的變更造成另一個對象的變更。

數據系結基本概念

共用方式為

XAML 標記延伸

共用的資源

x:Static 標記延伸

其他標記延伸

下一步

其他資源