AtomUI.Mobile.Controls 平台 Adapter

状态：预实现架构。本文定义已批准的目标契约，不表示当前仓库已经包含或发布 AtomUI.Mobile.Controls。

Mobile 使用一个内部 capability contract，由 Headless、iOS 和 Android adapter 分别实现。Control 和 Runtime scope 只消费统一 snapshot、事件与 hook，不读取 OS 名称，也不在具体 Control 中散布条件编译。

Capability Contract

能力	统一输出/入口	Owner
Safe Area 与 system bars	Insets、available bounds 和变化通知	Adapter 读取平台；`MobileViewportContext` 合并状态
Input pane / IME	Occlusion、可用性和变化通知	Adapter 投递；Viewport/输入 Control 协调消费
Back 与 navigation gesture	单次可仲裁的系统输入	Adapter 投递；Overlay/Navigation 决定 owner
Haptic	可用性与受约束调用入口	Adapter 执行；Control policy 决定是否请求
Touch profile	已解析的最小触控目标和 interaction profile	Adapter/profile 提供；Theme/Control 消费值
Foreground/background	Host 状态、恢复和 detach/recreation 通知	Host/adapter 投递；Runtime scope 统一清理或恢复
Reduce Motion 与 font scale	一致 snapshot 字段	Adapter 投递；Viewport 发布
Accessibility environment	平台环境和能力状态	Adapter 投递；Control 仍拥有 AutomationPeer 语义

平台 adapter 提供事实与 hook，不决定 Control 视觉、Token、导航结果、Overlay 关闭原因或默认产品行为。

实现角色

Adapter	目标用途	不能证明
Headless	注入确定 snapshot、模拟能力缺失、验证状态机和 acquire/release	iOS/Android 触摸、IME、系统返回或无障碍体验
iOS	投射 iOS Host 生命周期、viewport、输入、返回手势、haptic 和 accessibility 环境	Android 行为或发布状态
Android	投射 Android Host 生命周期、system back、viewport、输入、haptic 和 accessibility 环境	iOS 行为或发布状态

iOS 是首个实现平台，但三个 adapter 从 Foundation 使用相同 contract。iOS 适配不能把平台 SDK 类型、pt 特例或 Host 生命周期泄漏到 Public Control API；Android 适配不能在后续通过修改公共契约追补基本能力。

Owner 生命周期

Host 在 AtomUI 组合根提供 adapter。
每个 TopLevel attach 时，Mobile Runtime scope acquire 与 adapter 建立 owner-scoped subscription。
Adapter 在 UI thread 边界投递原始变化；Runtime 合并为一致 snapshot。
TopLevel detach、Host recreation 或应用终止时取消 pending work，并释放 subscription、hook 和 owner 引用。
新 Host/TopLevel 创建新的 scope；旧 adapter 不通过 static cache 保留 Visual、Control 或 session。

如果 native hook 需要跨线程回调，adapter 必须在进入 Runtime 前完成线程和 lifetime 归一化，不能让 Control 直接处理原生回调。

能力缺失

缺失能力	退化行为
Safe Area/system bar 来源	使用零 inset 并保留可诊断状态
Input pane bounds	保持最近一致 viewport，不猜测键盘高度
Haptic	跳过反馈，不改变逻辑终态和事件顺序
系统返回/gesture	显式导航命令继续使用同一事务
Reduce Motion	移除非必要动效，保持提交、焦点和 cleanup
Host detach	以统一原因终止 session、pointer chain 和订阅

必需 adapter 缺失或重复属于启动/acquire 配置错误，不使用静默 fallback。可选 capability 缺失则按上表退化，Control 不通过 OS 名称猜测值。

Native 边界

Adapter 优先使用 Avalonia 公共 API。只有能力涉及 P/Invoke、native handle、原生结构体、协议对象或可释放 hook，且 Avalonia 公共 API 无法表达时，才调用 AtomUI.Native。Native 负责参数/handle 校验、底层调用、错误转换和确定释放；Mobile adapter 负责 owner、订阅、状态归一化和产品侧调用时机。

验证

Contract/Headless：snapshot 合并、能力缺失、重复 adapter、detach、取消和无残留引用。
iOS：Simulator 与真机分别验证 Safe Area、IME、返回手势、旋转、前后台、VoiceOver 和 haptic 降级。
Android：Emulator 与真机分别验证 system bars、IME、system back、multi-window、Activity recreation、TalkBack 和 haptic 降级。
Release：两个平台分别验证 trim/AOT 后 adapter、Theme、Localization 和 DataTemplate 可发现，产物可安装启动。

测试层级与证据要求见 Mobile 验证架构。当前没有 adapter 源码或平台通过证据。

4.7 KiB Raw Permalink Blame History Unescape Escape