開始使用 XAML

發行項
02/13/2024

在 .NET 多平臺應用程式 UI （.NET MAUI）應用程式中，XAML 主要用於定義頁面的視覺內容，並與 C# 程式代碼後置檔案搭配運作。程序代碼後置檔案提供標記的程式代碼支援。這兩個檔案會共同參與新的類別定義，其中包含子檢視和屬性初始化。在 XAML 檔案中，會使用 XML 元素和屬性來參考類別和屬性，並建立標記和程式代碼之間的連結。

XAML 檔案的結構

新的 .NET MAUI 應用程式包含三個 XAML 檔案，以及其相關聯的程式代碼後置檔案：

Screenshot of the structure of a new .NET MAUI app.

第一個檔案配對是 App.xaml、XAML 檔案和 App.xaml.cs，這是與 XAML 檔案相關聯的 C# 程式代碼後置 檔案。 App.xaml 和 App.xaml.cs 都參與衍生自 Application的類別App。第二個檔案配對是 AppShell.xaml 和 AppShell.xaml.cs，其有助於衍生自 Shell的類別AppShell。大部分具有 XAML 檔案的其他類別都會參與衍生自 ContentPage的類別，並定義頁面的 UI。這是 MainPage.xaml 和 MainPage.xaml.cs 檔案的 true。

MainPage.xaml 檔案具有下列結構：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MyMauiApp.MainPage">
    ...
</ContentPage>

兩個 XML 命名空間（xmlns）宣告是指 microsoft.com 上的 URI。不過，這些 URI 沒有內容，而且基本上會作為版本標識符運作。

第一個 XML 命名空間宣告表示在 XAML 檔案中定義的標籤沒有前置詞，例如 ContentPage，參考 .NET MAUI 中的類別。第二個命名空間宣告會定義的 x前置詞。這用於 XAML 本身內建的數個元素和屬性，以及 XAML 的其他實作所支援的屬性。不過，這些元素和屬性會根據 URI 中內嵌的年份而略有不同。 .NET MAUI 支援 2009 XAML 規格。

在第一個標記的結尾，前置 x 詞會用於名為 Class的屬性。由於此 x 前置詞的使用幾乎適用於 XAML 命名空間，因此 Class XAML 屬性幾乎一律稱為 x:Class。屬性 x:Class 會指定完整 .NET 類別名稱： MainPage 命名空間中的 MyMauiApp 類別。這表示這個 XAML 檔案會在衍生自 ContentPage 的命名空間中MyMauiApp定義名為 MainPage 的新類別（屬性所在的標記x:Class）。

屬性 x:Class 只能出現在 XAML 檔案的根元素中，以定義衍生的 C# 類別。這是 XAML 檔案中唯一定義的新類別。 XAML 檔案中顯示的其他所有專案，只會從現有的類別具現化並初始化。

MainPage.xaml.cs 檔案看起來如下所示：

namespace MyMauiApp;

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
    }
}

類別 MainPage 衍生自 ContentPage，而是部分類別定義。

當 Visual Studio 建置專案時，來源產生器會產生新的 C# 來源，其中包含從MainPage建構函式呼叫的方法定義InitializeComponent，並將它新增至編譯物件。

在執行時間，類別中的 MauiProgram 程式碼會啟動應用程式並執行 App 類別建構函式，以具現化 AppShell。類別 AppShell 會具現化要顯示之應用程式的第一頁，也就是 MainPage。建 MainPage 構函式會呼叫 InitializeComponent，它會初始化 XAML 檔案中定義的所有物件、將它們全部連接在父子關聯性中、將程式代碼中定義的事件處理程式附加至 XAML 檔案中設定的事件，並將對象的結果樹狀結構設定為頁面的內容。

注意

類別 AppShell 會使用 .NET MAUI Shell 來設定要顯示之應用程式的第一頁。不過，Shell 超出此 XAML 簡介的範圍。如需詳細資訊，請參閱 .NET MAUI Shell。

