Savedstate

Savedstate

Guide de l'utilisateur  Atelier de programmation

Documentation de référence de l'API
androidx.savedstate

Écrivez des composants enfichables qui enregistrent l'état de l'interface utilisateur à la fin d'un processus, puis restaurez-les au redémarrage du processus.

Dernière mise à jour	Version stable	Version finale	Version bêta	Version alpha
11 décembre 2024	1.2.1	-	-	1.3.0-alpha06

Déclarer des dépendances

Pour ajouter une dépendance sur SavedState, vous devez ajouter le dépôt Maven de Google à votre projet. Pour en savoir plus, consultez la section Dépôt Maven de Google.

Ajoutez les dépendances correspondant aux artefacts dont vous avez besoin dans le fichier build.gradle de votre application ou de votre module :

Groovy

dependencies {
    // Java language implementation
    implementation "androidx.savedstate:savedstate:1.2.1"

    // Kotlin
    implementation "androidx.savedstate:savedstate-ktx:1.2.1"
}

Kotlin

dependencies {
    // Java language implementation
    implementation("androidx.savedstate:savedstate:1.2.1")

    // Kotlin
    implementation("androidx.savedstate:savedstate-ktx:1.2.1")
}

Pour en savoir plus sur les dépendances, consultez Ajouter des dépendances de compilation.

Commentaires

Vos commentaires nous aident à améliorer Jetpack. N'hésitez pas à nous contacter si vous découvrez de nouveaux problèmes ou si vous avez des idées pour améliorer cette bibliothèque. Veuillez consulter les problèmes existants de cette bibliothèque avant d'en signaler un nouveau. Vous pouvez ajouter votre vote à un problème existant en cliquant sur le bouton en forme d'étoile.

Signaler un nouveau problème

Pour en savoir plus, consultez les documents sur l'outil Issue Tracker.

Version 1.3

Version 1.3.0-alpha06

11 décembre 2024

Publication d'androidx.savedstate:savedstate-*:1.3.0-alpha06. La version 1.3.0-alpha06 contient ces commits.

Nouvelles fonctionnalités

• Le KMP SavedState est désormais compatible avec IBinder, Size, SizeF, Array<Parcelable>, SparseArray<Parcelable> et Serializable (Android). (I1ba94, b/334076622)
• Ajoutez des instances KSerializer pouvant être utilisées pour encoder/décoder les types Java et Android compatibles avec Bundle en marquant le champ approprié de votre classe avec @Serializable(with = ParcelableSerializer::class). (I8c10f, I28caf, b/376026712)
• Les instances SavedStateRegistryOwner récupérées via findViewTreeSavedStateRegistryOwner peuvent désormais être résolues via des parents disjoints d'une vue, comme un ViewOverlay. Pour en savoir plus sur les parents de vue disjoints, consultez les notes de version du noyau ou la documentation de ViewTree.setViewTreeDisjointParent. (Iccb33)

Modifications apportées à l'API

• Amélioration de la cohérence des noms et de l'organisation des packages avec SavedStateRegistryOwnerDelegate. (I8c135, b/376026744)

Version 1.3.0-alpha05

13 novembre 2024

Publication d'androidx.savedstate:savedstate-*:1.3.0-alpha05. La version 1.3.0-alpha05 contient ces commits.

Compatibilité avec la sérialisation KotlinX

• SavedState est désormais compatible avec la sérialisation KotlinX. Vous pouvez convertir une classe annotée avec @Serializable en SavedState à l'aide des méthodes encodeToSavedState et decodeFromSavedState. Le SavedState renvoyé est un Bundle standard sur Android et peut être utilisé par n'importe quelle API qui accepte un Bundle. (I6f59f, b/374102924)

  @Serializable
  data class Person(val firstName: String, val lastName: String)
  
  fun main() {
      val person = Person("John", "Doe")
      val encoded: SavedState = encodeToSavedState(person)
      val decoded: Person = decodeFromSavedState(encoded)
  }
  

• Nous avons également inclus saved, un délégué de propriété paresseux, pour faciliter le stockage des classes @Serializable dans un SavedStateRegistryOwner (par exemple, ComponentActivity, Fragment, etc.) et que ces classes soient automatiquement restaurées lors de la mort et de la recréation du processus. Notez que le délégué saved est paresseux et n'appelle pas le lambda init ni n'enregistre quoi que ce soit dans SavedStateRegistry tant qu'il n'y a pas accès. (I66739, b/376027806)

  @Serializable
  data class Person(val firstName: String, val lastName: String)
  
  class MyActivity : ComponentActivity() {
      var person by saved { Person("John", "Doe") }
  
      override fun onCreate(savedInstanceState: Bundle?) {
          super.onCreate(savedInstanceState)
          this.person = Person("Jane", "Doe")
      }
  }
  

