hz-android-2d-porting

将 Android 2D 应用移植到 Horizon OS

适用场景

在以下情况下使用此技能：

• 将现有 Android 2D 应用移植到 Meta VR 头显上运行
• 为 Horizon OS 面板适配移动端 Android 应用
• 排查 Meta VR 设备上 2D 应用的输入、布局或兼容性问题
• 为 Android 应用准备 Horizon Store 提交
• 评估现有 Android 应用是否兼容 Horizon OS

概述

Horizon OS 基于 Android（AOSP）构建，可在 面板 中运行标准 Android 应用——面板是位于 3D 空间中的浮动 2D 窗口。大多数构建良好的 Android 应用只需少量改动，就能在 Meta VR 设备上运行，但仍有几个方面需要注意：

1. 输入：没有触摸屏。用户通过控制器指针（射线投射）、手部追踪或连接的外设进行交互。
2. 布局：应用运行在可调整大小的面板中，而不是固定显示屏上的全屏模式。
3. 兼容性：依赖项和权限必须在没有 Google Play Services 或不具备相关硬件的情况下正常工作。
4. 设计与性能：应用必须符合 Horizon Store 针对移动硬件的要求。

移植的目标是在保留现有功能的同时，让应用融入 Meta VR 体验。

移植工作流

步骤 1：初步测试

按照常规 Android 工作流构建并安装现有应用。Android Studio、Gradle 和 adb 均可与已连接的 Meta VR 设备配合使用：

./gradlew installDebug
adb shell am start -n com.example.yourapp/.MainActivity

此处优先使用 metavr app install <apk> 和 metavr app launch <package>，而不是直接使用 adb；首次运行期间，通过 metavr adb logcat --follow 持续查看日志。记录是否出现即时崩溃、黑屏、输入问题或布局错乱。

步骤 2：兼容性审查

在修改 UI 之前，检查应用是否依赖 Google Play Services、不受支持的硬件或禁止的权限。将不受支持的功能设为可选，或替换为 Horizon OS 的替代方案。请参阅兼容性要求。

步骤 3：输入适配

最常见的移植问题是输入。触摸事件会转换为控制器指针输入，但：

• 悬停状态现在会显示出来（用户会先指向，再单击）
• 滚动使用摇杆，而不是滑动手势
• 多点触控手势（捏合缩放）无法直接转换
• 点击目标必须足够大，确保指针操作准确（最小 48dp）

详细指南请参阅输入适配参考。

步骤 4：布局调整

面板可调整大小，并支持各种宽高比。应用必须能够处理：

• 动态宽度和高度变化
• 横屏和竖屏方向
• 不同的有效 DPI 值

使用响应式 Android 布局和窗口尺寸断点。请参阅面板布局参考。

步骤 5：Gradle 和清单更新

更新构建配置以面向 Horizon OS：

// build.gradle.kts
android {
    defaultConfig {
        minSdk = 29       // Android 10 minimum
        targetSdk = 34    // API 34 or higher required for all new 2D panel apps
    }
}

添加必要的清单条目以指定设备目标。请参阅 Gradle 设置参考。

步骤 6：输入测试

使用所有受支持的输入方式进行测试：

• 控制器：指向并单击、摇杆滚动、扳机点击
• 手部追踪：捏合选择、手部滚动
• 键盘/鼠标：蓝牙外设、用于文本字段的系统键盘

使用 Meta Spatial Simulator 快速进行桌面端迭代，然后通过 Meta Horizon OS Android Studio 插件或常规 ADB 工具在设备上验证。每轮输入测试期间都保持 metavr adb logcat --follow 运行——它能捕获不会导致明显崩溃的输入错误。

步骤 7：商店提交

提交到 Horizon Store 之前：

• 确认符合所有兼容性要求
• 在至少 Quest 3、Quest 3S 和 Quest 2（如果目标设备包含这些型号）以及 Meta VR Glasses 上进行测试
• 确认应用在透视和沉浸式主场景中均可正常运行
• 查看 Meta 的内容政策和技术要求

快速兼容性检查

适用于 Horizon OS

功能	状态	备注
标准 Android 视图	支持	TextView、RecyclerView 等
Jetpack Compose	支持	完整的 Compose UI 工具包
React Native	支持	使用标准 Android 应用路径
WebView	支持	基于 Chromium
媒体播放（ExoPlayer）	支持	视频和音频
网络（HTTP、WebSocket）	支持	Wi-Fi 连接
Room / SQLite	支持	本地数据库
WorkManager	支持	后台任务
通知	支持	Horizon OS 通知面板
Bluetooth（外设）	支持	键盘、鼠标、游戏手柄
Android 无障碍 API	支持	提供 TalkBack 的等效功能

受限或不可用

功能	状态	备注
电话 / SMS	不可用	无蜂窝无线电
NFC	不可用	无 NFC 硬件
GPS / 精确位置	受限	仅支持基于 Wi-Fi 的定位
指纹 / BiometricPrompt	不可用	请改用 Meta 账户身份验证
多个由应用拥有的面板	受限	有可用的最新公开多面板指南时，请参阅该指南
Google Play Services	不可用	请使用 Meta 等效服务或替代方案
ARCore	不可用	空间功能请使用 Meta Spatial SDK
多点触控手势	受限	控制器仅提供单指针

常见问题与解决方法

问题	原因	解决方法
应用启动时崩溃	缺少 Google Play Services 依赖项	移除 GMS，或将其设为可选
按钮太小，难以点击	触控目标小于 48dp	增大最小点击目标尺寸
键盘未显示	自定义输入字段未使用 InputConnection	使用标准 EditText 或 TextField
布局异常	假设布局尺寸固定	使用响应式视图或 Compose 布局
应用请求不可用的权限	电话、NFC 或其他缺失硬件	使用 hasSystemFeature() 检查进行保护
APK 因权限违规被拒绝	库或插件悄悄添加了违规权限	运行 aapt dump permissions your-app.apk，然后检查禁止权限列表
APK 因签名无效被拒绝	仅使用 v1 签名方案签名	AGP 7.0+ 默认使用 v2 签名；对于较旧的 AGP，请在签名配置中添加 v2SigningEnabled = true

测试工具

• Meta Horizon OS Android Studio 插件：设备连接、部署和 Horizon OS 开发支持
• Meta Spatial Simulator：在桌面上模拟 Horizon OS 上的 2D Android 应用
• Android Studio、Gradle 和 ADB：标准 Android 构建、安装、启动和 logcat 工作流
• metavr：用于设备和应用操作的可选命令行便捷工具

性能注意事项

Meta VR 设备采用移动级硬件，且有严格的热限制：

• GPU：Qualcomm Adreno（因型号而异）
• RAM：6-12 GB，由系统和应用共享
• 热量：持续运行的工作负载可能触发热节流
• 避免在 2D UI 中使用大量过度绘制和复杂的着色器效果
• 尽量减少后台工作，以降低功耗
• 使用有代表性的数据负载进行测试（大型列表、图像等）

参考资料

• 兼容性要求 -- 商店要求和 API 兼容性
• 输入适配 -- 将触控输入适配为控制器和手部输入
• 面板布局 -- Horizon OS 面板的响应式布局
• Gradle 设置 -- 构建配置和清单条目