MAUI中使用CommunityToolkit：扩展控件库实战-优快云博客

MAUI中使用CommunityToolkit：扩展控件库实战

【免费下载链接】maui dotnet/maui: .NET MAUI (Multi-platform App UI) 是.NET生态下的一个统一跨平台应用程序开发框架，允许开发者使用C#和.NET编写原生移动和桌面应用，支持iOS、Android、Windows等操作系统。项目地址: https://gitcode.com/GitHub_Trending/ma/maui

引言

在.NET MAUI (Multi-platform App UI)开发中，官方控件库虽然功能强大，但在实际项目中往往需要更多定制化的控件和功能。CommunityToolkit.Maui作为一个开源的控件扩展库，为开发者提供了丰富的UI组件和工具类，极大地提升了开发效率。本文将从实战角度出发，详细介绍如何在MAUI项目中集成和使用CommunityToolkit，以及如何利用其扩展控件库构建更丰富的用户界面。

CommunityToolkit.Maui简介

CommunityToolkit.Maui是由.NET社区维护的开源项目，它提供了一系列高质量的控件、转换器、行为和辅助类，旨在补充MAUI的官方控件库。该工具包遵循MVVM (Model-View-ViewModel)设计模式，与MAUI框架深度集成，支持iOS、Android、Windows等多个平台。

主要功能模块

CommunityToolkit.Maui主要包含以下功能模块：

控件(Controls)：如Popup、TabView、BadgeView等增强型控件
转换器(Converters)：提供多种数据绑定转换器，简化XAML中的数据转换
行为(Behaviors)：为控件添加额外行为，如验证、事件处理等
辅助类(Helpers)：提供各种实用工具，如SvgImageSource、Preferences等
MVVM支持：包含ObservableObject、ICommand实现等MVVM基础组件

环境准备与集成

系统要求

.NET 7.0或更高版本
Visual Studio 2022或JetBrains Rider
对应平台的SDK（Android SDK、iOS SDK等）

安装CommunityToolkit.Maui

在MAUI项目中集成CommunityToolkit.Maui主要有两种方式：通过NuGet包管理器安装或手动引用。

通过NuGet安装

在Visual Studio的包管理器控制台中执行以下命令：

Install-Package CommunityToolkit.Maui

或者使用.NET CLI：

dotnet add package CommunityToolkit.Maui

在项目模板中集成

查看项目模板中的MauiProgram.cs文件，可以看到CommunityToolkit的集成代码：

src/Templates/src/templates/maui-mobile/MauiProgram.cs

#if (IncludeSampleContent)
using CommunityToolkit.Maui;
#endif
// ...
public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
#if (IncludeSampleContent)
        .UseMauiCommunityToolkit()
        .ConfigureSyncfusionToolkit()
        // ...
#endif
        .ConfigureFonts(fonts =>
        {
            // ...
        });
    // ...
}

关键代码是.UseMauiCommunityToolkit()方法调用，该方法用于初始化CommunityToolkit.Maui。

核心功能实战

1. MVVM基础实现

CommunityToolkit.Maui提供了完善的MVVM支持，通过ObservableObject和ICommand实现可以轻松构建响应式UI。

ViewModel示例

查看模板中的PageModels：

src/Templates/src/templates/maui-mobile/PageModels/MainPageModel.cs

using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

namespace MauiApp._1.PageModels;

public partial class MainPageModel : ObservableObject
{
    [ObservableProperty]
    private string _title = "Main Page";
    
    [RelayCommand]
    private void NavigateToProjects()
    {
        // 导航逻辑
    }
}

这里使用了ObservableObject基类和[ObservableProperty]特性，自动实现了属性更改通知。[RelayCommand]特性则简化了命令的创建。

2. 弹出层控件(Popup)

Popup控件是CommunityToolkit提供的一个强大弹窗组件，支持自定义内容和动画效果。

使用示例

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MauiApp.PopupExamplePage">
    <Button Text="Show Popup" Clicked="OnShowPopupClicked"/>
    
    <toolkit:Popup x:Name="MyPopup">
        <VerticalStackLayout>
            <Label Text="这是一个CommunityToolkit Popup"/>
            <Button Text="关闭" Clicked="OnClosePopupClicked"/>
        </VerticalStackLayout>
    </toolkit:Popup>
</ContentPage>

private void OnShowPopupClicked(object sender, EventArgs e)
{
    MyPopup.IsVisible = true;
}

private void OnClosePopupClicked(object sender, EventArgs e)
{
    MyPopup.IsVisible = false;
}

3. 徽章视图(BadgeView)

BadgeView控件可以轻松地为其他控件添加徽章提示，常用于通知数量显示。

使用示例

<toolkit:BadgeView HorizontalOptions="Center" VerticalOptions="Center">
    <toolkit:BadgeView.Content>
        <Button Text="消息" WidthRequest="100"/>
    </toolkit:BadgeView.Content>
    <toolkit:BadgeView.Badge>
        <toolkit:Badge Text="5" BackgroundColor="Red" TextColor="White"/>
    </toolkit:BadgeView.Badge>