• Un délégué de propriété saved similaire pour SavedStateHandle a été ajouté dans Lifecycle 2.9.0-alpha07.

Modifications apportées à l'API

• Ajout de toMap à SavedState, ce qui permet de convertir n'importe quel SavedState en Map standard (copie superficielle). (I487b9, b/334076622)
• Le KMP SavedState est désormais compatible avec les tableaux. (Ic0552, b/334076622)

Version 1.3.0-alpha04

30 octobre 2024

Publication d'androidx.savedstate:savedstate-*:1.3.0-alpha04. La version 1.3.0-alpha04 contient ces commits.

Modifications apportées à l'API

• SavedState KMP est désormais compatible avec Char. (I9ac2f, b/334076622)
• Ajout de putNull et isNull à SavedState KMP. (Iea71d, b/334076622)
• Ajout de paramètres de fabrique savedState supplémentaires compatibles avec un Map<String, Any> initial (I9b37d, b/334076622)
• SavedState KMP est désormais compatible avec la comparaison contentDeepEquals. (Ia515c, b/334076622)
• Le KMP SavedState est désormais compatible avec Long. (I4c180, b/334076622)

Version 1.3.0-alpha03

16 octobre 2024

Publication d'androidx.savedstate:savedstate-*:1.3.0-alpha03 sans modification notable. La version 1.3.0-alpha03 contient ces commits.

Version 1.3.0-alpha02

2 octobre 2024

Publication d'androidx.savedstate:savedstate-*:1.3.0-alpha02. La version 1.3.0-alpha02 contient ces commits.

Multiplateforme Kotlin

• Le module SavedState est désormais compatible avec KMP. Les plates-formes compatibles incluent désormais les environnements de bureau Android, iOS, Linux, Mac et JVM. (I26305, b/334076622)

Nouvelles fonctionnalités

• Introduction du type opaque SavedState en tant qu'abstraction pour fournir un moyen cohérent d'enregistrer et de restaurer l'état de l'application dans KMP. Il inclut un SavedStateReader et un SavedStateWriter pour modifier l'état à enregistrer. Sur Android, SavedState est un alias de type pour Bundle, ce qui garantit la compatibilité binaire et facilite la migration des API existantes vers un ensemble de sources commun. Sur d'autres plates-formes, SavedState est une instance Map<String, Any>. (I18575, b/334076622)

  // Create a new SavedState object using the savedState DSL:
  val savedState = savedState {
    putInt("currentPage", 1)
    putString("filter", "favorites")
  }

  // Read from a SavedState object
  val currentPage = savedState.read { getInt("currentPage") }

  // Edit an existing SavedState object
  savedState.write {
    remove("currentPage")
  }

Modifications apportées à l'API

• SavedStateRegistry et SavedStateRegistryController sont désormais compatibles avec KMP. (Id7bb8, b/334076622)
• SavedState, SavedStateWriter et SavedStateReader sont désormais compatibles avec KMP. (I26305, b/334076622)

Version 1.3.0-alpha01

7 août 2024

Publication d'androidx.savedstate:savedstate:1.3.0-alpha01 et d'androidx.savedstate:savedstate-ktx:1.3.0-alpha01. La version 1.3.0-alpha01 contient ces commits.

Modifications apportées à l'API

• Les extensions Kotlin savedstate-ktx ont été déplacées vers le module savedstate de base. (I1cc18, b/274803094)

Note

• Mise à jour de compileSdk vers 35 (5dc41be)

Version 1.2.1

Version 1.2.1

22 mars 2023

Publication d'androidx.savedstate:savedstate:1.2.1 et d'androidx.savedstate:savedstate-ktx:1.2.1. Liste des commits de la version 1.2.1

Mises à jour des dépendances

• SavedState dépend désormais de Lifecycle 2.6.1. (c1f621)

Version 1.2.0

Version 1.2.0

29 juin 2022

Publication d'androidx.savedstate:savedstate:1.2.0 et androidx.savedstate:savedstate-ktx:1.2.0. Liste des commits de la version 1.2.0

Changements importants depuis la version 1.1.0