設定頁面內容

ContentPage應該包含單一子系，可以是具有子檢視的檢視或版面配置。的 ContentPage 子系會自動設定為屬性的值 ContentPage.Content 。

下列範例顯示 ContentPage 包含的 Label：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.HelloXamlPage"
             Title="Hello XAML Page">
    <Label Text="Hello, XAML!"
           VerticalOptions="Center"
           HorizontalTextAlignment="Center"
           Rotation="-15"
           FontSize="18"
           FontAttributes="Bold"
           TextColor="Blue" />
</ContentPage>

從上述範例中，類別、屬性和 XML 之間的關聯性應該很明顯。 .NET MAUI 類別（例如 ContentPage 或 Label）會以 XML 元素的形式出現在 XAML 檔案中。該類別的屬性，包括 Title on ContentPage 和 7 屬性 Label ，通常會顯示為 XML 屬性。

有許多快捷方式可用來設定這些屬性的值。有些屬性是基本數據類型。例如，Title和屬性的類型為string，且 Rotation 的類型為 doubleText 。屬性 HorizontalTextAlignment 的類型為 TextAlignment，這是列舉。對於任何列舉型別的屬性，您只需要提供的成員名稱。

不過，對於更複雜的型別屬性，轉換器會用於剖析 XAML。這些是衍生自 TypeConverter的 .NET MAUI 類別。針對上述範例，會自動套用數個 .NET MAUI 轉換器，將字串值轉換成正確的類型：

LayoutOptionsConverter 為 VerticalOptions 屬性。這個轉換子會將結構之公用靜態字段 LayoutOptions 的名稱轉換為類型的 LayoutOptions值。
ColorTypeConverter 為 TextColor 屬性。此轉換子會轉換類別或十六進位 RGB 值的公用靜態欄位 Colors 名稱，以及具有或不含 Alpha 色板。

當您執行 .NET MAUI 應用程式時， MainPage 通常會顯示。若要查看不同的頁面，您可以將該頁面設定為 AppShell.xaml 檔案中的新啟動頁面，或從 MainPage流覽至新頁面。

若要實作導覽，在 MainPage.xaml.cs 建構函式中，您可以建立簡單Button且使用事件處理程式來巡覽至 HelloXamlPage：

public MainPage()
{
    InitializeComponent();

    Button button = new Button
    {
        Text = "Navigate!",
        HorizontalOptions = LayoutOptions.Center,
        VerticalOptions = LayoutOptions.Center
    };

    button.Clicked += async (sender, args) =>
    {
        await Navigation.PushAsync(new HelloXamlPage());
    };

    Content = button;
}

當您編譯及部署此應用程式的新版本時，畫面上會出現一個按鈕。按下它會巡覽至 HelloXamlPage：

Screenshot of rotated Label text.

您可以使用在每個平臺上的導覽列來瀏覽回 MainPage 。

注意

此流覽模型的替代方法是使用 .NET MAUI Shell。如需詳細資訊，請參閱 .NET MAUI Shell 概觀。

XAML 和程式代碼互動

大部分 ContentPage 衍生專案的子系是版面配置，例如 StackLayout 或 Grid，而且版面配置可以包含多個子系。在 XAML 中，這些父子式關聯性是使用一般 XML 階層建立的：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.XamlPlusCodePage"
             Title="XAML + Code Page">
    <StackLayout>
        <Slider VerticalOptions="Center" />
        <Label Text="A simple Label"
               FontSize="18"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
        <Button Text="Click Me!"
                HorizontalOptions="Center"
                VerticalOptions="Center" />
    </StackLayout>
</ContentPage>

此 XAML 檔案是語法完整的，併產生下列 UI：

Screenshot of multiple controls on a page.

不過，雖然您可以與 Slider 和 Button互動，但不會更新UI。應該 Slider 會導致 Label 顯示目前值，而 Button 應該執行某些動作。