</toolkit:BadgeView>

4. 数据转换器

CommunityToolkit提供了多种内置转换器，简化了XAML中的数据转换。

BooleanToVisibilityConverter示例

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MauiApp.ConverterExamplePage">
    <ContentPage.Resources>
        <toolkit:BooleanToVisibilityConverter x:Key="BooleanToVisibilityConverter"/>
    </ContentPage.Resources>
    
    <StackLayout>
        <Label Text="加载中..." 
               IsVisible="{Binding IsLoading, Converter={StaticResource BooleanToVisibilityConverter}}"/>
    </StackLayout>
</ContentPage>

高级应用场景

1. 图片处理

CommunityToolkit.Maui提供了SvgImageSource，支持SVG图片的加载和显示。

SVG图片使用示例

<Image>
    <Image.Source>
        <toolkit:SvgImageSource Resource="Resources.Images.logo.svg" 
                               Width="100" 
                               Height="100"/>
    </Image.Source>
</Image>

2. 行为(Behaviors)

行为可以为控件添加额外功能，而无需创建子类。

数字验证行为

<Entry Placeholder="请输入数字">
    <Entry.Behaviors>
        <toolkit:NumericValidationBehavior AllowNegatives="False" 
                                           AllowDecimals="True"/>
    </Entry.Behaviors>
</Entry>

3. 消息提示

CommunityToolkit.Maui提供了简化的消息提示API，支持多种弹出通知。

Snackbar示例

src/Templates/src/templates/maui-mobile/AppShell.xaml.cs

using CommunityToolkit.Maui.Alerts;
using CommunityToolkit.Maui.Core;

private async void ShowSnackbar()
{
    var snackbar = Snackbar.Make("操作成功", 
                                 actionButtonText: "撤销", 
                                 action: async () => await UndoOperation(),
                                 duration: TimeSpan.FromSeconds(3));
    await snackbar.Show();
}

项目中的CommunityToolkit应用

在MAUI项目模板中，CommunityToolkit被广泛应用于多个模块：

1. 内部可见性设置

src/Controls/src/Core/Properties/AssemblyInfo.cs

[assembly: InternalsVisibleTo("CommunityToolkit.Maui")]
[assembly: InternalsVisibleTo("CommunityToolkit.Maui.Core")]
[assembly: InternalsVisibleTo("CommunityToolkit.Maui.Embedding")]
[assembly: InternalsVisibleTo("CommunityToolkit.Maui.UnitTests")]
[assembly: InternalsVisibleTo("CommunityToolkit.Maui.Markup")]
[assembly: InternalsVisibleTo("CommunityToolkit.Maui.Markup.UnitTests")]

这些设置允许CommunityToolkit访问MAUI控件库的内部成员，实现更深度的集成。

2. 消息中心迁移

src/Controls/src/Core/MessagingCenter.cs

[Obsolete("We recommend migrating to `CommunityToolkit.Mvvm.Messaging.WeakReferenceMessenger`: https://www.nuget.org/packages/CommunityToolkit.Mvvm")]
public static class MessagingCenter
{
    // ...
}

官方推荐使用CommunityToolkit.Mvvm中的WeakReferenceMessenger替代传统的MessagingCenter，以获得更好的性能和内存管理。

3. 数据模型

src/Essentials/samples/Samples/Model/PermissionItem.cs

using CommunityToolkit.Mvvm.Messaging;

namespace Essentials.Samples.Model
{
    public class PermissionItem : ObservableObject
    {
        // ...
    }
}

使用ObservableObject作为数据模型基类，简化了属性更改通知的实现。

常见问题与解决方案

1. XC0103错误

在项目中可能会遇到XC0103错误：

src/TestUtils/src/Microsoft.Maui.IntegrationTests/SimpleTemplateTest.cs

"XC0103", // https://github.com/CommunityToolkit/Maui/issues/2205

这是由于CommunityToolkit.Maui的一个已知问题引起的，解决方案是更新到最新版本的CommunityToolkit.Maui或应用临时的XAML编译忽略。

2. 平台特定功能处理

在使用跨平台控件时，可能需要针对不同平台进行特殊处理：

#if ANDROID
// Android特定代码
#elif IOS
// iOS特定代码
#endif

总结与展望

CommunityToolkit.Maui作为MAUI生态系统的重要补充，为开发者提供了丰富的控件和工具，极大地提升了跨平台应用开发效率。通过本文的介绍，我们了解了如何在MAUI项目中集成和使用CommunityToolkit，以及如何利用其提供的各种功能来构建更丰富、更交互性的用户界面。

随着MAUI生态的不断发展，CommunityToolkit也将持续更新，提供更多创新功能和更好的性能优化。建议开发者保持关注社区动态，及时更新工具包版本，以获得最佳的开发体验。

参考资料

官方文档：docs/CodeDocumentationGuidelines.md
API参考：src/Core/src/Core.csproj
示例项目：src/Controls/samples/Controls.Sample/

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考