• SavedStateRegistryController autorise désormais l'association anticipée de SavedStateRegistry via performAttach().
• Vous pouvez maintenant récupérer un SavedStateProvider enregistré précédemment à partir d'un SavedStateRegistry via getSavedStateProvider().
• La bibliothèque SavedState a été réécrite en Kotlin.
  • Pour SavedStateRegistryOwner, il s'agit d'une modification incompatible avec la source pour les classes écrites en Kotlin. Vous devez maintenant remplacer la propriété savedStateRegistry au lieu d'implémenter la fonction getSavedStateRegistry() précédente.
  • Pour ViewTreeSavedStateRegistryOwner, il s'agit d'une modification incompatible avec la source pour les classes écrites en Kotlin. Vous devez désormais importer et utiliser directement les méthodes d'extension Kotlin sur View de androidx.savedstate.setViewTreeSavedStateRegistryOwner et androidx.savedstate.findViewTreeSavedStateRegistryOwner pour définir et rechercher un propriétaire défini précédemment. Cette action remplace l'API savedstate-ktx de findViewTreeSavedStateRegistryOwner.

Nouveaux comportements

• SavedStateRegistry n'enregistre plus un groupe vide s'il n'y a pas d'état à enregistrer.

Version 1.2.0-rc01

11 mai 2022

Publication d'androidx.savedstate:savedstate:1.2.0-rc01 et androidx.savedstate:savedstate-ktx:1.2.0-rc01. Liste des commits de la version 1.2.0-rc01

Modifications de la documentation

• Les Kdocs de SavedStateRegistryOwner ont été mis à jour pour clarifier les responsabilités et le contrat du propriétaire concernant l'implémentation de l'interface ou l'appel des méthodes sur SavedStateRegistryController. (Iefc95, b/228887344)

Version 1.2.0-beta01

20 avril 2022

Publication d'androidx.savedstate:savedstate:1.2.0-beta01 et androidx.savedstate:savedstate-ktx:1.2.0-beta01. Liste des commits de la version 1.2.0-beta01

Modifications apportées à l'API

• Les classes SavedStateRegistry et ViewTreeSavedStateRegistryOwner ont été réécrites en Kotlin. Pour ViewTreeSavedStateRegistryOwner, il s'agit d'une modification incompatible avec la source pour les classes écrites en Kotlin. Vous devez désormais importer et utiliser directement les méthodes d'extension Kotlin sur View d'androidx.savedstate.setViewTreeSavedStateRegistryOwner et androidx.savedstate.findViewTreeSavedStateRegistryOwner pour définir et rechercher un propriétaire défini précédemment. Cette action remplace l'API savedstate-ktx de findViewTreeSavedStateRegistryOwner. Cette fonctionnalité est compatible avec le binaire et reste compatible avec la source pour les implémentations écrites en langage de programmation Java. (b/220191285)

Version 1.2.0-alpha02

6 avril 2022

Publication d'androidx.savedstate:savedstate:1.2.0-alpha02 et androidx.savedstate:savedstate-ktx:1.2.0-alpha02. Liste des commits de la version 1.2.0-alpha02.

Nouvelles fonctionnalités

• Vous pouvez maintenant récupérer un SavedStateProvider enregistré précédemment à partir d'un SavedStateRegistry via getSavedStateProvider(). (I7ea47, b/215406268)

Modifications apportées à l'API

• Les classes SavedStateRegistryOwner, SavedStateRegistryController et Recreator ont été réécrites en Kotlin. Pour SavedStateRegistryOwner, il s'agit d'une modification incompatible avec la source pour les classes écrites en Kotlin. Vous devez maintenant remplacer la propriété savedStateRegistry au lieu d'implémenter la fonction getSavedStateRegistry() précédente. Cette fonctionnalité est compatible avec le binaire et la source pour les implémentations écrites en langage de programmation Java. (b/220191285)

Version 1.2.0-alpha01

26 janvier 2022

Publication d'androidx.savedstate:savedstate:1.2.0-alpha01 et androidx.savedstate:savedstate-ktx:1.2.0-alpha01. Liste des commits de la version 1.2.0-alpha01

Nouvelles fonctionnalités

• SavedStateRegistryController autorise désormais l'association anticipée de SavedStateRegistry via performAttach(). (Ice4bf)

Nouveaux comportements

• SavedStateRegistry n'enregistre plus un groupe vide s'il n'y a pas d'état à enregistrer. (aosp/1896865, b/203457956)

Version 1.1.0

Version 1.1.0

10 février 2021

Publication d'androidx.savedstate:savedstate:1.1.0 et androidx.savedstate:savedstate-ktx:1.1.0. Liste des commits de la version 1.1.0

Principales modifications depuis la version 1.0.0

• API ViewTreeSavedStateRegistryOwner : Une nouvelle API ViewTreeSavedStateRegistryOwner.get(View) vous permet de récupérer le conteneur SavedStateRegistry en fonction d'une instance View. Vous devez passer à Activity 1.2.0, Fragment 1.3.0 et AppCompat 1.3.0-alpha01 ou version ultérieure pour renseigner correctement ce champ.
• Artefact savedstate-ktx : le nouvel artefact savedstate-ktx a été ajouté avec une extension Kotlin findViewTreeSavedStateRegistryOwner() pour travailler avec ViewTreeSavedStateRegistryOwner.

