android-navigation-deeplinks

Android 导航深层链接

适用场景

• 请求涉及以下内容时使用此技能：Android 导航图、深层链接到 Android 应用、Compose Nav 中的返回堆栈问题。
• 主要目标：处理 Android 应用的导航图、返回堆栈行为、应用链接、Intent 和目标项归属。
• 超出此范围时移交给以下技能：
• android-permissions-activity-results
• android-testing-ui

工作流

1. 确认用户可见的流程、目标设备上的行为，以及需要关注的失败状态。
2. 确定此流程所属的屏幕、Activity、目标项和状态持有者。
3. 实现此流程，并明确处理加载、成功、空数据和错误状态。
4. 在示例应用中验证无障碍功能、配置变更和返回堆栈行为。
5. 将数据、架构或发布方面的问题移交给交接说明中列出的专用技能。

防护措施

• 将加载、空数据、错误、离线和权限被拒状态视为一等 UI 状态。
• 不要将导航或权限的副作用隐藏在可复用 UI 组件中。
• 优先使用感知生命周期的 API，而不是手动回调链。
• 确保深层链接、Intent 和权限提示可测试且可观测。

反模式

• 认为产品流程只需覆盖理想路径即可。
• 在多个位置硬编码请求代码或路由字符串。
• 直接从仓库或网络层触发导航。
• 发布缺少恢复 UI 的流程，导致权限被拒或状态异常时用户无从处理。

修复示例

集中管理路由归属

sealed interface OrbitRoute {
    data object Board : OrbitRoute
    data class Task(val taskId: String) : OrbitRoute
}

保持符合预期的返回堆栈行为

navController.navigate(OrbitRoute.Task(taskId)) {
    launchSingleTop = true
    restoreState = true
}

在同一处解析深层链接参数

val taskId = intent?.data?.getQueryParameter("taskId")
require(!taskId.isNullOrBlank()) { "Missing taskId deep-link argument" }

示例

理想路径

• 场景：通过深层链接，将 Compose 示例应用导航至任务详情目标项。
• 命令：cd examples/orbittasks-compose && ./gradlew :app:testDebugUnitTest

边界情况

• 场景：从链接冷启动 XML Activity 时，保持符合预期的 Up 和 Back 行为。
• 命令：cd examples/orbittasks-xml && ./gradlew :app:testDebugUnitTest

失败恢复

• 场景：避免用户对权限、状态和发布提示感到困惑。
• 命令：python3 scripts/eval_triggers.py --skill android-navigation-deeplinks

完成检查清单

• 实现路径明确、精简，并对应正确的 Android 界面。
• 已执行或更新相关示例命令和基准测试提示词。
• 请求涉及相邻技能时，已记录相应的移交说明。
• 官方参考资料涵盖所选模式，以及主要的迁移或故障排查路径。

官方参考资料

• https://developer.android.com/guide/navigation
• https://developer.android.com/guide/navigation/design
• https://developer.android.com/training/app-links
• https://developer.android.com/guide/components/intents-filters