第十章：硬件访问与原生功能集成

本章导读：想象你是一位建筑师，正在设计一座横跨四个大陆的桥梁。每个大陆都有自己的地形规则、建筑法规和材料标准。在 iOS 大陆，你需要遵守 CoreLocation 的法则；在 Android 平原，LocationManager 和动态权限是你必须应对的挑战；而在 Web 海洋中，JavaScript 的 navigator.geolocation 是唯一的通行证。Uno Platform 就是那位神奇的翻译官，它让你用一种语言——Windows.Devices 命名空间——与四个世界对话。本章将揭开这场跨平台硬件访问的"魔术"背后的秘密。

🎭 10.1 跨平台硬件访问的"魔术"

在正式深入技术细节之前，让我们先理解一个看似矛盾的现象：为什么 Uno Platform 能够让你用 Windows 的 API 在 Android、iOS 和 Web 上运行？这听起来就像是用美元在北京买早餐一样不可思议。

答案藏在编译器的魔法之中。Uno Platform 实现了 WinUI 的 Windows.Devices 命名空间，这意味着你编写的每一行 C# 代码，在编译时都会被自动"翻译"成对应平台的原生调用。当你在 Android 上调用 Geolocator.GetGeopositionAsync() 时，Uno 的内核会在底层调用 Android 的 LocationManager；在 iOS 上，它会调用 CoreLocation；在 WebAssembly 中，它会通过 JavaScript 互操作调用 navigator.geolocation.getCurrentPosition()。

第一性原理：跨平台抽象的本质不是消除差异，而是将差异转移到编译时。运行时的统一体验，源于编译时的精确映射。这就像国际会议中的同声传译——听众只需要理解一种语言，而翻译官在后台完成了所有的转换工作。

🔬 10.1.1 这真的是"黑魔法"吗？

当然不是。Uno Platform 的硬件抽象层（Hardware Abstraction Layer，简称 HAL）是一个精心设计的桥梁。它由三个核心组件构成：首先是 接口层，暴露给开发者的 WinUI 风格 API；其次是 映射层，负责将通用 API 转换为平台特定调用；最后是 适配层，直接与各平台的底层框架通信。

这种架构设计有一个美妙的名字——桥梁模式（Bridge Pattern）。想象一座连接两岸的物理桥梁：桥面（接口层）对所有人都是一样的，但桥墩（适配层）必须根据河床的地质条件进行定制。Uno Platform 的 genius 就在于它为每条"河流"（平台）都准备了恰到好处的桥墩。

📍 10.2 地理位置服务：从坐标到世界

获取用户位置是移动应用的基石功能。无论是外卖配送、打车服务，还是社交签到，地理位置都是连接数字世界与物理世界的纽带。让我们以 Geolocator 类为例，深入了解 Uno Platform 如何处理这一核心功能。

🎯 10.2.1 位置服务的核心概念

在开始编码之前，我们需要理解几个关键概念。地理坐标系统是地球表面的点定位标准，最常用的是 WGS-84 坐标系，它使用经度（Longitude）和纬度（Latitude）两个数值来唯一确定地球上的任何一点。经度的范围是 \([-180°, +180°]\)，以英国格林威治天文台为本初子午线；纬度的范围是 \([-90°, +90°]\)，以赤道为零度。

费曼技巧提问：如果你要向一个十岁的孩子解释 GPS 定位是如何工作的，你会怎么说？

想象地球是一个巨大的橙子，你在橙子表面画了两组线：一组从北极连到南极（经线），另一组平行于赤道环绕橙子（纬线）。GPS 卫星就像天上的灯塔，它们不断发送信号说"我在这里，现在是几点"。你的手机接收到至少四颗卫星的信号后，通过计算信号传播的时间，就能算出你在橙子表面的确切位置——就像通过听到四座教堂的钟声时间差，来推断自己的位置一样。

💻 10.2.2 Geolocator 的实战应用

让我们通过一段完整的代码来理解位置获取的流程：

using Windows.Devices.Geolocation;

public class LocationService
{
    private Geolocator _geolocator;

