安卓开发指南

技能文档

---
name: android-dev-pro
title: 安卓开发指南
category: 开发工具
description: >
  安卓应用开发指南，覆盖Material Design 3、Jetpack Compose、Kotlin协程、架构模式等现代Android开发最佳实践。
  支持UI设计、导航模式、响应式布局、无障碍开发、权限管理等场景。
  当用户需要开发Android应用、使用Jetpack Compose、实现Material Design或处理安卓兼容性问题时触发。
  触发词：Android开发、Jetpack Compose、Material Design、Kotlin、安卓UI、移动开发。
---

# 安卓开发指南

现代Android开发最佳实践指南，覆盖Material Design 3和Jetpack Compose。

## 1. Material You 与主题

### 动态颜色
Android 12+默认支持基于壁纸的动态颜色主题：

```kotlin
@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context)
            else dynamicLightColorScheme(context)
        }
        darkTheme -> darkColorScheme()
        else -> lightColorScheme()
    }
    MaterialTheme(
        colorScheme = colorScheme,
        typography = AppTypography,
        content = content
    )
}
```

**规则**：
- 必须提供Android 12以下的静态颜色回退方案
- 禁止在组件中硬编码颜色值，始终引用主题颜色角色
- 至少用3种不同壁纸测试动态颜色协调性

### 颜色角色

| 角色 | 用途 |
|------|------|
| primary | 关键操作、活跃状态、FAB |
| secondary | 辅助UI、筛选标签 |
| tertiary | 强调色、对比补充 |
| surface | 背景、卡片、底部抽屉 |
| error | 错误状态、破坏性操作 |

## 2. 导航模式

### 导航组件选择

| 屏幕尺寸 | 3-5个目的地 | 5+个目的地 |
|----------|-------------|------------|
| 紧凑(<600dp) | 底部导航栏 | 模态抽屉+底部导航 |
| 中等(600-839dp) | 导航栏 | 模态抽屉+导航栏 |
| 展开(840dp+) | 导航栏 | 固定抽屉 |

**规则**：
- 底部导航栏用于3-5个顶级目的地
- 始终显示标签，不允许纯图标导航
- 选中状态使用填充图标，未选中使用轮廓图标
- 活跃指示器使用 `secondaryContainer` 颜色

### 预测性返回手势
Android 13+支持预测性返回动画：
- 在Manifest中启用 `enableOnBackInvokedCallback`
- 使用 `OnBackInvokedCallback` 替代 `onBackPressed()`

## 3. 响应式布局

### 窗口尺寸类别

```kotlin
val windowSizeClass = calculateWindowSizeClass(this)
when (windowSizeClass.widthSizeClass) {
    WindowWidthSizeClass.Compact -> CompactLayout()
    WindowWidthSizeClass.Medium -> MediumLayout()
    WindowWidthSizeClass.Expanded -> ExpandedLayout()
}
```

| 类别 | 宽度 | 典型设备 |
|------|------|----------|
| Compact | <600dp | 手机竖屏 |
| Medium | 600-839dp | 平板竖屏 |
| Expanded | 840dp+ | 平板横屏 |

### 全面屏显示
Android 15+强制全面屏，应用须绘制到系统栏后面：
- 在 `setContent` 前调用 `enableEdgeToEdge()`
- 使用 `WindowInsets` 处理系统栏内边距

## 4. 排版

### Material 字体层级

| 角色 | 大小 | 用途 |
|------|------|------|
| displayLarge | 57sp | 英雄文本 |
| headlineLarge | 32sp | 屏幕标题 |
| titleLarge | 22sp | 应用栏标题 |
| bodyLarge | 16sp | 正文 |
| labelLarge | 14sp | 按钮标签 |

**规则**：
- 始终使用 `sp` 单位支持用户字体缩放
- 正文最小12sp，标签最小11sp
- 通过 `MaterialTheme.typography` 引用，不硬编码

## 5. 核心组件

### 组件选择指南

| 需求 | 组件 |
|------|------|
| 屏幕主要操作 | FAB |
| 简短反馈 | Snackbar |
| 关键决策 | Dialog |
| 补充内容 | Bottom Sheet |
| 切换筛选 | Filter Chip |
| 用户输入标签 | Input Chip |

**FAB规则**：
- 每屏最多1个FAB
- 位于屏幕右下角
- 优先使用带标签的 ExtendedFloatingActionButton

## 6. 无障碍

- 所有交互元素必须有 `contentDescription`
- 最小触摸目标 48x48dp
- 文本对比度 >= 4.5:1
- 不仅用颜色传达信息
- 支持TalkBack、Switch Access和键盘导航

## 7. 权限与隐私

- 在使用时请求权限，不在启动时
- 请求前展示权限用途说明
- 优雅处理权限拒绝
- Android 13+使用Photo Picker替代媒体权限

## 反模式警示

| 反模式 | 正确做法 |
|--------|----------|
| 硬编码颜色 | 使用主题颜色角色 |
| 用dp设置文字大小 | 使用sp单位 |
| 自定义底部导航 | 使用Material NavigationBar |
| 无标签导航栏 | 始终显示文字标签 |
| 纯黑暗色主题 | 使用Material surface颜色 |
| 启动时请求权限 | 在上下文中请求 |

## 使用指引

1. 说明开发需求（UI/导航/布局/组件）
2. 获取符合Material Design 3的代码示例
3. 按最佳实践实现功能
4. 使用评估清单检查质量

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。