教學課程：使用 C# 標記和社群工具組建立 .NET MAUI 應用程式

使用 .NET MAUI 社群工具組的 C# 標記，以建立時不含 XAML 的使用者介面組建 .NET MAUI 應用程式。

簡介

.NET MAUI 社群工具組是一組延伸模組、行為、動畫和其他協助程式。 C# 標記是其中一種功能，可讓您完全以 C# 程式碼建立使用者介面。 在本教學課程中，您將瞭解如何為使用 C# 標記來建立使用者介面的 Windows 建立 .NET MAUI 應用程式。

設定環境

如果您尚未設定 .NET MAUI 的開發環境，請按照步驟開始使用 Windows 的 .NET MAUI。

建立 .NET MAUI 專案

注意

如果您已經熟悉 .NET MAUI 專案的設定方法，可以跳到下一節。

啟動 Visual Studio，然後在起始視窗按一下 [建立新專案] 以建立新的專案。

在「建立新專案」視窗的 [所有專案類型] 下拉式清單中選取 [MAUI]，然後選取 .NET MAUI 應用程式 範本，再按一下 [下一步] 按鈕：

接下來，在「設定新專案」畫面上，為專案命名、選擇位置，然後按一下 [下一步] 按鈕。

在最後一個畫面「其他資訊」上，按一下 [建立] 按鈕。

等候專案建立，以及相依性還原。

在 Visual Studio 工具列中，按下 [Windows 電腦] 按鈕以組建並執行應用程式。 按一下 [按我] 按鈕，確認按鈕內容會隨著點擊次數而更新。

現在您已確認 Windows 上的 .NET MAUI 應用程式可如期運作，我們接著就可以整合 MVVM 工具組和 C# 標記套件。 在下一節，您會將這些套件新增到您的新專案。

從 .NET MAUI 社群工具組新增 C# 標記

現在您已在 Windows 執行 .NET MAUI 應用程式了，接著就將幾個 NuGet 套件新增至專案，以便與 .NET MAUI 社群工具組的 MVVM 工具組和 C# 標記整合。

在「方案總管」中，以滑鼠右鍵按一下專案，然後選取操作功能表中的 [管理 NuGet 套件...]。

在「NuGet 套件管理員」視窗中，選取 [瀏覽] 索引標籤，然後搜尋「CommunityToolkit.MVVM」。

按一下 [安裝]，將 CommunityToolkit.MVVM 套件的最新穩定版本新增至專案。

接下來，搜尋 CommunityToolkit.Maui：

按一下 [安裝]，將 CommunityToolkit.Maui.Markup 套件的最新穩定版本新增至專案。

在新套件完成安裝之後，關閉「NuGet 套建管理員」視窗。

將 ViewModel 新增至專案

我們接著要以 MVVM 工具組新增簡單的 Model-View-ViewModel (MVVM) 實作。 我們先建立 viewmodel 以便與檢視 (MainPage) 配對。 再次以滑鼠右鍵按一下專案，並從操作功能表中選取 [新增 | 類別]。

在顯示的「新增項目」視窗中，將類別命名為 MainViewModel，然後按一下 [新增]：

我們接著要在 MainViewModel 運用 MVVM 工具組功能。 以下列程式碼取代 類別的內容：

using CommunityToolkit.Mvvm.ComponentModel;
using System.ComponentModel;
using System.Diagnostics;

namespace MauiMarkupSample
{
    [INotifyPropertyChanged]
    public partial class MainViewModel
    {
        [ObservableProperty]
        private string name;
        partial void OnNameChanging(string value)
        {
            Debug.WriteLine($"Name is about to change to {value}");
        }
        partial void OnNameChanged(string value)
        {
            Debug.WriteLine($"Name has changed to {value}");
        }
    }
}

如果您已完成組建第一個適用於 Windows 的 .NET MAUI 應用程式教學課程，您就會瞭解上述程式碼的功能。 類別 MainViewModel 裝飾了 INotifyPropertyChanged 屬性，可讓 MVVM 工具組為類別產生 INotifyPropertyChanged 實作。 MainViewModel 必須標示為 partial class，.NET 來源產生器才能運作。 name 私有欄位的 ObservableProperty 屬性會針對在產生的部分類別含有正確 INotifyPropertyChanged 實作的類別新增 Name 屬性。 新增 OnNameChanging 和 OnNameChanged 部分方法是選擇性步驟，但可讓您在 Name 屬性將變更或已變更時新增自訂邏輯。

使用 C# 標記組建 UI

使用 C# 標記組建 UI 時，第一個步驟是在 MauiProgram.cs 中更新 CreateMauiApp() 方法。 使用下列程式碼來取代 方法的內容：

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    builder
        .UseMauiApp<App>()
        .UseMauiCommunityToolkitMarkup();

    return builder.Build();
}