    public LocationService()
    {
        // 创建地理定位器实例
        // Geolocator 是 Uno 对各平台定位服务的统一抽象
        _geolocator = new Geolocator();

        // 设置期望精度（单位：米）
        // 精度越高，耗电量越大，定位时间越长
        // 50米是一个平衡精度与性能的良好选择
        _geolocator.DesiredAccuracyInMeters = 50;

        // 监听位置状态变化
        // 当设备的定位能力发生变化时（如用户关闭 GPS），会触发此事件
        _geolocator.StatusChanged += OnStatusChanged;
    }

    /// <summary>
    /// 获取当前设备的地理位置
    /// </summary>
    /// <returns>包含经纬度的位置信息</returns>
    public async Task<BasicGeoposition> GetCurrentLocationAsync()
    {
        try
        {
            // GetGeopositionAsync 是一个异步操作
            // 它会触发系统的定位服务，可能需要几秒钟
            // maximumAge 参数表示可接受的缓存位置年龄（这里设为5分钟）
            // timeout 参数表示最大等待时间
            Geoposition position = await _geolocator.GetGeopositionAsync(
                maximumAge: TimeSpan.FromMinutes(5),
                timeout: TimeSpan.FromSeconds(30)
            );

            // 从 Geoposition 中提取坐标信息
            // Point.Position 是一个 BasicGeoposition 结构体
            // 包含 Latitude（纬度）、Longitude（经度）和 Altitude（海拔）
            BasicGeoposition coordinates = position.Coordinate.Point.Position;

            // 获取精度信息（单位：米）
            // 这个值告诉你坐标的误差范围
            double accuracy = position.Coordinate.Accuracy;

            // 如果有海拔信息（并非所有设备都支持）
            double? altitude = position.Coordinate.Point.Position.Altitude;

            return coordinates;
        }
        catch (UnauthorizedAccessException)
        {
            // 用户拒绝了位置权限
            // 这是最常见的异常，需要友好地引导用户去设置中开启权限
            throw new LocationPermissionDeniedException("请在系统设置中允许应用访问位置信息");
        }
        catch (TaskCanceledException)
        {
            // 定位超时
            // 可能是因为 GPS 信号弱（如室内环境）
            throw new LocationTimeoutException("定位超时，请确保处于开阔区域");
        }
        catch (Exception ex)
        {
            // 其他未预期的错误
            throw new LocationException({{LATEX:2}}"摄像头初始化失败: {ex.Message}");
        }
    }

    /// <summary>
    /// 拍摄照片并保存到指定文件
    /// </summary>
    public async Task CapturePhotoAsync(StorageFile outputFile)
    {
        if (!_isInitialized)
            throw new InvalidOperationException("摄像头未初始化");

        // 创建编码属性
        var imageEncoding = ImageEncodingProperties.CreateJpeg();

        // 拍摄并保存
        await _mediaCapture.CapturePhotoToStorageFileAsync(imageEncoding, outputFile);
    }

    /// <summary>
    /// 切换前后摄像头
    /// </summary>
    public async Task SwitchCameraAsync()
    {
        // 获取所有可用的摄像头
        var allVideoDevices = await DeviceInformation.FindAllAsync(DeviceClass.VideoCapture);

        // 查找当前使用的摄像头
        var currentDevice = allVideoDevices.FirstOrDefault(d =>
            d.Id == _mediaCapture.MediaCaptureSettings.VideoDeviceId);

        // 选择另一个摄像头（前/后切换）
        var newDevice = allVideoDevices.FirstOrDefault(d =>
            d.Id != currentDevice?.Id);

        if (newDevice != null)
        {
            // 需要重新初始化 MediaCapture
            // 实际应用中，这通常需要重新创建整个 MediaCapture 实例
        }
    }

    public void Dispose()
    {
        _mediaCapture?.Dispose();
    }
}

技术术语：CaptureElement 是 Uno Platform 特有的控件，用于显示摄像头的实时预览。在 WASM 平台上，它会被渲染为 HTML5 的 <video> 标签；在 Android 和 iOS 上，它使用各自的原生预览视图。

📁 10.5 文件系统与沙盒：安全的数据访问

跨平台文件访问面临两个核心挑战：路径差异（每个平台有不同的文件系统结构）和沙盒限制（移动应用只能访问受限的目录）。Uno Platform 通过 StorageFile 和 StorageFolder API 提供了统一的解决方案。

🔓 10.5.1 文件选取器：让用户决定

