机遇屋-.NET跨端大杀器MAUI基础学习

.NET跨端大杀器MAUI基础学习

作者：ych

## 官方文档
[maui](https://docs.microsoft.com/zh-cn/dotnet/maui/ "maui")
[blog](https://devblogs.microsoft.com/dotnet/category/maui/ "blog")

## 精简文档
### 什么是 .NET MAUI？
.NET 多平台应用 UI (.NET MAUI) 是一个跨平台框架，用于使用 C# 和 XAML 创建本机移动和桌面应用。

.NET MAUI 是开源的，是 Xamarin.Forms 的演变，从移动方案扩展到桌面方案，UI 控件从头开始重新生成，以便实现性能和扩展性。 如果以前使用 Xamarin.Forms 生成跨平台用户界面，你会注意到与 .NET MAUI 有许多相似之处。 但也有一些差异。 使用 .NET MAUI，可以使用单个项目创建多平台应用，但如有必要，可以添加特定于平台的源代码和资源。 .NET MAUI 的主要目标是在单个代码库中尽可能多地实现应用逻辑和 UI 布局。

### .NET MAUI 的工作原理
.NET MAUI 将Android、iOS、macOS和Windows API 统一到单个 API 中，该 API 允许在任意位置运行一次开发人员体验，同时提供对每个本机平台的各个方面的深入访问。

.NET MAUI 提供了一个框架，用于为移动和桌面应用生成 UI。

## 实践
好的，我们来使用 .NET 8 的最新实践和写法，从零开始构建一个无缝混合 .NET MAUI 原生页面和 Blazor Web 视图的应用程序。

这个更新后的指南将确保所有代码和配置都遵循 .NET 8 的标准模式。

### 1. 环境准备

首先，请确保您的开发环境已更新至最新版本：

*   **Visual Studio 2022 (v17.8 or later)**：并确保已安装 “.NET Multi-platform App UI development” 工作负载。
*   **.NET 8 SDK**：在安装 Visual Studio 工作负载时会自动包含。

### 2. 创建 .NET MAUI Blazor 项目

第一步是创建一个标准的 .NET MAUI Blazor 应用程序，这将是我们的项目基础。

1.  打开 Visual Studio 2022。
2.  选择“创建新项目”。
3.  在项目模板搜索框中输入 "MAUI"，然后选择 **.NET MAUI Blazor App** 模板。
4.  给项目命名，例如 `MauiHybridAppNet8`，并选择 .NET 8.0 作为框架版本。
5.  点击“创建”。

创建完成后，您可以直接运行此项目。您会看到一个基于 Blazor 的默认用户界面，其中包含计数器和天气数据示例。

### 3. 创建原生 .NET MAUI 页面

接下来，我们将添加一个纯原生的 .NET MAUI 页面。

**第一步：创建原生视图 (ContentPage)**

1.  在解决方案资源管理器中，右键点击项目名称，选择 “添加” -> “新建文件夹”，命名为 `NativeViews`。
2.  右键点击 `NativeViews` 文件夹，选择 “添加” -> “新建项”。
3.  在左侧面板选择 **.NET MAUI**，然后在列表中选择 **.NET MAUI ContentPage (XAML)**。
4.  将页面命名为 `NativeContentPage.xaml`，然后点击“添加”。

**第二步：设计原生页面 UI**

打开 `NativeContentPage.xaml` 文件，添加一些原生控件。

```xml
<?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="MauiHybridAppNet8.NativeViews.NativeContentPage"
             Title="原生页面">
    <VerticalStackLayout Spacing="15" Padding="20">
        <Label 
            Text="这里是 .NET MAUI 原生页面"
            FontSize="22"
            FontAttributes="Bold"
            HorizontalOptions="Center" />

<Button 
            Text="返回 Blazor 视图"
            Clicked="OnBackButtonClicked"
            HorizontalOptions="Center" />
    </VerticalStackLayout>
</ContentPage>
```

**第三步：添加后台逻辑**

打开 `NativeContentPage.xaml.cs`，我们将在稍后实现按钮点击事件和状态共享逻辑。

### 4. 实现 Blazor 与原生之间的导航

为了能够在 Blazor 视图和原生页面之间跳转，我们需要设置一个导航容器。

**第一步：设置 NavigationPage**

打开 `App.xaml.cs` 文件，将 `MainPage` 包装在一个 `NavigationPage` 中。这为我们提供了一个可以进行压栈/出栈 (Push/Pop) 操作的导航堆栈。

```csharp
public App()
{
    InitializeComponent();

// 将 MainPage 包装在 NavigationPage 中以启用导航
    MainPage = new NavigationPage(new MainPage());
}
```

**第二步：从 Blazor 页面发起导航**

现在，我们需要一种方法从 Blazor UI 触发到原生页面的导航。最现代且解耦的方式是使用依赖注入来获取原生页面实例。

1.  **注册原生页面以便进行依赖注入**:
    打开 `MauiProgram.cs`，在 `builder` 配置中注册我们的原生页面。我们将其注册为瞬时 (Transient) 的，意味着每次请求时都会创建一个新实例。

```csharp
    // 在 MauiProgram.cs 文件中
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                });

builder.Services.AddMauiBlazorWebView();

#if DEBUG
    		builder.Services.AddBlazorWebViewDeveloperTools();
    		builder.Logging.AddDebug();
            #endif
            
            // -- 添加下面这行代码 --
            builder.Services.AddTransient<NativeViews.NativeContentPage>();

return builder.Build();
        }
    }
    ```

2.  **在 Blazor 组件中添加导航按钮**:
    打开 `Components/Pages/Home.razor`，注入 `IServiceProvider` 来访问依赖注入容器，并添加一个按钮来执行导航。

```html
    @page "/"
    @inject IServiceProvider ServiceProvider

<h1>Hello, from Blazor in .NET 8!</h1>

Welcome to your new app.

<button class="btn btn-primary" @onclick="NavigateToNativePage">跳转到原生 MAUI 页面</button>

@code {
        private async Task NavigateToNativePage()
        {
            // 从服务容器中解析原生页面实例
            var nativePage = ServiceProvider.GetRequiredService<NativeViews.NativeContentPage>();
            
            // 使用 MAUI 的导航服务进行页面跳转
            await App.Current.MainPage.Navigation.PushAsync(nativePage);
        }
    }
    ```

现在，运行应用并点击新添加的按钮，您将顺利跳转到原生页面。

### 5. 状态共享与双向通信

混合应用的核心优势之一是能够在 Web 和原生代码之间共享逻辑和状态。我们将通过一个共享服务来实现这一点。

**第一步：创建共享状态服务**

1.  在项目中创建一个新文件夹，命名为 `Services`。
2.  在 `Services` 文件夹中，创建一个名为 `AppState.cs` 的类。

```csharp
    // Services/AppState.cs
    public class AppState
    {
        public int Counter { get; private set; }

public event Action OnStateChanged;

public void IncrementCounter()
        {
            Counter++;
            NotifyStateChanged();
        }

private void NotifyStateChanged() => OnStateChanged?.Invoke();
    }
    ```

**第二步：注册共享服务**

在 `MauiProgram.cs` 中，将 `AppState` 注册为单例 (Singleton)，以确保整个应用程序共享同一个实例。

```csharp
// 在 MauiProgram.cs 的 CreateMauiApp 方法中
// ...

#endif

// -- 添加下面这两行代码 --
builder.Services.AddSingleton<AppState>();
builder.Services.AddTransient<NativeViews.NativeContentPage>();

return builder.Build();
```

**第三步：在 Blazor 中使用共享服务**

修改 `Components/Pages/Counter.razor`，让它使用我们新的共享服务。

```html
@page "/counter"
@inject AppState AppState
@implements IDisposable

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @AppState.Counter</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    protected override void OnInitialized()
    {
        // 订阅状态变更事件，以便在状态变化时刷新UI
        AppState.OnStateChanged += StateHasChanged;
    }

private void IncrementCount()
    {
        AppState.IncrementCounter();
    }

public void Dispose()
    {
        // 组件销毁时取消订阅，防止内存泄漏
        AppState.OnStateChanged -= StateHasChanged;
    }
}
```

**第四步：在原生页面中使用和修改共享状态**

现在，我们让原生页面也能消费和修改这个共享状态。

1.  **注入服务**: 修改 `NativeContentPage.xaml.cs` 的构造函数以接收 `AppState` 服务。

```csharp
    // NativeViews/NativeContentPage.xaml.cs
    using MauiHybridAppNet8.Services; // 添加 using

public partial class NativeContentPage : ContentPage, IDisposable
    {
        private readonly AppState _appState;
    
        public NativeContentPage(AppState appState)
        {
            InitializeComponent();
            _appState = appState;
    
            // 订阅事件并更新UI
            _appState.OnStateChanged += UpdateUI;
            UpdateLabelText(); // 初始化文本
        }
    
        private void UpdateUI()
        {
            // 确保在UI线程上更新
            MainThread.BeginInvokeOnMainThread(UpdateLabelText);
        }

private void UpdateLabelText()
        {
            StateLabel.Text = $"当前共享计数值: {_appState.Counter}";
        }
    
        private void OnUpdateButtonClicked(object sender, EventArgs e)
        {
            // 从原生代码修改共享状态
            _appState.IncrementCounter();
        }
    
        private async void OnBackButtonClicked(object sender, EventArgs e)
        {
            await Navigation.PopAsync();
        }

public void Dispose()
        {
            _appState.OnStateChanged -= UpdateUI;
        }
    }
    ```

现在，您的应用程序已经完全配置好了！您可以：

1.  在 Blazor 的 Counter 页面增加计数。
2.  导航到原生页面，会看到计数值已经同步。
3.  在原生页面点击按钮增加计数。
4.  返回 Blazor 页面，会发现计数值也同步更新了。

这个使用 .NET 8 编写的例子展示了 Blazor Hybrid 架构的强大之处，它通过现代的依赖注入和服务模式，实现了 Web 技术和原生平台之间的无缝集成。

### 什么是 .NET MAUI Blazor？

.NET MAUI Blazor，也称为 **Blazor Hybrid**，是一种开发模式，它允许您将基于 Web 技术的 Blazor 组件嵌入到原生的 .NET MAUI 应用程序中。

简单来说，您可以：

*   **使用 Web 技术构建原生应用界面**：利用 C#、HTML 和 CSS 来创建桌面和移动应用的 UI，就像开发网站一样。
*   **获得原生应用的全部能力**：您的应用程序不是运行在浏览器沙箱中，而是作为一个真正的原生应用进程运行。这意味着它可以完全访问设备的所有原生功能，如文件系统、传感器、摄像头、蓝牙等。

它完美地结合了 **Web 开发的灵活性** 和 **原生应用的强大功能**。

### 核心工作原理：BlazorWebView

.NET MAUI Blazor 的核心是 `BlazorWebView` 控件。这是一个特殊的 .NET MAUI 控件，它的作用是在原生应用内部承载一个嵌入式的 Web 视图，并在其中渲染您的 Blazor 组件。

**工作流程如下**：

1.  您的 .NET MAUI 应用启动时，会创建一个窗口。
2.  `BlazorWebView` 控件在这个窗口内初始化。
3.  它会加载您的 Blazor 应用所需的静态资源（HTML, CSS, JavaScript）。
4.  您的 C# Blazor 组件代码（`.razor` 文件）在 .NET 进程中直接执行。
5.  Blazor 运行时通过一个高效的本地互操作通道，将 UI 的渲染指令发送给 `BlazorWebView`。
6.  `BlazorWebView` 将这些指令转换为原生 Web 视图可以理解的内容并显示出来。

**关键点**：所有代码，包括 UI 逻辑、业务逻辑和原生 API 调用，都运行在同一个 .NET 进程中。这与将网站打包成应用的方案（如 PWA 或 Cordova）有本质区别，后者通常受限于浏览器沙箱。

### 使用 .NET MAUI Blazor 的主要优势

1.  **代码重用和技能复用**
    *   **共享组件**：您可以为 Web 应用 (Blazor Server/WASM) 和原生桌面/移动应用 (.NET MAUI Blazor) 创建一套共用的 UI 组件库 (RCL)。
    *   **技能复用**：熟悉 Blazor、ASP.NET Core 或任何 Web 开发技术的团队可以快速上手构建原生应用，无需学习特定于平台的 UI 框架（如 XAML、SwiftUI 或 Jetpack Compose）。

2.  **完全访问原生平台 API**
    *   由于代码运行在原生进程中，您可以直接调用 .NET MAUI 提供的所有跨平台 API，或者通过条件编译编写特定于平台（Windows, Android, iOS, macOS）的代码。
    *   例如，从一个 Blazor 组件的 C# 代码中，您可以轻松地调用 `Geolocation.GetLocationAsync()` 来获取设备位置，或使用 `FileSystem.Current.AppDataDirectory` 访问应用数据目录。

3.  **丰富的生态系统**
    *   您可以利用庞大的 .NET 生态系统，包括数以万计的 NuGet 包。
    *   同时，您也可以使用为 Blazor 设计的各种 UI 组件库，如 MudBlazor、Telerik UI for Blazor 等。

4.  **现代化和渐进式迁移**
    *   对于希望现代化其老旧桌面应用（如 Windows Forms 或 WPF）的团队来说，.NET MAUI Blazor 提供了一个优秀的路径。 他们可以在现有应用中嵌入 `BlazorWebView`，逐步用现代的 Web UI 替换旧的 UI，而无需完全重写。

### 如何使用 .NET MAUI Blazor

#### 1. 项目类型

*   **.NET MAUI Blazor App**：这是最常见的模板。它创建一个完整的 .NET MAUI 应用，其主界面由一个全屏的 `BlazorWebView` 构成。整个应用的 UI 几乎完全由 Blazor 组件驱动。
*   **.NET MAUI App + BlazorWebView**：您可以从一个标准的 .NET MAUI 项目开始，然后在任何原生页面（ContentPage）的布局中，像添加其他原生控件（如 `Button` 或 `Label`）一样，添加一个 `BlazorWebView` 控件。这允许您在一个页面上混合使用原生 UI 控件和 Blazor Web 视图。

#### 2. 项目结构的关键文件

*   `MauiProgram.cs`: 应用的入口点。在这里，您需要注册 Blazor 服务，使用 `builder.Services.AddMauiBlazorWebView()`。
*   `MainPage.xaml`: 默认情况下，这个页面包含一个 `BlazorWebView` 控件。
*   `wwwroot/index.html`: Blazor 应用的宿主 HTML 页面。它通常非常简单，只包含一个根元素（如 `<div id="app"></div>`）和一个 Blazor 脚本引用。
*   `Components/`: 这个文件夹（或 `Pages/` 和 `Shared/` 在旧模板中）存放您所有的 Blazor Razor 组件。

#### 3. Blazor 与原生代码的交互

这是混合应用开发的核心。主要通过 **依赖注入 (Dependency Injection)** 和 **共享服务** 来实现。

**场景示例：从 Blazor 组件中触发原生弹窗**

1.  **创建服务接口和实现**
    ```csharp
    // 定义一个服务接口
    public interface INativeDialogService
    {
        Task ShowAlertAsync(string title, string message, string cancel);
    }

// 在 MAUI 项目中实现它
    public class NativeDialogServiceImpl : INativeDialogService
    {
        public Task ShowAlertAsync(string title, string message, string cancel)
        {
            // App.Current.MainPage 是对原生页面根的引用
            return App.Current.MainPage.DisplayAlert(title, message, cancel);
        }
    }
    ```

2.  **注册服务**
    在 `MauiProgram.cs` 中注册这个服务：
    ```csharp
    builder.Services.AddSingleton<INativeDialogService, NativeDialogServiceImpl>();
    ```

3.  **在 Blazor 组件中注入和使用**
    ```html
    @page "/native-test"
    @inject INativeDialogService DialogService

<h3>与原生功能交互</h3>
    <button @onclick="ShowNativeAlert">显示原生弹窗</button>

@code {
        private async Task ShowNativeAlert()
        {
            await DialogService.ShowAlertAsync("来自 Blazor", "这是一个由原生 UI 呈现的弹窗！", "好的");
        }
    }
    ```

通过这种模式，您的 Blazor 代码保持了平台无关性（它只知道 `INativeDialogService`），而具体的原生实现则被封装在 .NET MAUI 项目中。

### 总结

.NET MAUI Blazor 是一个功能强大的框架，它为 .NET 开发者开辟了一条使用 Web 技术构建全功能、高性能原生跨平台应用的新道路。如果您来自 Web 开发背景，或者希望在多个平台（Web、桌面、移动）之间最大化地共享 UI 和业务逻辑代码，那么 .NET MAUI Blazor 是一个非常值得考虑的选择。

评论区

先去登录

.NET跨端大杀器MAUI基础学习

相关推荐

评论区