ViewModel 的保存状态模块 Android Jetpack 的一部分。
如 保存 UI 状态 中所述,ViewModel
对象可以处理配置更改,因此您无需担心旋转或其他情况下的状态。但是,如果您需要处理系统启动的进程终止,您可能需要使用 SavedStateHandle
API 作为备份。
UI 状态通常存储或引用在 ViewModel
对象中,而不是 Activity 中,因此使用 onSaveInstanceState()
或 rememberSaveable
需要一些样板代码,而 保存状态模块 可以为您处理这些。
使用此模块时,ViewModel
对象会通过其构造函数接收一个 SavedStateHandle
对象。此对象是一个键值对映射,可让您向保存状态写入对象以及从保存状态检索对象。这些值在进程被系统终止后仍然存在,并通过同一对象保持可用。
保存状态与您的任务堆栈绑定。如果您的任务堆栈消失,您的保存状态也会消失。当强制停止应用、从最近使用菜单中移除应用或重启设备时,可能会发生这种情况。在这种情况下,任务堆栈会消失,您无法恢复保存状态中的信息。在 用户启动的 UI 状态关闭 场景中,保存状态不会恢复。在 系统启动的 场景中,则会恢复。
设置
从 Fragment 1.2.0 或其传递依赖项 Activity 1.1.0 开始,您可以接受 SavedStateHandle
作为 ViewModel
的构造函数参数。
Kotlin
class SavedStateViewModel(private val state: SavedStateHandle) : ViewModel() { ... }
Java
public class SavedStateViewModel extends ViewModel { private SavedStateHandle state; public SavedStateViewModel(SavedStateHandle savedStateHandle) { state = savedStateHandle; } ... }
这样,您无需任何额外配置即可检索 ViewModel
实例。默认的 ViewModel
工厂会为您的 ViewModel
提供相应的 SavedStateHandle
。
Kotlin
class MainFragment : Fragment() { val vm: SavedStateViewModel by viewModels() ... }
Java
class MainFragment extends Fragment { private SavedStateViewModel vm; public void onViewCreated(@NonNull View view, Bundle savedInstanceState) { vm = new ViewModelProvider(this).get(SavedStateViewModel.class); ... } ... }
提供自定义 ViewModelProvider.Factory
实例时,您可以通过扩展 AbstractSavedStateViewModelFactory
来启用 SavedStateHandle
的使用。
使用 SavedStateHandle
SavedStateHandle
类是一个键值对映射,可让您通过 set()
和 get()
方法向保存状态写入数据以及从保存状态检索数据。
通过使用 SavedStateHandle
,查询值会在进程终止后保留下来,从而确保用户在重新创建前后看到相同的过滤数据,而无需 Activity 或 Fragment 手动保存、恢复和将该值转发回 ViewModel
。
SavedStateHandle
还有其他您在使用键值对映射时可能会预期的方法
contains(String key)
- 检查给定键是否存在值。remove(String key)
- 移除给定键的值。keys()
- 返回SavedStateHandle
中包含的所有键。
此外,您可以使用可观察数据容器从 SavedStateHandle
中检索值。支持的类型列表如下:
LiveData
使用 getLiveData()
从包装在 LiveData
可观察对象中的 SavedStateHandle
中检索值。当键的值更新时,LiveData
会收到新值。通常,该值是由于用户交互而设置的,例如输入查询以过滤数据列表。然后,此更新的值可用于转换 LiveData
。
Kotlin
class SavedStateViewModel(private val savedStateHandle: SavedStateHandle) : ViewModel() { val filteredData: LiveData<List<String>> = savedStateHandle.getLiveData<String>("query").switchMap { query -> repository.getFilteredData(query) } fun setQuery(query: String) { savedStateHandle["query"] = query } }
Java
public class SavedStateViewModel extends ViewModel { private SavedStateHandle savedStateHandle; public LiveData<List<String>> filteredData; public SavedStateViewModel(SavedStateHandle savedStateHandle) { this.savedStateHandle = savedStateHandle; LiveData<String> queryLiveData = savedStateHandle.getLiveData("query"); filteredData = Transformations.switchMap(queryLiveData, query -> { return repository.getFilteredData(query); }); } public void setQuery(String query) { savedStateHandle.set("query", query); } }
StateFlow
使用 getStateFlow()
从包装在 StateFlow
可观察对象中的 SavedStateHandle
中检索值。当您更新键的值时,StateFlow
会收到新值。通常,您可能会由于用户交互而设置该值,例如输入查询以过滤数据列表。然后,您可以使用其他 Flow 运算符转换此更新的值。
Kotlin
class SavedStateViewModel(private val savedStateHandle: SavedStateHandle) : ViewModel() { val filteredData: StateFlow<List<String>> = savedStateHandle.getStateFlow<String>("query") .flatMapLatest { query -> repository.getFilteredData(query) } fun setQuery(query: String) { savedStateHandle["query"] = query } }
实验性 Compose 状态支持
lifecycle-viewmodel-compose
工件提供了实验性的 saveable
API,这些 API 允许 SavedStateHandle
与 Compose 的 Saver
之间互操作,这样您可以使用自定义 Saver
通过 rememberSaveable
保存的任何 State
也可以使用 SavedStateHandle
保存。
Kotlin
class SavedStateViewModel(private val savedStateHandle: SavedStateHandle) : ViewModel() { var filteredData: List<String> by savedStateHandle.saveable { mutableStateOf(emptyList()) } fun setQuery(query: String) { withMutableSnapshot { filteredData += query } } }
支持的类型
保存在 SavedStateHandle
中的数据将作为 Bundle
与 Activity 或 Fragment 的其余 savedInstanceState
一起保存和恢复。
直接支持的类型
默认情况下,您可以在 SavedStateHandle
上为与 Bundle
相同的数据类型调用 set()
和 get()
,如下所示:
类型/类支持 | 数组支持 |
double |
double[] |
int |
int[] |
long |
long[] |
字符串 |
String[] |
byte |
byte[] |
char |
char[] |
CharSequence |
CharSequence[] |
float |
float[] |
Parcelable |
Parcelable[] |
Serializable |
Serializable[] |
short |
short[] |
SparseArray |
|
Binder |
|
Bundle |
|
ArrayList |
|
Size (仅限 API 21+) |
|
SizeF (仅限 API 21+) |
如果类没有扩展上述列表中的任一类,请考虑通过添加 @Parcelize
Kotlin 注解或直接实现 Parcelable
来使类可打包。
保存不可打包的类
如果一个类没有实现 Parcelable
或 Serializable
,并且无法修改以实现这些接口之一,则无法将该类的实例直接保存到 SavedStateHandle
中。
从 Lifecycle 2.3.0-alpha03 开始,SavedStateHandle
允许您通过使用 setSavedStateProvider()
方法提供您自己的逻辑来将任何对象保存和恢复为 Bundle
。 SavedStateRegistry.SavedStateProvider
是一个接口,它定义了一个 saveState()
方法,该方法返回一个包含您要保存的状态的 Bundle
。当 SavedStateHandle
准备好保存其状态时,它会调用 saveState()
从 SavedStateProvider
中检索 Bundle
,并为关联的键保存该 Bundle
。
考虑一个应用示例,该应用通过 ACTION_IMAGE_CAPTURE
intent 从相机应用请求图像,并传入一个临时文件,用于相机应存储图像的位置。TempFileViewModel
封装了创建该临时文件的逻辑。
Kotlin
class TempFileViewModel : ViewModel() { private var tempFile: File? = null fun createOrGetTempFile(): File { return tempFile ?: File.createTempFile("temp", null).also { tempFile = it } } }
Java
class TempFileViewModel extends ViewModel { private File tempFile = null; public TempFileViewModel() { } @NonNull public File createOrGetTempFile() { if (tempFile == null) { tempFile = File.createTempFile("temp", null); } return tempFile; } }
为确保临时文件在 Activity 进程被终止并稍后恢复后不会丢失,TempFileViewModel
可以使用 SavedStateHandle
来持久化其数据。为了让 TempFileViewModel
保存其数据,请实现 SavedStateProvider
并将其设置为 ViewModel
的 SavedStateHandle
上的提供程序。
Kotlin
private fun File.saveTempFile() = bundleOf("path", absolutePath) class TempFileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() { private var tempFile: File? = null init { savedStateHandle.setSavedStateProvider("temp_file") { // saveState() if (tempFile != null) { tempFile.saveTempFile() } else { Bundle() } } } fun createOrGetTempFile(): File { return tempFile ?: File.createTempFile("temp", null).also { tempFile = it } } }
Java
class TempFileViewModel extends ViewModel { private File tempFile = null; public TempFileViewModel(SavedStateHandle savedStateHandle) { savedStateHandle.setSavedStateProvider("temp_file", new TempFileSavedStateProvider()); } @NonNull public File createOrGetTempFile() { if (tempFile == null) { tempFile = File.createTempFile("temp", null); } return tempFile; } private class TempFileSavedStateProvider implements SavedStateRegistry.SavedStateProvider { @NonNull @Override public Bundle saveState() { Bundle bundle = new Bundle(); if (tempFile != null) { bundle.putString("path", tempFile.getAbsolutePath()); } return bundle; } } }
当用户返回时,要恢复 File
数据,请从 SavedStateHandle
中检索 temp_file
Bundle
。这是由 saveTempFile()
提供的相同 Bundle
,其中包含绝对路径。然后,可以使用绝对路径实例化新的 File
。
Kotlin
private fun File.saveTempFile() = bundleOf("path", absolutePath) private fun Bundle.restoreTempFile() = if (containsKey("path")) { File(getString("path")) } else { null } class TempFileViewModel(savedStateHandle: SavedStateHandle) : ViewModel() { private var tempFile: File? = null init { val tempFileBundle = savedStateHandle.get<Bundle>("temp_file") if (tempFileBundle != null) { tempFile = tempFileBundle.restoreTempFile() } savedStateHandle.setSavedStateProvider("temp_file") { // saveState() if (tempFile != null) { tempFile.saveTempFile() } else { Bundle() } } } fun createOrGetTempFile(): File { return tempFile ?: File.createTempFile("temp", null).also { tempFile = it } } }
Java
class TempFileViewModel extends ViewModel { private File tempFile = null; public TempFileViewModel(SavedStateHandle savedStateHandle) { Bundle tempFileBundle = savedStateHandle.get("temp_file"); if (tempFileBundle != null) { tempFile = TempFileSavedStateProvider.restoreTempFile(tempFileBundle); } savedStateHandle.setSavedStateProvider("temp_file", new TempFileSavedStateProvider()); } @NonNull public File createOrGetTempFile() { if (tempFile == null) { tempFile = File.createTempFile("temp", null); } return tempFile; } private class TempFileSavedStateProvider implements SavedStateRegistry.SavedStateProvider { @NonNull @Override public Bundle saveState() { Bundle bundle = new Bundle(); if (tempFile != null) { bundle.putString("path", tempFile.getAbsolutePath()); } return bundle; } @Nullable private static File restoreTempFile(Bundle bundle) { if (bundle.containsKey("path") { return File(bundle.getString("path")); } return null; } } }
测试中的 SavedStateHandle
要测试以 SavedStateHandle
作为依赖项的 ViewModel
,请创建一个新的 SavedStateHandle
实例,其中包含所需的测试值,并将其传递给您正在测试的 ViewModel
实例。
Kotlin
class MyViewModelTest { private lateinit var viewModel: MyViewModel @Before fun setup() { val savedState = SavedStateHandle(mapOf("someIdArg" to testId)) viewModel = MyViewModel(savedState = savedState) } }
更多资源
如需了解有关 ViewModel
的保存状态模块的更多信息,请参阅以下资源。
Codelab
为您推荐
- 注意:当 JavaScript 关闭时,会显示链接文本
- 保存 UI 状态
- 使用可观察数据对象
- 创建带依赖项的 ViewModel