SuperAPI AI 工具集

maui-device-capabilities

智能体与模型

查看项目

更新于 10-16 08:36

技能介绍

用途:当 MAUI 应用需要文件、媒体、相机、定位或地图等设备服务时使用本技能。核心原则是运行时 API 调用必须与平台声明配对,并提供用户友好的拒绝/取消处理路径。

主要能力与工作流:先检查目标平台及 Platforms/Android、Platforms/iOS、Platforms/MacCatalyst、Platforms/Windows 下的现有文件;确定所需能力与最小权限;在请求运行时权限前添加平台声明;在需要该功能时再请求权限,并先说明用途;把取消视为正常用户选择;若 ViewModel 或测试不应直接依赖 MAUI 静态 API,则把设备 API 封装在服务之后;在每个目标平台验证,因为权限名称与体验不同。

权限模式:用 Permissions.CheckStatusAsync<Permissions.LocationWhenInUse>() 检查,未授予则 Permissions.RequestAsync 请求;仍被拒绝时设置提示信息、CanOpenSettings,并用 SemanticScreenReader.Announce 播报。用户拒绝后不要反复弹窗,应显示可被屏幕阅读器感知的特定空/阻止状态,必要时用按钮调用 AppInfo.ShowSettingsUI() 引导到设置。

平台声明映射:相机/媒体采集按目标 SDK 行为仅在需要时添加 CAMERA 与媒体存储权限,iOS/Mac Catalyst 视情况添加 NSCameraUsageDescription、NSMicrophoneUsageDescription、NSPhotoLibraryUsageDescription;图库访问在 Android 12 及更早审计 READ_EXTERNAL_STORAGE,Android 13+ 使用 READ_MEDIA_IMAGES、READ_MEDIA_VIDEO 或 READ_MEDIA_AUDIO,或优先系统照片选择器;定位使用 ACCESS_COARSE_LOCATION、ACCESS_FINE_LOCATION,仅真正后台场景才加后台定位,iOS 用 NSLocationWhenInUseUsageDescription;文件选择通常无需宽泛存储权限;地图需平台 API 密钥/配置及 UseMauiMaps()。应使用与功能匹配的最窄声明,不要“以防万一”添加后台定位、宽泛存储或麦克风。

选择器与传感器护栏:FilePicker.PickAsync 与 PickMultipleAsync 需处理 null、空结果、取消和 PermissionException;MediaPicker 拍照前检查 IsCaptureSupported;需要持久访问时把所选文件流复制到应用存储;Geolocation.GetLastKnownLocationAsync 可能过期,应使用 GetLocationAsync 配合 GeolocationRequest 获取当前位置;谨慎选择 DesiredAccuracy,非必要用中低精度省电;可取消或页面消失时传入取消令牌;迁移应用需审计旧 Xamarin 的 READ_EXTERNAL_STORAGE 声明。

权限体验:在需要时而非首次启动时询问;调用平台提示前说明用户收益;拒绝时提供有用回退;用 SemanticProperties.Description、SemanticScreenReader.Announce 或聚焦说明标签让拒绝/阻止状态可见并播报;避免拒绝后立即重复请求的循环;受影响 UI 用 AutomationId 使错误/取消状态可测试。

验证清单:清单/plist 只含功能所需声明;运行时权限请求先于需要它的能力 API;拒绝与取消流程不崩溃;拒绝权限 UI 可见、可访问,并在平台需手动启用时提供设置入口;需要持久访问时复制所选文件/媒体;定位代码处理过期最后已知数据、超时与取消。