.NET Multi-platform App UI (.NET MAUI) 社区工具包入门

本文介绍如何开始使用作为 .NET MAUI 社区工具包项目的一部分提供的包。

添加 NuGet 包

该工具包以一组 NuGet 包的形式提供，可以使用 Visual Studio 将其添加到任何现有或新项目中。

1. 打开现有项目，或根据 .NET MAUI 设置文档新建项目

2. 在“解决方案资源管理器”面板中，右键单击项目名称，然后选择“管理 NuGet 包”。 搜索“CommunityToolkit.Maui”，然后从列表中选择所需的 NuGet 包。

   

3. 从以下选项中选择最适合需求的工具包：

此包是用于使用 .NET MAUI 进行开发工作的动画、行为、转换器和自定义视图的集合。 它可简化并演示使用 .NET MAUI 生成 iOS、Android、macOS 和 Windows 应用的常见开发人员任务。

包名称：CommunityToolkit.Maui

Package url：https://www.nuget.org/packages/CommunityToolkit.Maui

初始化包

首先，需要将 using 语句添加到 MauiProgram.cs 文件的顶部

using CommunityToolkit.Maui;

为了正确使用工具包，必须在启动应用程序 MauiProgram.cs 文件时，对 MauiAppBuilder 类调用 UseMauiCommunityToolkit 方法。 以下示例演示如何执行此操作。

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkit()

要使用工具包的功能，请参阅每个特定功能的文档页。

此包是一组 Fluent 帮助程序方法和类，用于简化在 C# 中生成声明性 .NET MAUI 用户界面。

包名称：CommunityToolkit.Maui.Markup

Package url：https://www.nuget.org/packages/CommunityToolkit.Maui.Markup

初始化包

首先，需要将 using 语句添加到 MauiProgram.cs 文件的顶部

using CommunityToolkit.Maui.Markup;

为了正确使用工具包，必须在启动应用程序 MauiProgram.cs 文件时，对 MauiAppBuilder 类调用 UseMauiCommunityToolkitMarkup 方法。 以下示例演示如何执行此操作。

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMarkup()

要使用工具包的功能，请参阅每个特定功能的文档页。

通过此包，可以在 .NET MAUI Windows 应用程序中显示地图。

重要

必应地图已停止提供此控件正常运行所需的新 API 密钥。 我们目前正在决定是应更新此控件以使用此使用 Azure Maps 的 WinUI 控件，还是将为此等待正式的 .NET MAUI 第一方实现。 目前，这意味着如果还没有必应地图 API 密钥，则不能使用此控件。 必应地图整体将于 2025 年 6 月 30 日完全停用。

包名称：CommunityToolkit.Maui.Maps

Package url：https://www.nuget.org/packages/CommunityToolkit.Maui.Maps

初始化包

首先，需要将 using 语句添加到 MauiProgram.cs 文件的顶部

using CommunityToolkit.Maui.Maps;

为了正确使用 Map，必须在启动应用程序 MauiProgram.cs 文件时，对 MauiAppBuilder 类调用 .UseMauiCommunityToolkitMaps 方法。 此方法需要有效的必应地图 API 密钥，该密钥可通过必应地图门户获取。

以下示例演示如何执行此操作。

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMaps("YOUR_API_KEY")

当同时使用适用于 Windows 的 .NET MAUI 社区工具包地图和常规 .NET MAUI 地图时，需要确保每个初始化调用仅针对相关平台进行。 以下示例演示如何执行此操作。

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
#if ANDROID || IOS
    .UseMauiMaps()
#elif WINDOWS
    .UseMauiCommunityToolkitMaps("YOUR_API_KEY")
#endif

有关如何在 iOS 和 Android 上初始化地图以及如何使用地图控件 API 的更多信息，请参阅 .NET MAUI 地图文档。

通过此包，可以在 .NET MAUI 应用程序中播放音频和视频。

包名称：CommunityToolkit.Maui.MediaElement

Package url：https://www.nuget.org/packages/CommunityToolkit.Maui.MediaElement

初始化包

首先，需要将 using 语句添加到 MauiProgram.cs 文件的顶部

using CommunityToolkit.Maui;

为了正确使用 MediaElement，必须在启动应用程序 MauiProgram.cs 文件时，对 MauiAppBuilder 类调用 UseMauiCommunityToolkitMediaElement 方法。 以下示例演示如何执行此操作。

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement()

要使用工具包的功能，请参阅每个特定功能的文档页。

CommunityToolkit.Maui.Camera

使用此包可以连接到相机，显示相机预览并拍照。

包名称：CommunityToolkit.Maui.Camera

Package url：https://www.nuget.org/packages/CommunityToolkit.Maui.Camera

初始化包

首先，需要将 using 语句添加到 MauiProgram.cs 文件的顶部

using CommunityToolkit.Maui;

若要正确使用 CameraView，在启动应用程序 MauiProgram.cs 文件时，必须对 MauiAppBuilder 类调用 UseMauiCommunityToolkitCamera 方法。 以下示例演示如何执行此操作。

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitCamera()

要使用工具包的功能，请参阅每个特定功能的文档页。

使用 NuGet 包

4. 在 MauiProgram.cs 中启用工具包：

var builder = MauiApp.CreateBuilder();
builder.UseMauiApp<App>();
builder.UseMauiCommunityToolkit();

4.1. 对于高级设置，请设置 CommunityToolkit.Maui.Options：

builder.UseMauiCommunityToolkit(options =>
{
    options.SetShouldSuppressExceptionsInConverters(false);
    options.SetShouldSuppressExceptionsInBehaviors(false);
    options.SetShouldSuppressExceptionsInAnimations(false);
});

5. 请查看文档的其余部分，了解有关实现特定功能的详细信息。

其他资源

.NET MAUI 社区工具包 GitHub 存储库包含示例应用程序的源代码，旨在说明如何使用工具包生成 .NET MAUI 应用程序。 请注意，需要克隆或下载存储库并编译源代码才能运行示例应用程序。

建议不熟悉 .NET MAUI 的开发人员访问 .NET MAUI 文档。

访问 .NET MAUI 社区工具包 GitHub 存储库查看当前源代码、后续内容并克隆存储库。 欢迎为社区做贡献！