FileOpenPicker 是访问用户文件的最佳方式，因为它能自动处理各平台的文件选择逻辑，同时尊重用户的选择权。

using Windows.Storage;
using Windows.Storage.Pickers;

public class FilePickerService
{
    /// <summary>
    /// 让用户选择一张图片
    /// </summary>
    public async Task<StorageFile> PickImageAsync()
    {
        // 创建文件打开选择器
        var picker = new FileOpenPicker();

        // 设置视图模式（列表或缩略图）
        // 对于图片选择，缩略图视图更友好
        picker.ViewMode = PickerViewMode.Thumbnail;

        // 设置初始位置
        // PicturesLibrary 是一个已知文件夹，会自动映射到各平台的图片目录
        picker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;

        // 添加允许的文件类型
        // 用户只能看到并选择这些类型的文件
        picker.FileTypeFilter.Add(".jpg");
        picker.FileTypeFilter.Add(".jpeg");
        picker.FileTypeFilter.Add(".png");
        picker.FileTypeFilter.Add(".gif");
        picker.FileTypeFilter.Add(".bmp");

        // 显示选择器并等待用户选择
        StorageFile file = await picker.PickSingleFileAsync();

        return file; // 如果用户取消，返回 null
    }

    /// <summary>
    /// 让用户选择多个文件
    /// </summary>
    public async Task<IReadOnlyList<StorageFile>> PickMultipleFilesAsync()
    {
        var picker = new FileOpenPicker();
        picker.ViewMode = PickerViewMode.List;
        picker.FileTypeFilter.Add("*"); // 允许所有文件类型

        // 选择多个文件
        IReadOnlyList<StorageFile> files = await picker.PickMultipleFilesAsync();

        return files;
    }

    /// <summary>
    /// 让用户选择保存位置
    /// </summary>
    public async Task<StorageFile> SaveFileAsync(string suggestedName)
    {
        var picker = new FileSavePicker();

        // 建议的文件名
        picker.SuggestedFileName = suggestedName;

        // 添加可用的文件类型选项
        // 第一个类型会是默认选项
        picker.FileTypeChoices.Add("文本文档", new List<string> { ".txt" });
        picker.FileTypeChoices.Add("JSON 文件", new List<string> { ".json" });

        // 显示选择器
        StorageFile file = await picker.PickSaveFileAsync();

        return file;
    }
}

💾 10.5.2 本地应用存储：私有的数据家园

每个应用都有自己私有的存储空间，用于保存配置、缓存和用户数据。Uno Platform 通过 ApplicationData 类提供了统一的访问方式。

using Windows.Storage;

public class LocalStorageService
{
    // LocalFolder：应用私有存储，会随应用卸载而删除
    // 用于存储用户数据、数据库文件等
    private StorageFolder LocalFolder => ApplicationData.Current.LocalFolder;

    // RoamingFolder：漫游存储，会在用户的所有设备间同步
    // 注意：有大小限制（通常为 100KB），仅用于少量配置
    private StorageFolder RoamingFolder => ApplicationData.Current.RoamingFolder;

    // TemporaryFolder：临时存储，系统可能随时清理
    // 用于缓存文件、下载的临时内容等
    private StorageFolder TempFolder => ApplicationData.Current.TemporaryFolder;

    /// <summary>
    /// 保存文本内容到本地文件
    /// </summary>
    public async Task SaveTextAsync(string fileName, string content)
    {
        // 在 LocalFolder 中创建或覆盖文件
        StorageFile file = await LocalFolder.CreateFileAsync(
            fileName,
            CreationCollisionOption.ReplaceExisting
        );

        // 写入文本内容
        await FileIO.WriteTextAsync(file, content);
    }

    /// <summary>
    /// 从本地文件读取文本内容
    /// </summary>
    public async Task<string> ReadTextAsync(string fileName)
    {
        try
        {
            // 获取文件引用
            StorageFile file = await LocalFolder.GetFileAsync(fileName);

            // 读取文本内容
            return await FileIO.ReadTextAsync(file);
        }
        catch (FileNotFoundException)
        {
            return null; // 文件不存在
        }
    }

