NextUI.Blazor MAUI Blazor Hybrid 支持

概述

NextUI.Blazor 已完全支持在 .NET MAUI Blazor Hybrid 应用中使用，包括 iOS、Android、macOS 和 Windows 平台。

iOS/Mac Catalyst 静态资源打包

问题背景

在 iOS 构建时，.NET MAUI 构建系统在处理 Razor Class Library (RCL) 的静态资源时，可能会出现路径解析问题，导致警告：

warning: The path '...' would result in a file outside of the app bundle and cannot be used.

如果这些警告被忽略，当 NextUI.Blazor 作为 NuGet 包被 MAUI Blazor Hybrid 应用引用时，静态资源可能无法正确打包到应用包中，导致运行时资源加载失败。

解决方案

NextUI.Blazor 项目已针对 iOS/Mac Catalyst 目标框架进行了特殊配置：

<!-- iOS/Mac Catalyst: 显式配置静态资源为 MauiAsset，确保在 MAUI Blazor Hybrid 应用中正确打包 -->
<ItemGroup Condition="'$(TargetFramework)' == 'net10.0-ios' OR '$(TargetFramework)' == 'net10.0-maccatalyst'">
    <!-- 排除 wwwroot 下的文件从默认的 Static Web Assets 处理 -->
    <Content Remove="wwwroot\**\*" />
    <!-- 显式添加为 MauiAsset，使用相对于项目根目录的路径 -->
    <MauiAsset Include="wwwroot\**\*" />
</ItemGroup>

效果

  • ✅ 完全消除 wwwroot 下静态资源的 iOS 构建警告
  • ✅ 完全消除 Razor 组件源码（*.razor）被误判为 BundleResource 导致的 “outside of the app bundle” 警告（保持它们仅作为编译输入）
  • ✅ 确保 在 MAUI Blazor Hybrid 应用中，所有静态资源（CSS、JS、字体、图标等）都能正确打包到应用包中
  • ✅ 兼容 纯 Blazor WebAssembly 应用（如 Workbench），不影响现有功能

验证

构建 iOS 目标框架时，wwwroot 下的静态资源警告数量为 0：

dotnet build -f net10.0-ios src/NextUI.Blazor/NextUI.Blazor.csproj 2>&1 | grep -c "wwwroot.*would result"
# 输出: 0

在 MAUI Blazor Hybrid 应用中使用

1. 安装 NuGet 包

dotnet add package NextUI.Blazor

2. 引用静态资源

在 MAUI Blazor Hybrid 应用的 HTML 文件中（通常是 wwwroot/index.html 或 Pages/_Host.cshtml），使用 _content/{PackageId}/ 前缀引用静态资源：

<!-- CSS -->
<link href="_content/NextUI.Blazor/Styles/sx-tokens.css" rel="stylesheet" />

<!-- JavaScript -->
<script src="_content/NextUI.Blazor/js/theme-runtime.js" type="module"></script>

3. 注册服务与原生支持

在 MauiProgram.cs 中注册 NextUI 服务。特别注意： 在 MAUI 环境下，由于 JavaScript 运行时不支持同步调用，必须注册原生的 IUserPreferences 实现以支持主题和设置的持久化。

using NextUI.Blazor;
using NextUI.Core;
using NextUI.Samples.Maui.Services; // 包含自定义的 MauiUserPreferences

builder.Services.AddNextDesignSystem();

// 核心修复：在 MAUI 中使用原生 Preferences 覆盖掉 BrowserUserPreferences
builder.Services.AddScoped<IUserPreferences, MauiUserPreferences>();

MauiUserPreferences 的实现参考：

public sealed class MauiUserPreferences : IUserPreferences
{
    public string Get(string key, string defaultValue) => Preferences.Default.Get(key, defaultValue);
    public void Set(string key, string value) => Preferences.Default.Set(key, value);
    // ... 其他类型的实现
}

4. 使用组件

在 Razor 页面中使用 NextUI 组件：

@using NextUI.Blazor.Components

<SxButton>Click Me</SxButton>

平台兼容性

平台 支持状态 说明
iOS ✅ 完全支持 静态资源正确打包，无警告
Android ✅ 完全支持 标准支持
macOS (Mac Catalyst) ✅ 完全支持 静态资源正确打包，无警告
Windows ✅ 完全支持 标准支持

注意事项

Razor 组件文件警告

构建 iOS 目标框架时，可能会看到 Razor 组件文件（.razor）的警告：

warning: The path '...Components/SxButton.razor' would result in a file outside of the app bundle...

我们建议彻底消除这些告警（而不是忽略），原因是它们会淹没真实问题并降低 CI 信噪比。做法是在 iOS/Mac Catalyst 构建下，显式从 BundleResource（以及相关资源打包链路）中移除 **/*.razor，保证这些文件只参与编译、不参与 app bundle 资源打包。

静态资源访问路径

在 MAUI Blazor Hybrid 应用中，静态资源必须通过 _content/{PackageId}/ 路径访问，而不是直接路径。这是 .NET MAUI 的标准约定。

相关文档