android-jetpack

android-jetpack

用途

此技能提供用于集成 Android Jetpack 组件的工具，帮助构建高效、易维护的 Android 应用，重点涵盖 Room 数据库、Navigation 界面流转、WorkManager 后台任务、DataStore 偏好设置、CameraX 相机操作、Hilt 依赖注入和 Paging 3 数据加载。

适用场景

在构建需要持久化存储（例如，使用 Room 操作 SQLite）、页面间导航（例如，Navigation Component）、定时任务（例如，WorkManager）、安全偏好设置（例如，DataStore）、相机功能（例如，CameraX）、模块化依赖注入（例如，Hilt）或高效分页（例如，Paging 3）的 Android 应用时，使用此技能。适用于数据流复杂、需要后台处理或与硬件交互的应用。

核心功能

• Room：SQLite 数据库的 ORM；支持实体、DAO 和迁移。
• Navigation：通过 NavController 管理 Fragment 事务和深层链接。
• WorkManager：调度可延迟任务，并支持网络可用性等约束。
• DataStore：使用 Protocol Buffers 进行类型化存储，以取代 SharedPreferences。
• CameraX：抽象相机硬件，支持预览、拍摄和分析。
• Hilt：通过 Android 专用注解简化 Dagger 依赖注入。
• Paging 3：按页加载列表数据，并可与 LiveData 或 Flow 集成。

使用模式

要使用 Room，请在 build.gradle 中添加依赖项：implementation 'androidx.room:room-runtime:2.5.0'。定义一个 Entity：@Entity class User(val id: Int, val name: String)。创建一个 DAO：interface UserDao { @Query("SELECT * FROM user") fun getAll(): List<User> }。设置数据库：Room.databaseBuilder(context, AppDatabase::class.java, "database-name").build()。

要使用 Navigation，请在 build.gradle 中添加：implementation 'androidx.navigation:navigation-fragment-ktx:2.5.0'。在 XML 中创建 Nav Graph：<navigation xmlns:android="http://schemas.android.com/apk/res/android" ...> <fragment android:id="@+id/mainFragment" ...> <action android:id="@+id/action_to_detail" app:destination="@id/detailFragment" /> </fragment> </navigation>。在代码中导航：findNavController().navigate(R.id.action_to_detail)。

通过添加以下依赖项集成 Hilt：implementation 'com.google.dagger:hilt-android:2.44'。为应用添加注解：@HiltAndroidApp class MyApp : Application()。注入依赖项：@AndroidEntryPoint class MainActivity : AppCompatActivity() { @Inject lateinit var viewModel: MyViewModel }。