    /// <summary>
    /// 保存应用设置（键值对）
    /// </summary>
    public void SaveSetting(string key, object value)
    {
        // ApplicationDataContainer 是一个轻量级的键值存储
        // 适合存储用户偏好、应用配置等
        ApplicationDataContainer settings = ApplicationData.Current.LocalSettings;

        // 支持的基本类型：int, string, float, bool, DateTime, Guid 等
        settings.Values[key] = value;
    }

    /// <summary>
    /// 读取应用设置
    /// </summary>
    public T GetSetting<T>(string key, T defaultValue = default)
    {
        ApplicationDataContainer settings = ApplicationData.Current.LocalSettings;

        if (settings.Values.TryGetValue(key, out object value))
        {
            return (T)value;
        }

        return defaultValue;
    }

    /// <summary>
    /// 获取本地存储的路径（用于调试）
    /// </summary>
    public string GetLocalFolderPath()
    {
        // 这个路径在不同平台上不同：
        // Windows: C:\Users\{User}\AppData\Local\Packages\{AppId}\LocalState
        // Android: /data/data/{PackageId}/files
        // iOS: /var/mobile/Containers/Data/Application/{GUID}/Library
        // WASM: 浏览器 IndexedDB（虚拟文件系统）
        return LocalFolder.Path;
    }
}

费曼技巧提问：为什么移动应用不能随意访问文件系统？想象你住在一个安全的公寓里，每个住户都有自己的房间和储物柜。你可以自由地在自己的房间里存放东西，但不能随便进入别人的房间。沙盒机制就是这样一种安全边界——它保护了用户的隐私，防止恶意应用窃取其他应用的数据。

🚪 10.6 原生 API 逃逸舱：突破抽象的边界

Uno Platform 的抽象层覆盖了绝大多数常见场景，但有时候你需要调用某个平台独有的功能——比如 Android 的前台服务、iOS 的 Touch ID、或者 Web 的特定 JavaScript API。这时候，你需要使用条件编译配合部分类（Partial Classes）。

🔧 10.6.1 部分类模式：优雅的平台适配

部分类是 C# 的一个强大特性，它允许将一个类的定义分散在多个文件中。在 Uno Platform 中，我们可以利用这个特性将通用接口和平台实现分离。

首先，在 Shared 项目中定义接口和部分声明：

// 文件位置：Shared/Services/DeviceInfo.cs
namespace MyUnoApp.Services
{
    /// <summary>
    /// 设备信息服务 - 跨平台接口
    /// </summary>
    public partial class DeviceInfo
    {
        /// <summary>
        /// 获取设备型号
        /// </summary>
        public partial string GetModel();

        /// <summary>
        /// 获取操作系统版本
        /// </summary>
        public partial string GetOsVersion();

        /// <summary>
        /// 检查是否为低电量模式
        /// </summary>
        public partial bool IsLowPowerMode();
    }
}

然后，在 Android 项目中实现：

// 文件位置：Platforms/Android/Services/DeviceInfo.android.cs
using Android.OS;

namespace MyUnoApp.Services
{
    public partial class DeviceInfo
    {
        public partial string GetModel()
        {
            // 使用 Android API 获取设备型号
            // Build.Model 返回设备制造商定义的型号名称
            // 如 "SM-G991B" (Samsung Galaxy S21)
            return Build.Model;
        }

        public partial string GetOsVersion()
        {
            // 返回 Android 版本，如 "12"
            return Build.VERSION.Release;
        }

        public partial bool IsLowPowerMode()
        {
            // Android 5.0+ 的省电模式检测
            if (Build.VERSION.SdkInt >= BuildVersionCodes.Lollipop)
            {
                var powerManager = Android.App.Application.Context
                    .GetSystemService(Android.Content.Context.PowerService)
                    as PowerManager;

                return powerManager?.IsPowerSaveMode ?? false;
            }

            return false;
        }
    }
}

在 iOS 项目中实现：

// 文件位置：Platforms/iOS/Services/DeviceInfo.ios.cs
using UIKit;

namespace MyUnoApp.Services
{
    public partial class DeviceInfo
    {
        public partial string GetModel()
        {
            // UIDevice.CurrentDevice.Model 返回 "iPhone" 或 "iPad"
            // 如果需要具体型号（如 "iPhone14,2"），需要调用底层 sysctl API
            return UIDevice.CurrentDevice.Model;
        }