Slider透過Label數據系結，可以在 XAML 中完全使用來顯示值。不過，先查看程式代碼解決方案會很有用。即便如此，處理 Button 點擊肯定需要程序代碼。這表示的程式代碼後置檔案XamlPlusCodePage必須包含的事件處理程式ValueChanged，以及 Clicked 的事件Slider Button：

namespace XamlSamples
{
    public partial class XamlPlusCodePage
    {
        public XamlPlusCodePage()
        {
            InitializeComponent();
        }

        void OnSliderValueChanged(object sender, ValueChangedEventArgs args)
        {
            valueLabel.Text = args.NewValue.ToString("F3");
        }

        async void OnButtonClicked(object sender, EventArgs args)
        {
            Button button = (Button)sender;
            await DisplayAlert("Clicked!", "The button labeled '" + button.Text + "' has been clicked", "OK");
        }
    }
}

回到 XAML 檔案， Slider 和 Button 標記必須包含參考這些處理程式之 ValueChanged 和 Clicked 事件的屬性：

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="XamlSamples.XamlPlusCodePage"
             Title="XAML + Code Page">
    <StackLayout>
        <Slider VerticalOptions="Center"
                ValueChanged="OnSliderValueChanged" />
        <Label x:Name="valueLabel"
               Text="A simple Label"
               FontSize="18"
               HorizontalOptions="Center"
               VerticalOptions="Center" />
        <Button Text="Click Me!"
                HorizontalOptions="Center"
                VerticalOptions="Center"
                Clicked="OnButtonClicked" />
    </StackLayout>
</ContentPage>

請注意，將處理程式指派給事件具有與將值指派給屬性相同的語法。此外，若要 ValueChanged 讓的 Slider 事件處理程式使用 Label 來顯示目前值，處理程式必須從程式代碼參考該物件。因此， Label 需要以屬性指定 x:Name 的名稱。屬性 x 的 x:Name 前置詞表示這個屬性是 XAML 內建的。您指派給 x:Name 屬性的名稱與 C# 變數名稱具有相同的規則。例如，它必須以字母或底線開頭，且不包含內嵌空格。

ValueChanged事件處理程式現在可以設定 Label 來顯示新的Slider值，而這個值可從事件自變數取得：

void OnSliderValueChanged(object sender, ValueChangedEventArgs args)
{
    valueLabel.Text = args.NewValue.ToString("F3");
}

或者，處理程式可以取得 Slider 物件，該對像是從 sender 自變數產生這個事件，並從中取得 Value 屬性：

void OnSliderValueChanged(object sender, ValueChangedEventArgs args)
{
    valueLabel.Text = ((Slider)sender).Value.ToString("F3");
}

結果是，的任何操作 Slider 都會在中 Label顯示其值：

Screenshot of multiple controls on a page, with Slider value displayed.

在上述範例中，Button藉由顯示具有按鈕的警示Text來模擬事件的回應Clicked。因此，事件處理程式可以將自變數Button轉換成 sender ，然後存取其屬性：

async void OnButtonClicked(object sender, EventArgs args)
{
    Button button = (Button)sender;
    await DisplayAlert("Clicked!", "The button labeled '" + button.Text + "' has been clicked", "OK");
}

方法 OnButtonClicked 的定義是 async ，因為 DisplayAlert 方法是異步的 await ，而且應該以運算符開頭，這個運算符會在方法完成時傳回。因為這個方法會 Button 從 sender 自變數取得引發事件，所以同一個處理程式可用於多個按鈕。

下一步

XAML 主要是針對具現化和初始化對象所設計。但是，屬性通常必須設定為無法輕易表示為 XML 字串的複雜物件，而某個類別所定義的屬性有時必須在子類別上設定。這兩個需求需要屬性元素和附加屬性的基本 XAML 語法功能。

基本 XAML 語法

開始使用 XAML

XAML 檔案的結構

設定頁面內容

頁面導覽

XAML 和程式代碼互動

下一步

意見反應

其他資源