要使用 WorkManager，请将任务加入队列：WorkManager.getInstance(context).enqueue(OneTimeWorkRequestBuilder<MyWorker>().build())。定义 Worker：class MyWorker(context: Context, params: WorkerParameters) : Worker(context, params) { override fun doWork(): Result { // Perform task return Result.success() } }。

使用 DataStore 保存偏好设置：添加 implementation 'androidx.datastore:datastore-preferences:1.0.0'。访问它：val dataStore = applicationContext.dataStore。读写数据：dataStore.edit { settings -> settings[STRING_KEY] = "value" }。

使用 CameraX 时，绑定相机：ProcessCameraProvider.getInstance(context).use { provider -> val camera = provider.bindToLifecycle(this, cameraSelector, preview) }。配置预览：val preview = Preview.Builder().build().also { it.setSurfaceProvider(viewFinder.surfaceProvider) }。

要使用 Paging 3，请创建 PagingSource：class UserPagingSource : PagingSource<Int, User>() { override suspend fun load(params: LoadParams<Int>): LoadResult<Int, User> { // Fetch data return LoadResult.Page(data, prevKey, nextKey) } }。在 ViewModel 中使用：val pager = Pager(config) { UserPagingSource() }.flow。

常用命令/API

• Room CLI：使用 ./gradlew dependencies 验证 Room 集成。进行迁移时，通过 ADB 运行数据库查询：adb shell sqlite3 /data/data/your.package/databases/yourdb "PRAGMA user_version;"。
• Navigation API：调用 NavController.navigate(actionId) 执行页面跳转。在 Nav Graph 中使用深层链接：<deepLink app:uri="yourapp://details/{id}" />。
• WorkManager API：使用约束将任务加入队列：OneTimeWorkRequestBuilder<MyWorker>().setConstraints(Constraints.Builder().setRequiredNetworkType(NetworkType.CONNECTED).build()).build()。查询状态：WorkManager.getInstance().getWorkInfosForUniqueWork("workName").observe(...)。
• DataStore API：读取偏好设置：dataStore.data.map { preferences -> preferences[STRING_KEY] }。处理数据流：使用 collect { value -> /* process */ }。
• CameraX API：拍摄图像：imageCapture.takePicture(outputFileOptions, executor, object : ImageCapture.OnImageSavedCallback { override fun onImageSaved(output: ImageCapture.OutputFileResults) { // Handle saved file } })。
• Hilt API：使用 ./gradlew hiltGenerateSources 生成代码。注入模块：@Module @InstallIn(SingletonComponent::class) class AppModule { @Provides fun provideService(): Service = Service() }。
• Paging 3 API：与 RemoteMediator 结合使用，以支持网络和数据库：Pager( config = PagingConfig(pageSize = 20), remoteMediator = UserRemoteMediator(), pagingSourceFactory = { UserPagingSource() } )。

集成说明

通过为数据库添加注解，将 Room 与 Hilt 集成：@Database(entities = [User::class], version = 1) @HiltDatabase abstract class AppDatabase : RoomDatabase() { abstract fun userDao(): UserDao }。对于 WorkManager 和 Navigation，可在 fragment 中观察任务状态：WorkManager.getInstance().getWorkInfoByIdLiveData(workId).observe(viewLifecycleOwner) { info -> if (info.state == WorkInfo.State.SUCCEEDED) navigateToResult() }。将 DataStore 与 Paging 配合使用：在 DataStore 中存储分页键，并通过数据流读取。对于 CameraX，确保权限已授予：使用 ContextCompat.checkSelfPermission(context, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED 检查。如果需要 API 密钥（例如 WorkManager 中外部服务的密钥），可在 build.gradle 或 strings.xml 中使用 $GOOGLE_API_KEY 等环境变量。将 Paging 与 Room 结合：在 PagingSource 中使用 Room 作为数据源。

错误处理

对于 Room，捕获 SQLite 异常：try { dao.insert(user) } catch (e: SQLiteConstraintException) { Log.e("RoomError", e.message ?: "Constraint violation") }。处理 Navigation 错误：使用 NavController.addOnDestinationChangedListener 捕获无效操作。对于 WorkManager，在 doWork 中检查 Result.retry()：if (error) return Result.retry()。DataStore 错误：使用 try-catch 捕获 IOException。CameraX：使用 try { provider.unbindAll() } catch (e: IllegalStateException) { Log.e("CameraError", "Binding failed") } 处理 CameraX.bindToLifecycle 失败。Hilt：检查 @Inject 注解并运行 ./gradlew clean，以解决注入错误。Paging 3：捕获 LoadState 错误：pager.loadStateFlow.collect { state -> if (state.refresh is LoadState.Error) Log.e("PagingError", state.refresh.error.message ?: "Load failed") }。

具体使用示例

1. 示例：使用 Room 和 Hilt 的用户应用：在 ViewModel 中注入 Room DAO：@HiltViewModel class UserViewModel @Inject constructor(private val userDao: UserDao) : ViewModel() { fun getUsers() = userDao.getAll() }。在 Activity 中：使用 Hilt 注入并显示数据：viewModel.getUsers().observe(this) { users -> adapter.submitList(users) }。
2. 示例：使用 WorkManager 和 DataStore 进行后台同步：将 worker 加入队列以获取数据并存储到 DataStore：WorkManager.enqueue(OneTimeWorkRequestBuilder<SyncWorker>().build())。在 worker 中：dataStore.edit { it[LAST_SYNC_KEY] = System.currentTimeMillis() }。然后，在 UI 中读取 DataStore 以检查上次同步时间。

图关系

• Room 依赖：Android 核心组件（用于 SQLite）和 Hilt（用于注入）。
• Navigation 集成：WorkManager（用于异步导航）和 Paging 3（用于列表导航）。
• WorkManager 关联：DataStore（用于存储结果）和 CameraX（用于后台处理）。
• DataStore 连接：Room（作为替代存储）和 Hilt（用于注入式访问）。
• CameraX 链接：Navigation（用于相机 UI 流程）。
• Hilt 为以下组件提供注入：所有其他组件（Room、WorkManager 等）。
• Paging 3 与以下组件协同工作：Room（作为数据源）和 Navigation（用于无限列表）。