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 執行個體時，您可以擴充 AbstractSavedStateViewModelFactory 來啟用 SavedStateHandle。

注意： 使用較舊的 Fragment 程式庫版本時，請按照生命週期版本資訊中的操作說明，在 lifecycle-viewmodel-savedstate 新增依附元件，並使用 SavedStateViewModelFactory 做為工廠。

使用 SavedStateHandle

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

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

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

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

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

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

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

警告： 這些可觀測的資料容器整合後，就能以更便利的方式使用保留的儲存的執行個體狀態顯示 UI。不過，此類整合也會利用與基本 get() 和 set() 方法相同的機制儲存及還原。在連結的活動或片段上呼叫 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 會接收新的值。在多數情況下，您可能會因為使用者互動 (例如輸入查詢以篩選資料清單) 而設定值。接著，您可以使用其他資料流運算子轉換此更新的值。

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 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，和適用於活動或片段的其他 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，並在 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 的「已儲存狀態」模組，請參閱下列資源。

程式碼研究室

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