您還必須在檔案頂端新增新的 using 陳述式：using CommunityToolkit.Maui.Markup;。 呼叫 UseMauiCommunityToolkitMarkup() 會將 C# 標記的支援功能新增至應用程式，讓您以 C# 程式碼替代 XAML 來建構 UI。

轉譯 UI 時MainPage.xaml 檔案將不再使用，因此您可以移除 ContentPage 的內容。

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MauiMarkupSample.MainPage">
</ContentPage>

在 MainPage.xaml.cs中，移除點擊事件處理常式，並將三個私有成員新增至類別：

private readonly MainViewModel ViewModel = new();
private enum Row { TextEntry }
private enum Column { Description, Input }

屬性 ViewModel 會建立對 UI 進行資料繫結時使用的類別 MainViewModel 執行個體。 Row和 Column 列舉將用於定義含有 C# 標記的 UI 版面配置。 這是一種簡單的 UI，其中包含的單一列和兩個欄，將在下個步驟中定義。 您也需要將命名空間指示詞新增至檔案頂端： using static CommunityToolkit.Maui.Markup.GridRowsColumns;。

由於 UI元素將以 C# 程式碼來定義，因此不需要 InitializeComponent() 方法。 移除呼叫，並取代為下列程式碼來建立 UI：

public MainPage()
{
    Content = new Grid
    {
        RowDefinitions = Rows.Define(
            (Row.TextEntry, 36)),

        ColumnDefinitions = Columns.Define(
            (Column.Description, Star),
            (Column.Input, Stars(2))),

        Children =
        {
            new Label()
                .Text("Customer name:")
                .Row(Row.TextEntry).Column(Column.Description),

            new Entry
            {
                Keyboard = Keyboard.Numeric,
                BackgroundColor = Colors.AliceBlue,
            }.Row(Row.TextEntry).Column(Column.Input)
                .FontSize(15)
                .Placeholder("Enter name")
                .TextColor(Colors.Black)
                .Height(44)
                .Margin(6, 6)
                .Bind(Entry.TextProperty, nameof(ViewModel.Name), BindingMode.TwoWay)
        }
    };
}

MainPage 建構函式中的新程式碼是使用 C# 標記來定義 UI。 Grid 已設為頁面的 Content。 新的網格定義了高度為 36 像素的列，以及使用 Star 值 (而不是絕對像素值) 定義寬度的兩個欄。 Input 欄的寬度一律是 Description 欄的兩倍。 這些定義的對等 XAML 是：

<Grid.RowDefinitions>
    <RowDefinition Height="36" />
</Grid.RowDefinitions>
<Grid.ColumnDefinitions>
    <ColumnDefinition Width="*" />
    <ColumnDefinition Width="2*" />
</Grid.ColumnDefinitions>

用於建立網格的其餘程式碼會新增兩個 Children、一個 Label 和一個 Entry。 Text、Row 與 Column 屬性是設定在 Label 元素上，且 Entry 建立時含有下列屬性：

屬性	數值	Description
Row	Row.TextEntry	定義列數。
Column	Column.Input	定義欄數。
FontSize	15	設定字型大小。
Placeholder	"Enter name"	設定元素空白時要顯示的預留位置文字。
TextColor	Colors.Black	設定文字顏色。
Height	44	奢定元素高度。
Margin	6, 6	定義元素周圍的邊界。
Bind	Entry.TextProperty, nameof(ViewModel.Name), BindingMode.TwoWay	使用雙向資料繫結，將元素的 Text 屬性繫結到檢視的 Name 屬性。

定義這些子元素的對等 XAML 是：

<Label Text="Customer name:"
       Grid.Row="0" Grid.Column="0" />
<Entry Grid.Row="1" Grid.Column="0"
       FontSize="15"
       Placeholder="Enter name"
       HeightRequest="44"
       Margin="6, 6"
       Text="{Binding Path=ViewModel.Name, Mode=TwoWay}" />

您可能已注意到上述標記並未設定 TextColor 屬性。 設定控制項的 TextColor 需要設定自訂樣式。 如詳細了解如何在 .NET MAUI 使用樣式，請參閱使用 XAML 設定應用程式樣式。 這個範例說明了以 C# 標記設定屬性比對等 XAML 更精簡。 不過，使用當中的樣式可讓重複使用和繼承更簡單。

您現在已可以開始執行應用程式了！ 按 F5 鍵建置並執行專案。 應用程式現在看起來應該類似如下螢幕擷取畫面。

您現在已使用 .NET MAUI 在 Windows 上建立第一個 C# 標記應用程式了。 若要深入瞭解如何使用 C# 標記，請參閱 C# 標記文件。

相關主題

.NET MAUI 學習資源

.NET MAUI 社群工具組文件

C# 標記文件