使用 Android Jetpack 的 Room 部分将数据保存到本地数据库。
处理大量结构化数据的应用可极大地受益于在本地保留这些数据。最常见的使用场景是缓存相关的数据,这样一来,当设备无法访问网络时,用户仍然可以在离线状态下浏览该内容。
Room 持久性库在 SQLite 上提供了一个抽象层,以便在充分利用 SQLite 的强大功能的同时,能够流畅地访问数据库。具体来说,Room 具有以下优势:
- 提供针对 SQL 查询的编译时验证。
- 提供方便注解,可最大限度减少重复和容易出错的样板代码。
- 简化了数据库迁移路径。
出于这些方面的考虑,我们强烈建议您使用 Room,而不是直接使用 SQLite API。
设置
如需在应用中使用 Room,请将以下依赖项添加到应用的 build.gradle
文件。
dependencies { val room_version = "2.6.1" implementation("androidx.room:room-runtime:$room_version") // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP) // See Add the KSP plugin to your project ksp("androidx.room:room-compiler:$room_version") // If this project only uses Java source, use the Java annotationProcessor // No additional plugins are necessary annotationProcessor("androidx.room:room-compiler:$room_version") // optional - Kotlin Extensions and Coroutines support for Room implementation("androidx.room:room-ktx:$room_version") // optional - RxJava2 support for Room implementation("androidx.room:room-rxjava2:$room_version") // optional - RxJava3 support for Room implementation("androidx.room:room-rxjava3:$room_version") // optional - Guava support for Room, including Optional and ListenableFuture implementation("androidx.room:room-guava:$room_version") // optional - Test helpers testImplementation("androidx.room:room-testing:$room_version") // optional - Paging 3 Integration implementation("androidx.room:room-paging:$room_version") }
dependencies { def room_version = "2.6.1" implementation "androidx.room:room-runtime:$room_version" // If this project uses any Kotlin source, use Kotlin Symbol Processing (KSP) // See KSP Quickstart to add KSP to your build ksp "androidx.room:room-compiler:$room_version" // If this project only uses Java source, use the Java annotationProcessor // No additional plugins are necessary annotationProcessor "androidx.room:room-compiler:$room_version" // optional - RxJava2 support for Room implementation "androidx.room:room-rxjava2:$room_version" // optional - RxJava3 support for Room implementation "androidx.room:room-rxjava3:$room_version" // optional - Guava support for Room, including Optional and ListenableFuture implementation "androidx.room:room-guava:$room_version" // optional - Test helpers testImplementation "androidx.room:room-testing:$room_version" // optional - Paging 3 Integration implementation "androidx.room:room-paging:$room_version" }
主要组件
Room 包含三个主要组件:
- 数据库类,用于保存数据库并作为应用持久性数据底层连接的主要访问点。
- 数据实体,用于表示应用的数据库中的表。
- 数据访问对象 (DAO),为您的应用提供在数据库中查询、更新、插入和删除数据的方法。
数据库类为应用提供与该数据库关联的 DAO 的实例。反过来,应用可以使用 DAO 从数据库中检索数据,作为关联的数据实体对象的实例。此外,应用还可以使用定义的数据实体更新相应表中的行,或者创建新行供插入。图 1 说明了 Room 的不同组件之间的关系。

实现示例
本部分介绍了具有单个数据实体和单个 DAO 的 Room 数据库实现示例。
数据实体
以下代码定义了一个 User
数据实体。User
的每个实例都代表应用数据库中 user
表中的一行。
@Entity data class User( @PrimaryKey val uid: Int, @ColumnInfo(name = "first_name") val firstName: String?, @ColumnInfo(name = "last_name") val lastName: String? )
@Entity public class User { @PrimaryKey public int uid; @ColumnInfo(name = "first_name") public String firstName; @ColumnInfo(name = "last_name") public String lastName; }
如需详细了解 Room 中的数据实体,请参阅使用 Room 实体定义数据。
数据访问对象 (DAO)
以下代码定义了一个名为 UserDao
的 DAO。UserDao
提供了应用的其余部分与 user
表中的数据交互的方法。
@Dao interface UserDao { @Query("SELECT * FROM user") fun getAll(): List<User> @Query("SELECT * FROM user WHERE uid IN (:userIds)") fun loadAllByIds(userIds: IntArray): List<User> @Query("SELECT * FROM user WHERE first_name LIKE :first AND " + "last_name LIKE :last LIMIT 1") fun findByName(first: String, last: String): User @Insert fun insertAll(vararg users: User) @Delete fun delete(user: User) }
@Dao public interface UserDao { @Query("SELECT * FROM user") List<User> getAll(); @Query("SELECT * FROM user WHERE uid IN (:userIds)") List<User> loadAllByIds(int[] userIds); @Query("SELECT * FROM user WHERE first_name LIKE :first AND " + "last_name LIKE :last LIMIT 1") User findByName(String first, String last); @Insert void insertAll(User... users); @Delete void delete(User user); }
如需详细了解 DAO,请参阅使用 Room DAO 访问数据。
数据库
以下代码定义了用于保存数据库的 AppDatabase
类。
AppDatabase
定义数据库配置,并作为应用对持久性数据的主要访问点。数据库类必须满足以下条件:
- 该类必须带有
@Database
注解,该注解包含列出所有与数据库关联的数据实体的entities
数组。 - 该类必须是一个抽象类,用于扩展
RoomDatabase
。 - 对于与数据库关联的每个 DAO 类,数据库类必须定义一个具有零参数的抽象方法,并返回 DAO 类的实例。
@Database(entities = [User::class], version = 1) abstract class AppDatabase : RoomDatabase() { abstract fun userDao(): UserDao }
@Database(entities = {User.class}, version = 1) public abstract class AppDatabase extends RoomDatabase { public abstract UserDao userDao(); }
注意:如果您的应用在单个进程中运行,在实例化 AppDatabase
对象时应遵循单例设计模式。每个 RoomDatabase
实例的成本相当高,而您几乎不需要在单个进程中访问多个实例。
如果您的应用在多个进程中运行,请在数据库构建器调用中包含 enableMultiInstanceInvalidation()
。这样,如果您在每个进程中都有一个 AppDatabase
实例,可以在一个进程中使共享数据库文件失效,并且这种失效会自动传播到其他进程中 AppDatabase
的实例。
用法
定义数据实体、DAO 和数据库对象后,您可以使用以下代码创建数据库实例:
val db = Room.databaseBuilder( applicationContext, AppDatabase::class.java, "database-name" ).build()
AppDatabase db = Room.databaseBuilder(getApplicationContext(), AppDatabase.class, "database-name").build();
然后,您可以使用 AppDatabase
中的抽象方法获取 DAO 的实例,转而可以使用 DAO 实例中的方法与数据库进行交互:
val userDao = db.userDao() val users: List<User> = userDao.getAll()
UserDao userDao = db.userDao(); List<User> users = userDao.getAll();
其他资源
如需详细了解 Room,请参阅下面列出的其他资源:
示例
您可以在一条文本字符串中支持多个链接,以便用户选择要前往的位置并提高互动度。 您可以设置文本的部分样式,以提高可读性、提升用户体验,并通过使用颜色和字体来激发更大的创造力。 您可以在用户在文本字段中输入内容(例如输入姓名、电子邮件地址、地址或其他联系信息)时验证输入内容。此验证可减少错误并为用户节省时间。 如需在应用中显示图片(用于内容和响应用户操作),请从磁盘或互联网上的外部来源加载图片。 卡片可为界面提供 Material Design 容器。 使用 TopAppBar 可组合项创建顶部应用栏,以帮助用户在应用中导航和访问功能。 了解如何使用 Compose Animation API 为状态值添加动画效果、使用转场效果添加动画效果、为可见性或大小更改添加动画效果,以及添加交叉淡化效果。 应用栏是位于屏幕顶部或底部的容器,其中包含主要功能和导航项。 您可以创建一个图标,以便根据用户的切换开关隐藏或显示密码,从而提高安全性并提升用户体验。 您可以加载可绘制文件来显示动画图片,从而在应用中打造更具互动性和吸引力的用户体验。动画图片非常适合用于创建加载指示器、成功或错误指示器,以及促进游戏开发和各种其他界面功能。 限制应用在小屏设备上的屏幕方向,但不限制其在大屏设备上的屏幕方向。 您可以在图片的剪裁区域周围绘制阴影,以便以剪辑的形状显示图片。 了解如何管理可拆卸键盘配置更改。 进度指示器会显示操作的状态。 创建分页列表,以便用户滚动浏览无法在一屏中显示的内容。水平分页列表可帮助用户浏览图片、幻灯片或商品轮播界面等内容。垂直分页列表非常适合内容丰富的应用,在这些应用中,用户可能需要滚动浏览大量内容(例如文章)。 您可以使用切换开关让用户选择两种状态之一。 为界面选择合适的组件,并了解如何在应用中实现该组件。 按钮可触发特定操作。 条状标签组件可直观地表示复杂的实体,通常包含图标和标签。 构建您的首个 Jetpack Compose 测试。了解如何使用 Compose 的测试工件编写界面测试、使用测试规则、查找器和断言。 用户可以通过悬浮操作按钮在应用中执行主要操作。 拒绝触控笔手掌误触。 对话框会在应用主要内容之上的层上显示弹出式消息或请求用户输入。 框架可将界面的不同部分(例如应用栏和悬浮操作按钮)整合在一起,从而让应用具有一致的外观和风格。支持在单个文本字符串中添加多个链接
设置文本的部分样式
在用户输入时验证输入内容
加载和显示图片
创建一个用作容器的卡片
显示顶部应用栏
Compose 中的动画
显示应用栏
根据用户切换开关显示或隐藏密码
显示动画图片
限制应用在手机上的屏幕方向,但不限制其在大屏设备上的屏幕方向
显示裁剪为某个形状的图片
管理可拆卸键盘配置变更
创建进度指示器
显示分页列表
添加用户可以切换的开关
显示互动组件
创建按钮
创建用于表示复杂实体的条状标签
在 Compose 中进行测试
创建悬浮操作按钮 (FAB)
拒绝触控笔手掌轻触
显示弹出式消息或请求用户输入
创建一个框架组件来将界面整合在一起