Version 1.1.0-rc01

16 décembre 2020

Publication d'androidx.savedstate:savedstate:1.1.0-rc01 et d'androidx.savedstate:savedstate-ktx:1.1.0-rc01 sans modification par rapport à la version 1.1.0-beta01. Liste des commits de la version 1.1.0-rc01

Version 1.1.0-beta01

1er octobre 2020

Publication d'androidx.savedstate:savedstate:1.1.0-beta01 et d'androidx.savedstate:savedstate-ktx:1.1.0-beta01 sans modification par rapport à la version 1.1.0-alpha01. Liste des commits de la version 1.1.0-beta01

Version 1.1.0-alpha01

20 mai 2020

Publication d'androidx.savedstate:savedstate:1.1.0-alpha01 et androidx.savedstate:savedstate-ktx:1.1.0-alpha01. Liste des commits de la version 1.1.0-alpha01

Nouvelles fonctionnalités

• Une nouvelle API ViewTreeSavedStateRegistryOwner.get(View) vous permet de récupérer le conteneur SavedStateRegistry en fonction d'une instance View. Vous devez passer à Activity 1.2.0-alpha05, Fragment 1.3.0-alpha05 et AppCompat 1.3.0-alpha01 pour renseigner ces éléments correctement. (aosp/1298679)
• Le nouvel artefact savedstate-ktx a été ajouté avec une extension Kotlin findViewTreeSavedStateRegistryOwner() pour travailler avec ViewTreeSavedStateRegistryOwner. (aosp/1299434)

Version 1.0.0

Version 1.0.0

5 septembre 2019

Publication d'androidx.savedstate:savedstate:1.0.0. Les commits inclus dans cette version sont disponibles sur cette page.

Principales fonctionnalités de la version 1.0.0 de SavedState

androidx.savedstate est passé à une version stable. Il s'agit d'un ensemble d'API permettant aux développeurs d'insérer des composants dans le processus restore/saveInstanceState. Le principal point d'entrée de l'API est SavedStateRegistry, qui permet de récupérer les états précédemment enregistrés à l'aide de consumeRestoredStateForKey et d'enregistrer un rappel à registerSavedStateProvider pour fournir un état enregistré une fois que le système l'a demandé.

Version 1.0.0-rc01

2 juillet 2019

Publication d'androidx.savedstate:savedstate:1.0.0-rc01. Les commits inclus dans cette version sont disponibles sur cette page.

Correction de bugs

• Correction d'une règle ProGuard incorrecte (b/132655499)

Version 1.0.0-beta01

7 mai 2019

Publication d'androidx.savedstate:savedstate:1.0.0-beta01. Les commits inclus dans cette version sont disponibles sur cette page.

Version 1.0.0-alpha02

13 mars 2019

Publication d'androidx.savedstate:savedstate:1.0.0-alpha02. androidx.savedstate:savedstate combine les artefacts androidx.savedstate:savedstate-bundle et androidx.savedstate:savedstate-common en un seul, car il a été décidé de simplifier l'infrastructure savedstate et de supprimer les éléments génériques de SavedStateRegistry. Il n'est donc pas nécessaire de créer des modules distincts.

La liste complète des commits inclus dans cette version est disponible sur cette page.

Nouvelles fonctionnalités

• SavedStateRegistry.runOnNextRecreaction(Class<? extends AutoRecreated> clazz ) a été ajouté. La classe donnée sera instanciée et la méthode AutoRecreated.onRecreated sera exécutée lorsque le composant propriétaire aura redémarré.

Modifications apportées à l'API

• Génériques supprimés de SavedStateRegistry<T>
• Suppression d'AbstractSavedStateRegistry et de BundlableSavedStateRegistry. Utilisez simplement SavedStateRegistry à la place.
• BundleSavedStateRegistryOwner a été renommé SavedStateRegistryOwner.

Version 1.0.0-alpha01

17 décembre 2018

Il s'agit de la première version de SavedState.

Nouvelles fonctionnalités

androidx.savedstate est un nouvel ensemble d'API alpha qui permet aux développeurs d'insérer des composants dans le processus restore/saveInstanceState. Le principal point d'entrée de l'API est SavedStateRegistry<T>, qui permet de récupérer l'état précédemment enregistré via consumeRestoredStateForKey et d'enregistrer un rappel à registerSavedStateProvider pour fournir un savedstate une fois que le système l'a demandé.