ViewModel 的已保存状态模块 Android Jetpack 的一部分。

保存界面状态这篇文章提到过，ViewModel 对象可以处理配置更改，因此您无需担心旋转时或其他情况下的状态。但是，如果需要处理系统发起的进程终止，则可以使用 SavedStateHandle API 作为备用方式。

界面状态通常会在 ViewModel 对象（而非 activity）中存储或引用，因此，使用 onSaveInstanceState() 或 rememberSaveable 时需要已保存的状态模块可以为您处理的某个样板文件。

使用此模块时，ViewModel 对象会通过其构造函数接收 SavedStateHandle 对象。此对象是一个键值对映射，用于向已保存状态写入对象以及从其中检索对象。这些值会在进程被系统终止后继续保留，并通过同一对象保持可用状态。

保存的状态与您的任务堆栈相关联。如果任务堆栈消失，保存的状态也会消失。强制停止应用、从“最近用过”菜单中移除应用或重新启动设备时，可能会发生这种情况。在这种情况下，任务堆栈会消失，并且您无法恢复保存的状态中的信息。在用户发起的界面状态解除情景中，不会恢复保存的状态。在系统发起的界面状态解除情景中，则会恢复。

要点：通常，保存的实例状态中存储的数据是临时状态，根据用户的输入或导航而定。这方面的例子包括：列表的滚动位置、用户想详细了解的项目的 ID、正在进行的用户偏好设置选择或文本字段的输入。

重要提示：要使用的 API 取决于状态存储的位置及其所需的逻辑。对于业务逻辑中使用的状态，请将其存储在 ViewModel 中，并使用 SavedStateHandle 保存。对于界面逻辑中使用的状态，请使用 View 系统中的 onSaveInstanceState API 或 Compose 中的 rememberSaveable。

注意：状态必须简单轻省。对于复杂或大型数据，应使用本地持久性存储。

设置

从 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。

注意：在使用早期版本的 Fragment 库时，您可以按照 Lifecycle 版本说明中关于声明依赖项的说明，添加 lifecycle-viewmodel-savedstate 的依赖项并使用 SavedStateViewModelFactory 作为工厂。

使用 SavedStateHandle

SavedStateHandle 类是一个键值对映射，用于通过 set() 和 get() 方法向已保存的状态写入数据以及从中检索数据。

通过使用 SavedStateHandle，查询值会在进程终止后保留下来，从而确保用户在重新创建前后看到同一组过滤后的数据，而无需 activity 或 fragment 手动保存、恢复该值并将其重新转给 ViewModel。

注意：仅当 Activity 停止时，SavedStateHandle 才会保存写入其中的数据。在 Activity 停止时对 SavedStateHandle 的写入，只有在 Activity 收到 onStop 后，又再次收到 onStart 时，才会被保存。

此外，SavedStateHandle 还包含其他您与键值对映射互动时可能会用到的方法：

• contains(String key) - 检查是否存在给定键的值。
• remove(String key) - 移除给定键的值。
• keys() - 返回 SavedStateHandle 中包含的所有键。

此外，您还可以使用可观察数据存储器从 SavedStateHandle 检索值。支持的类型包括：

• LiveData。
• StateFlow。
• Compose 的状态 API。

警告：在与可观察数据存储器进行此类集成后，更方便显示具有由保存的实例状态保留的状态的界面。但是，这些集成还会使用与基本 get() 和 set() 方法相同的机制保存和恢复。对关联的 activity 或 fragment 调用 onSaveInstanceState 时，系统会保存 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

注意：我们在 Lifecycle 版本 2.5.0 中添加了对 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 版本 2.5.0 中添加了对实验性 Compose 状态的支持

lifecycle-viewmodel-compose 工件提供了 saveable 支持 SavedStateHandle 与 Compose 之间互操作性的 API Saver，以便您将任何 State 设为 可通过rememberSaveable保存 具有自定义 Saver 的过滤器也可以使用 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 调用 set() 和 get()，以处理与 Bundle 相同的数据类型，如下所示。

类型/类支持	数组支持
double	double[]
int	int[]
long	long[]
String	String[]
byte	byte[]
char	char[]
CharSequence	CharSequence[]
float	float[]
Parcelable	Parcelable[]
Serializable	Serializable[]
short	short[]
SparseArray
Binder
Bundle
ArrayList
Size (only in API 21+)
SizeF (only in API 21+)

如果该类没有扩展上述列表中的任何一项，则应考虑通过添加 @Parcelize Kotlin 注解或直接实现 Parcelable 来使该类变为 Parcelable 类。

保存非 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

• Android 生命周期感知型组件 Codelab