ViewModel 的已儲存狀態模組 Android Jetpack 的一部分。

如「儲存 UI 狀態」一文所述，ViewModel 物件可以處理設定變更，因此您不必擔心旋轉或其他情況下的狀態。但如果您需要處理系統啟動的程序 建議使用 SavedStateHandle API 做為備份。

UI 狀態通常是在 ViewModel 物件中儲存或參照，而不是 因此，使用 onSaveInstanceState() 或 rememberSaveable 時，需要一些 已儲存狀態模組的樣板 自動化處理功能

使用這個模組時，ViewModel 物件會透過其建構函式接收 SavedStateHandle 物件。這個物件是鍵/值對應，可讓你寫入及擷取儲存狀態的物件。這些值會在系統終止程序後保留，並且仍可透過相同的物件存取。

已儲存狀態會與工作堆疊建立關聯。如果工作堆疊消失，表示已儲存 狀態也會消失如果強制停止應用程式，移除應用程式的 或重新啟動裝置。在這種情況下 堆疊消失，而且無法還原處於儲存狀態的資訊。於 關閉使用者啟動的 UI 狀態 無法還原已儲存的狀態於 系統啟動的 情境為何？

重點： 一般來說，以已儲存執行個體狀態儲存的資料會處於暫時狀態 取決於使用者輸入或瀏覽方式例如捲動畫面 清單位置、使用者想查看詳細資料的項目 ID，以及 持續選取使用者偏好設定，或在文字欄位中輸入內容。

重要事項： 要使用的 API 取決於狀態儲存位置和 這就需要適用於 商業邏輯， ViewModel 並透過 SavedStateHandle 儲存。適用於 UI 邏輯，請使用 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敬上 例如，您可以擴充SavedStateHandle AbstractSavedStateViewModelFactory。

注意： 使用舊版的片段程式庫時，請遵循 瞭解如何在 SDK 中宣告依附元件 生命週期版本資訊 新增在 lifecycle-viewmodel-savedstate 上的依附元件，並使用 SavedStateViewModelFactory 做為工廠。

使用 SavedStateHandle

SavedStateHandle 類別是鍵/值對應，可讓你透過 set() 和 get() 方法，將資料寫入已儲存狀態並從中擷取資料。

使用 SavedStateHandle 時，查詢值會在整個程序終止期間保留，確保使用者在重新建立前後都可看到同一組經過篩選的資料，完全不需要任何活動或片段來手動儲存、還原，然後將該值傳回 ViewModel。

注意： 只有在發生這種情形時，SavedStateHandle 才會儲存寫入的資料， 「Activity」已停止。除非 Activity 收到 onStart 再加上 onStop，否則系統不會儲存 Activity 停止狀態，同時寫入 SavedStateHandle。

透過鍵/值對應進行互動時，SavedStateHandle 還提供其他方法：

• contains(String key)： 檢查特定鍵是否有值。
• remove(String key)： 移除指定鍵的值。
• keys() - 傳回 SavedStateHandle 中的所有鍵。

此外，您也可以使用SavedStateHandle 可觀測的資料容器。支援的類型清單如下：

• LiveData。
• StateFlow。
• Compose 的 State API。

，瞭解如何調查及移除這項存取權。

警告： 這些可觀測的資料容器整合後， 以顯示 UI 中保留的狀態 儲存的例項狀態。 不過，這些整合項目也會以相同的方式儲存和還原 做為基本的 get() 和 set() 方法。SavedStateHandle 是 在onSaveInstanceState時儲存的 會在連線的活動或片段上呼叫。也就是說，雖然您可以 繼續更新 SavedStateHandle 的可觀測資料容器，在 應用程式在背景執行時，所有狀態更新都可能會遺失 應用程式程序在再次進入前景前就終止。

LiveData

從 SavedStateHandle 擷取已包裝在 LiveData 可藉由 getLiveData()。 更新鍵值時，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 支援功能

從 SavedStateHandle 擷取已包裝在 StateFlow 可藉由 getStateFlow()。 更新鍵值時，StateFlow 會接收新的值。大多數 且您可以根據使用者互動 (例如輸入 查詢以篩選資料清單。接下來，您就可以轉換這個更新的值。 使用其他資料流運算子。

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，和適用於活動或片段的其他 savedInstanceState 一起。

直接支援的類型

根據預設，針對與 Bundle 相同的資料類型，你可以在 SavedStateHandle 呼叫 set() 和 get()，如下所示：

類型/類別支援	陣列支援
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 意圖要求相機應用程式提供圖片，並傳入暫存檔案讓相機儲存圖片。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;
    }
}

為避免暫存檔案在活動程序終止時遺失並方便在稍後還原，TempFileViewModel 可以使用 SavedStateHandle 保留其資料。如要允許「TempFileViewModel」儲存資料，請實作 SavedStateProvider，並在以下位置的 SavedStateHandle 設為提供者： ViewModel：

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 資料，請擷取 temp_file 「SavedStateHandle」設為 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 的「已儲存狀態」模組，請參閱 資源。

程式碼研究室

• Android 生命週期感知元件程式碼研究室