        public partial string GetOsVersion()
        {
            // 返回 iOS 版本，如 "15.4"
            return UIDevice.CurrentDevice.SystemVersion;
        }

        public partial bool IsLowPowerMode()
        {
            // iOS 9+ 的低电量模式检测
            // 需要 import UIKit
            return NSProcessInfo.ProcessInfo.LowPowerModeEnabled;
        }
    }
}

在 WebAssembly 项目中实现：

// 文件位置：Platforms/WebAssembly/Services/DeviceInfo.wasm.cs
using System.Runtime.InteropServices.JavaScript;

namespace MyUnoApp.Services
{
    public partial class DeviceInfo
    {
        public partial string GetModel()
        {
            // Web 平台没有传统意义上的"设备型号"
            // 可以通过 User-Agent 分析，但这不可靠
            return "Web Browser";
        }

        public partial string GetOsVersion()
        {
            // 可以通过 JavaScript 互操作获取一些信息
            // navigator.userAgent 包含浏览器和操作系统信息
            return GetUserAgent();
        }

        public partial bool IsLowPowerMode()
        {
            // Web 平台没有低电量模式的概念
            // 但可以通过 Battery API 检测电量
            return false;
        }

        // JavaScript 互操作示例
        [JSImport("globalThis.navigator.userAgent")]
        private static partial string GetUserAgent();
    }
}

🎯 10.6.2 条件编译：更精细的控制

对于简单的平台差异，你可以使用 条件编译符号 直接在 Shared 项目中编写不同平台的代码：

public string GetPlatformSpecificMessage()
{
    // 注意：这些条件编译符号由 Uno Platform 自动定义
    // 你不需要在 .csproj 中手动配置

#if WINDOWS
    return "运行在 Windows 上";
#elif __ANDROID__
    return {{LATEX:3}}"运行在 iOS {UIKit.UIDevice.CurrentDevice.SystemVersion} 上";
#elif HAS_UNO_WASM
    return "运行在 WebAssembly 上";
#else
    return "运行在未知平台";
#endif
}

第一性原理：为什么选择部分类而不是接口+依赖注入？部分类模式的优势在于编译时绑定——编译器会检查每个平台是否完整实现了所有部分方法。相比之下，接口模式需要在运行时通过反射或配置来注入正确的实现。对于平台适配这种"编译时就确定"的场景，部分类更加简洁和安全。

📝 本章小结

通过本章的学习，你已经掌握了跨平台硬件交互的精髓。从地理位置到传感器，从摄像头到文件系统，Uno Platform 不仅提供了高度抽象的 WinUI 风格 API，还通过灵活的逃逸机制确保你不会被限制在"抽象的牢笼"中。

现在，让我们回顾本章的核心要点：

第一，Uno Platform 的硬件抽象层通过编译时映射，让你用统一的 Windows.Devices API 调用各平台的原生功能。这种设计既保持了代码的简洁性，又不失平台的灵活性。

第二，权限管理是跨平台开发的永恒主题。虽然 C# 代码可以统一，但各平台的权限声明机制仍然独立，需要在对应的配置文件中正确设置。

第三，传感器数据的坐标系对齐是 Uno Platform 的一项重要工作。你不需要关心 Android 和 iOS 坐标系的差异，Uno 已经在底层为你处理好了。

第四，对于平台特有的功能，部分类模式提供了一个优雅的解决方案。它保持了共享代码的简洁，同时允许平台特定的实现自由发挥。

在下一章中，我们将进入 Uno Platform 的一个极具魅力的领域——WebAssembly 深度集成。我们将探讨如何在浏览器中发挥 C# 的极致性能，并与现有的 JavaScript 生态系统进行互操作。

动手实验：

1. 位置追踪器：创建一个简单的位置追踪应用，在地图上显示用户当前位置，并记录用户的移动轨迹。尝试处理权限被拒绝的情况，并提供友好的引导界面。
2. 摇一摇功能：使用加速度计实现"摇一摇"功能——当用户摇晃设备时，随机显示一条名言或执行某个操作。注意设置合适的阈值以避免误触发。
3. 跨平台文件管理器：实现一个简单的文件管理器，允许用户选择、查看和保存文本文件。在不同平台上测试，体验 Uno Platform 的文件抽象层。