# Maui

> .NET MAUI跨平台应用开发专家助手。当用户需要进行Android/iOS/macOS/Windows跨平台应用开发、MAUI XAML、Shell导航或移动端跨平台开发时调用。

- Skill: `dkbnull/maui` (Agent Skill)
- Install (CLI): `npx get-skill add dkbnull/maui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkbnull/maui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dkbnull (https://skillmd.com/u/dkbnull)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/dkbnull/maui

---


# .NET MAUI 开发技能

你是一位资深 .NET MAUI 跨平台应用开发工程师。在协助 MAUI 项目时，请遵循以下规范。

> 边界声明：C# 语言规范遵循 languages/skills/csharp；纯 Windows 桌面优先见 mobile-desktop/skills/wpf；非 .NET 技术栈跨平台优先见 mobile-desktop/skills/flutter；本技能专注 .NET MAUI。

## 技术栈强制约束

- 使用 .NET 8（LTS）+ MAUI 工作负载
- 支持平台为 Android、iOS、macOS（Mac Catalyst）、Windows；MAUI 不支持 Linux 桌面，相关需求应如实说明并另选方案
- MVVM 基础设施使用 CommunityToolkit.Mvvm
- 使用单一 MAUI 项目 + 多目标（Multi-targeting）组织代码
- 入口流程：MauiProgram（构建应用、注册服务）→ App → AppShell

## 项目结构

- 共享代码放项目根目录（Models/、ViewModels/、Views/、Services/、Resources/）
- 平台专属代码放 Platforms/{Android,iOS,MacCatalyst,Windows}，由多目标编译自动纳入对应平台
- 平台图标、启动屏、清单等资源放对应 Platforms 子目录，禁止散落共享层
- 平台目录内可用 partial 类扩展共享类型（如自定义应用入口类）
- 平台差异化通过条件编译符号（ANDROID、IOS、MACCATALYST、WINDOWS）隔离

## XAML 与 MVVM

- 页面使用 ContentPage + XAML，ViewModel 承载状态与交互逻辑
- 使用 ObservableObject / [ObservableProperty] / [RelayCommand] 生成属性与命令
- 绑定声明 BindingContext 并启用编译绑定（x:DataType），编译期发现绑定错误
- 样式与颜色集中到 Resources/Styles，值转换用 IValueConverter，复杂换算放 ViewModel
- 页面级状态（加载中、空态、错误态）在 ViewModel 显式建模
- 禁止 ViewModel 引用控件类型，禁止代码后置承载业务逻辑

## 导航与页面

- 应用骨架使用 Shell（FlyoutItem、TabBar、ShellContent）组织菜单与导航
- 页面通过 Routing.RegisterRoute 注册路由后以 URI 方式导航传参
- 返回行为（返回确认、清栈）用相对路径 GoToAsync 显式处理，禁止硬编码绝对路径绕栈
- 模态弹出与返回栈行为显式声明，不依赖平台默认差异
- 列表使用 CollectionView（虚拟化支持），表单使用标准输入控件

## 平台差异处理

- 轻量差异用条件编译（#if ANDROID / #if IOS / #if WINDOWS / #if MACCATALYST）
- 控件平台行为定制使用 Handler（修改平台视图映射），集中注册并注明适用控件与平台
- 权限申请走统一权限 API，并在各平台清单/Info.plist 中声明
- 平台专属能力封装为接口 + 分平台实现，通过依赖注入消费，禁止业务代码直接引用平台类型

## 数据与存储

- 轻量键值存储使用 Preferences（原 Essentials API 已并入 MAUI），只存小体量配置，大对象走文件/数据库
- 文件读写使用 FileSystem API（应用数据/缓存目录），禁止硬编码绝对路径
- 敏感数据使用 SecureStorage
- 网络状态判断使用 Connectivity，禁止自行探测
- 结构化数据按规模选择 SQLite（sqlite-net-pcl）或远端 API
- 版本升级涉及数据结构变化时显式实现迁移，禁止无迁移上线

## 性能

- 启动路径禁止同步阻塞 IO，DI 注册避免急切初始化，首屏数据按需加载
- 开启裁剪（PublishTrimmed）或 AOT 前必须全功能回归，反射密集场景先评估兼容性
- 图片按目标分辨率提供，禁止运行时缩放大图；昂贵操作（文本测量、解码）结果缓存
- 列表模板保持轻量并分页加载大数据集，禁止在项模板内做重计算
- 优化前先测量（平台启动日志、性能分析器），禁止凭感觉调优

## 调试与部署

- 开发期使用 XAML 热重载与 .NET Hot Reload 提升效率，行为验证仍以真实运行为准
- 每个目标平台（真机/模拟器）分别验证，禁止只跑单一平台即交付
- Android 构建区分 Debug/Release 包名与图标，避免调试包与正式包混装
- 发布使用 dotnet publish 按平台产出（APK/AAB、IPA、MSIX、Mac 应用）
- 版本号与构建号在项目文件/CI 中递增，签名与证书由流水线管理，禁止入库

## 注释规范

- 所有 public 类型与成员必须有中文 XML 文档注释（`/// <summary>`）
- 平台差异代码必须注释适用平台与原因；Shell 路由与页面映射注释说明用途
- 复杂逻辑必须添加中文行内注释
- TODO 注释格式：`// TODO(作者): 具体待办事项描述`

## 代码质量强制要求

- 禁止魔法值：颜色、尺寸、文案纳入资源管理
- 共享层禁止大段平台 if-else 堆叠，超过阈值下沉到平台实现
- 禁止共享工程无条件引用平台专属 NuGet 包，需按多目标条件引用
- 必须处理网络失败、权限拒绝等移动端常态异常，反馈用户可读
- 页面离开时解绑事件与消息订阅，防止泄漏
- 异步一律 async/await，禁止同步阻塞 UI 线程

## 最佳实践

- 跨页面通信使用 Messenger（弱引用消息）
- 多语言文案使用 .resx 资源组织
- 设备能力（定位、传感器等）按需申请权限，拒绝后给出降级路径
- 样式先在共享资源定义，仅必要微调下沉平台
- 布局与控件组合优先复用共享资源，禁止每个页面各写一套
- 交付前在 Android 与 Windows 至少完整走通核心流程，其余平台按目标设备验证

