教程：使用 C# 标记和社区工具包创建 .NET MAUI 应用

使用 .NET MAUI 社区工具包中的 C# 标记生成一个.NET MAUI 应用，其用户界面不是使用 XAML 创建的。

介绍

.NET MAUI 社区工具包是一组扩展、行为、动画和其他帮助器。 其中一项功能（C# 标记）提供完全在 C# 代码中创建用户界面的功能。 本教程介绍如何创建适用于 Windows 的 .NET MAUI 应用，该应用使用 C# 标记来创建用户界面。

设置环境

如果你尚未设置 .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# 标记

现在 .NET MAUI 应用已在 Windows 上运行，接下来我们将几个 NuGet 包添加到项目中，以便与 .NET MAUI 社区工具包中的 MVVM 工具包和 C# 标记集成。

在“解决方案资源管理器”中右键单击该项目，然后从上下文菜单中选择“管理 NuGet 包...”。

在“NuGet 包管理器”窗口中，选择“浏览”选项卡并搜索“CommunityToolkit.MVVM”：

单击“安装”，将最新稳定版本的 CommunityToolkit.MVVM 包添加到项目中。

接下来，搜索 CommunityToolkit.Maui：

单击“安装”，将最新稳定版本的 CommunityToolkit.Maui.Markup 包添加到项目中。

在新包安装完成后，关闭“NuGet 包管理器”窗口。

将 ViewModel 添加到项目中

我们将使用 MVVM 工具包添加一个简单的 Model-View-ViewModel (MVVM) 实现。 首先，让我们创建一个视图模型来与我们的视图 (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 Toolkit 生成该类的 INotifyPropertyChanged 实现。 .NET 源生成器需要将 MainViewModel 标记为 partial class 才能正常工作。 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，其中包含一行和两列，我们将在下一步中定义它们。

由于 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：

属性	价值	说明
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# 标记文档