Savedstate

Savedstate

دليل المستخدم  Codelab

مرجع واجهة برمجة التطبيقات
androidx.savedstate

اكتب مكوّنات قابلة للتوصيل تحفظ حالة واجهة المستخدم عند إيقاف عملية ما، وتستعيدها عند إعادة تشغيل العملية.

آخر تعديل	الإصدار الثابت	إصدار محتمل	الإصدار التجريبي	الإصدار التجريبي الأول
13 تشرين الثاني (نوفمبر) 2024	1.2.1	-	-	1.3.0-alpha05

الإعلان عن التبعيات

لإضافة عنصر تابع لـ SavedState، عليك إضافة مستودع Google Maven إلى مشروعك. اطّلِع على مستودع Maven من Google لمزيد من المعلومات.

أضِف التبعيات للعناصر التي تحتاج إليها في ملف build.gradle ل تطبيقك أو وحدتك:

رائع

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")
}

لمزيد من المعلومات عن العناصر الاعتمادية، اطّلِع على مقالة إضافة عناصر الاعتماد الخاصة بالإصدار.

ملاحظات

تساعدنا ملاحظاتك في تحسين Jetpack. يُرجى إعلامنا إذا واجهت مشاكل جديدة أو كان لديك أفكار لتحسين هذه المكتبة. يُرجى الاطّلاع على المشاكل الحالية في هذه المكتبة قبل إنشاء مكتبة جديدة. يمكنك إضافة صوتك إلى مشكلة حالية عن طريق النقر على زر النجمة.

إنشاء مشكلة جديدة

اطّلِع على مستندات أداة تتبُّع المشاكل لمزيد من المعلومات.

الإصدار 1.3

الإصدار 1.3.0-alpha05

13 تشرين الثاني (نوفمبر) 2024

تم إصدار androidx.savedstate:savedstate-*:1.3.0-alpha05. يحتوي الإصدار 1.3.0-alpha05 على عمليات الربط هذه.

إتاحة ميزة التسلسل في KotlinX

• يتضمّن SavedState الآن ميزة KotlinX Serialization. يمكنك تحويل فئة تمّت إضافة تعليقات توضيحية لها باستخدام @Serializable إلى SavedState باستخدام الطريقتَين encodeToSavedState وdecodeFromSavedState. الرمز SavedState المعروض هو رمز Bundle عادي على Android ويمكن لأي واجهة برمجة تطبيقات تقبل 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)
  }
  

• لقد أدرجنا أيضًا saved، وهو مفوّض سمة غير نشط، لتسهيل تخزين فئات @Serializable في SavedStateRegistryOwner (مثل ComponentActivity وFragment وما إلى ذلك) واستعادة هذه الفئات تلقائيًا عند إنهاء العملية وإعادة إنشائها. يُرجى العلم أنّ الوكيل saved غير نشِط ولن يستدعي دالة init lambda أو يحفظ أي شيء في SavedStateRegistry إلى أن يتم الوصول إليه. (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")
      }
  }
  

• هناك عنصر saved مفوَّض مشابه لسمة SavedStateHandle تمت إضافته في رحلة المستخدِم 2.9.0-alpha07.

تغييرات واجهة برمجة التطبيقات

• أضِف toMap إلى SavedState، ما يسمح بتحويل أي SavedState إلى Map عادي (نسخة سطحية). (I487b9، b/334076622)
• SavedState يتيح KMP الآن استخدام الصفائف. (Ic0552، b/334076622)

الإصدار 1.3.0-alpha04

30 تشرين الأول (أكتوبر) 2024

تم إصدار androidx.savedstate:savedstate-*:1.3.0-alpha04. يتضمّن الإصدار 1.3.0-alpha04 عمليات الربط هذه.

تغييرات واجهة برمجة التطبيقات

• يتيح الآن تنسيق KMP لحالة الحفظ استخدام Char. (I9ac2f، b/334076622)
• أضِف putNull وisNull إلى SavedState KMP. (Iea71d، b/334076622)
• إضافة مَعلمات savedState إضافية للمصنع تتيح استخدام Map<String, Any> أولي (I9b37d، b/334076622)
• تتيح الآن أداة KMP في SavedState مقارنة contentDeepEquals. (Ia515c، b/334076622)
• يتيح الآن SavedState KMP استخدام Long. (I4c180، b/334076622)

الإصدار 1.3.0-alpha03

16 أكتوبر 2024

تم إصدار الإصدار androidx.savedstate:savedstate-*:1.3.0-alpha03 بدون أي تغييرات ملحوظة. يتضمّن الإصدار 1.3.0-alpha03 عمليات الربط هذه.

الإصدار 1.3.0-alpha02

2 أكتوبر 2024

تم إصدار androidx.savedstate:savedstate-*:1.3.0-alpha02. يتضمّن الإصدار 1.3.0-alpha02 عمليات الربط هذه.

Kotlin Multiplatform

• أصبحت وحدة SavedState متوافقة مع KMP. تشمل الأنظمة الأساسية المتوافقة الآن بيئات سطح المكتب لنظام التشغيل Android وiOS وLinux وMac وJVM. (I26305، b/334076622)

الميزات الجديدة

• تقديم نوع SavedState غير الشفاف كنوع مجرد لتوفير طريقة متّسقة لحفظ حالة التطبيق واستعادتها في KMP يتضمّن SavedStateReader وSavedStateWriter لتعديل الحالة التي سيتم حفظها. على نظام التشغيل Android، SavedState هو اسم بديل لنوع Bundle، ما يضمن توافق البرنامج الثنائي وتسهيل نقل واجهات برمجة التطبيقات الحالية إلى مجموعة مصادر شائعة. على المنصات الأخرى، SavedState هو مثيل 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")
  }

تغييرات واجهة برمجة التطبيقات

• أصبح كل من "SavedStateRegistry" و"SavedStateRegistryController" متوافقَين مع KMP. (Id7bb8، b/334076622)
• أصبحت SavedState وSavedStateWriter وSavedStateReader متوافقة مع KMP. (I26305، b/334076622)

الإصدار 1.3.0-alpha01

7 آب (أغسطس) 2024

تم إصدار androidx.savedstate:savedstate:1.3.0-alpha01 وandroidx.savedstate:savedstate-ktx:1.3.0-alpha01. يتضمّن الإصدار 1.3.0-alpha01 عمليات الربط هذه.

تغييرات واجهة برمجة التطبيقات

• تم نقل إضافات savedstate-ktx kotlin إلى وحدة savedstate الأساسية. (I1cc18، b/274803094)

ملاحظة

• تعديل الإصدار compileSdk إلى 35 (5dc41be)

الإصدار 1.2.1

الإصدار 1.2.1

22 آذار (مارس) 2023

تم إصدار androidx.savedstate:savedstate:1.2.1 وandroidx.savedstate:savedstate-ktx:1.2.1. يحتوي الإصدار 1.2.1 على هذه المراجعات.

تعديلات على التبعيات

• يعتمد SavedState الآن على رحلة المستخدِم 2.6.1. (c1f621)

الإصدار 1.2.0

الإصدار 1.2.0

29 حزيران (يونيو) 2022

تم إصدار androidx.savedstate:savedstate:1.2.0 وandroidx.savedstate:savedstate-ktx:1.2.0. يحتوي الإصدار 1.2.0 على هذه المراجعات.

التغييرات المهمة منذ الإصدار 1.1.0

• يتيح SavedStateRegistryController الآن إرفاق SavedStateRegistry مبكرًا من خلال performAttach().
• يمكنك الآن استرداد SavedStateProvider مسجَّل سابقًا من SavedStateRegistry من خلال getSavedStateProvider().
• تمت إعادة كتابة مكتبة SavedState بلغة Kotlin.
  • بالنسبة إلى SavedStateRegistryOwner، يُعدّ هذا تغييرًا غير متوافق مع المصدر لهذه الفئات المكتوبة بلغة Kotlin، وعليك الآن إلغاء السمة savedStateRegistry بدلاً من تنفيذ الدالة getSavedStateRegistry() السابقة.
  • بالنسبة إلى ViewTreeSavedStateRegistryOwner، يُعدّ هذا تغييرًا غير متوافق مع المصدر لهذه الفئات المكتوبة بلغة Kotlin. عليك الآن استيراد طُرق إضافة Kotlin مباشرةً واستخدامها في View من androidx.savedstate.setViewTreeSavedStateRegistryOwner وandroidx.savedstate.findViewTreeSavedStateRegistryOwner لضبط مالك تم ضبطه سابقًا والعثور عليه. ويحلّ ذلك محل واجهة برمجة التطبيقات savedstate-ktx في findViewTreeSavedStateRegistryOwner.

التغييرات في السلوك

• لم يعُد SavedStateRegistry يحفظ حِزمة فارغة إذا لم تكن هناك حالة لحفظها.

الإصدار 1.2.0-rc01

11 أيار (مايو) 2022

تم إصدار androidx.savedstate:savedstate:1.2.0-rc01 وandroidx.savedstate:savedstate-ktx:1.2.0-rc01. يحتوي الإصدار 1.2.0-rc01 على هذه المراجعات.

تغييرات في المستندات

• تم تعديل SavedStateRegistryOwner Kdocs لتوضيح المسؤوليات والعقد الذي يتحمله المالك بشأن كيفية تنفيذ الواجهة أو الحالات التي يجب فيها استدعاء الطرق في SavedStateRegistryController. (Iefc95، b/228887344)

الإصدار 1.2.0-beta01

20 نيسان (أبريل) 2022

تم إصدار androidx.savedstate:savedstate:1.2.0-beta01 وandroidx.savedstate:savedstate-ktx:1.2.0-beta01. يحتوي الإصدار 1.2.0-beta01 على هذه المراجعات.

تغييرات واجهة برمجة التطبيقات

• تمت إعادة كتابة فئتَي SavedStateRegistry وViewTreeSavedStateRegistryOwner بلغة Kotlin. بالنسبة إلى ViewTreeSavedStateRegistryOwner، يُعدّ هذا تغييرًا غير متوافق مع المصدر لهذه الفئات المكتوبة بلغة Kotlin. عليك الآن استيراد طُرق إضافة Kotlin مباشرةً واستخدامها في View من androidx.savedstate.setViewTreeSavedStateRegistryOwner وandroidx.savedstate.findViewTreeSavedStateRegistryOwner لضبط مالك تم ضبطه سابقًا والعثور عليه. ويحلّ ذلك محل واجهة برمجة التطبيقات savedstate-ktx في findViewTreeSavedStateRegistryOwner. هذه الإصدارات متوافقة مع الثنائيات وتظل متوافقة مع المصدر للتنفيذات المكتوبة بلغة البرمجة Java. (b/220191285)

الإصدار 1.2.0-alpha02

6 نيسان (أبريل) 2022

تم إصدار androidx.savedstate:savedstate:1.2.0-alpha02 وandroidx.savedstate:savedstate-ktx:1.2.0-alpha02. يحتوي الإصدار 1.2.0-alpha02 على هذه المراجعات.

الميزات الجديدة

• يمكنك الآن استرداد SavedStateProvider مسجَّل سابقًا من SavedStateRegistry من خلال getSavedStateProvider(). (I7ea47، b/215406268)

تغييرات واجهة برمجة التطبيقات

• تمت إعادة كتابة فئات SavedStateRegistryOwner وSavedStateRegistryController وRecreator بلغة Kotlin. بالنسبة إلى SavedStateRegistryOwner، يُعدّ هذا تغييرًا غير متوافق مع المصدر لهذه الفئات المكتوبة بلغة Kotlin، وعليك الآن إلغاء السمة savedStateRegistry بدلاً من تنفيذ الدالة getSavedStateRegistry() السابقة. هذه الإصدارات متوافقة مع الثنائيات ومتوافقة مع المصدر للتنفيذات المكتوبة بلغة البرمجة Java. (b/220191285)

الإصدار 1.2.0-alpha01

26 كانون الثاني (يناير) 2022

تم إصدار androidx.savedstate:savedstate:1.2.0-alpha01 وandroidx.savedstate:savedstate-ktx:1.2.0-alpha01. يحتوي الإصدار 1.2.0-alpha01 على هذه المراجعات.

الميزات الجديدة

• يتيح SavedStateRegistryController الآن إرفاق SavedStateRegistry مبكرًا من خلال performAttach(). (Ice4bf)

التغييرات في السلوك

• لم يعُد SavedStateRegistry يحفظ حِزمة فارغة إذا لم تكن هناك حالة لحفظها. (aosp/1896865، b/203457956)

الإصدار 1.1.0

الإصدار 1.1.0

10 شباط (فبراير) 2021

تم إصدار androidx.savedstate:savedstate:1.1.0 وandroidx.savedstate:savedstate-ktx:1.1.0. يحتوي الإصدار 1.1.0 على عمليات الربط هذه.

التغييرات الرئيسية منذ الإصدار 1.0.0

• ViewTreeSavedStateRegistryOwner API: تتيح لك واجهة برمجة تطبيقات ViewTreeSavedStateRegistryOwner.get(View) الجديدة استرداد SavedStateRegistry المضمّنة في مثيل View. يجب الترقية إلى Activity 1.2.0 وFragment 1.3.0 وAppCompat 1.3.0-alpha01 أو إصدار أحدث لملء هذا الحقل بشكل صحيح.
• عنصر savedstate-ktx: تمت إضافة عنصر savedstate-ktx الجديد مع إضافة findViewTreeSavedStateRegistryOwner() Kotlin ليعمل مع ViewTreeSavedStateRegistryOwner.

الإصدار 1.1.0-rc01

16 كانون الأول (ديسمبر) 2020

تم إصدار androidx.savedstate:savedstate:1.1.0-rc01 وandroidx.savedstate:savedstate-ktx:1.1.0-rc01 بدون أي تغييرات منذ 1.1.0-beta01. يحتوي الإصدار 1.1.0-rc01 على هذه المراجعات.

الإصدار 1.1.0-beta01

1 تشرين الأول (أكتوبر) 2020

تم إصدار androidx.savedstate:savedstate:1.1.0-beta01 وandroidx.savedstate:savedstate-ktx:1.1.0-beta01 بدون أي تغييرات منذ 1.1.0-alpha01. يحتوي الإصدار 1.1.0-beta01 على هذه المراجعات.

الإصدار 1.1.0-alpha01

20 أيار (مايو) 2020

تم إصدار androidx.savedstate:savedstate:1.1.0-alpha01 وandroidx.savedstate:savedstate-ktx:1.1.0-alpha01. يحتوي الإصدار 1.1.0-alpha01 على هذه المراجعات.

الميزات الجديدة

• تتيح لك واجهة برمجة تطبيقات ViewTreeSavedStateRegistryOwner.get(View) الجديدة استرداد SavedStateRegistry المضمّنة في مثيل View. يجب الترقية إلى Activity 1.2.0-alpha05 وFragment 1.3.0-alpha05 وAppCompat 1.3.0-alpha01 لملء هذا الحقل بشكل صحيح. (aosp/1298679)
• تمت إضافة العنصر savedstate-ktx الجديد مع إضافة findViewTreeSavedStateRegistryOwner() Kotlin للاستخدام مع ViewTreeSavedStateRegistryOwner. (aosp/1299434)

الإصدار 1.0.0

الإصدار 1.0.0

5 أيلول (سبتمبر) 2019

تم إصدار androidx.savedstate:savedstate:1.0.0. يمكن العثور على عمليات الربط المضمّنة في هذا الإصدار هنا.

الميزات الرئيسية لواجهة برمجة التطبيقات SavedState 1.0.0

تم ترقية androidx.savedstate إلى إصدار ثابت. هذه مجموعة من واجهات برمجة التطبيقات التي تسمح للمطوّرين بتوصيل المكوّنات في عملية restore / saveInstanceState. نقطة الدخول الرئيسية لواجهة برمجة التطبيقات هي SavedStateRegistry، التي توفّر طريقة لاسترداد الحالات المحفوظة سابقًا باستخدام consumeRestoredStateForKey وتسجيل طلب استدعاء إلى registerSavedStateProvider لتقديم حالة محفوظة بعد أن يطلبها النظام.

الإصدار 1.0.0-rc01

2 تموز (يوليو) 2019

تم إصدار androidx.savedstate:savedstate:1.0.0-rc01. يمكن العثور على عمليات الربط المضمّنة في هذا الإصدار هنا.

إصلاح الأخطاء

• تم إصلاح قاعدة Proguard غير الصحيحة (b/132655499)

الإصدار 1.0.0-beta01

7 أيار (مايو) 2019

تم إصدار androidx.savedstate:savedstate:1.0.0-beta01. يمكن العثور على عمليات الربط المضمّنة في هذا الإصدار هنا.

الإصدار 1.0.0-alpha02

13 آذار (مارس) 2019

تم إصدار androidx.savedstate:savedstate:1.0.0-alpha02. يجمع androidx.savedstate:savedstate العنصرَين androidx.savedstate:savedstate-bundle وandroidx.savedstate:savedstate-common في عنصر واحد، لأنّه تمّ اتخاذ قرار بتبسيط بنية savedstate وإزالة العناصر العامة من SavedStateRegistry. وبالتالي، ليست هناك حاجة إلى وحدات منفصلة.

يمكن العثور على القائمة الكاملة للتغييرات المضمّنة في هذا الإصدار هنا.

الميزات الجديدة

• تمت إضافة SavedStateRegistry.runOnNextRecreaction(Class<? extends AutoRecreated> clazz ). سيتم إنشاء مثيل للصف المحدَّد وسيتم تشغيل الطريقة AutoRecreated.onRecreated عند إعادة تشغيل المكوّن المالك.

تغييرات واجهة برمجة التطبيقات

• تمّت إزالة الأدوية العامة من SavedStateRegistry<T>
• تمّت إزالة AbstractSavedStateRegistry وBundlableSavedStateRegistry، استخدِم SavedStateRegistry البسيط بدلاً منهما.
• تمت إعادة تسمية BundleSavedStateRegistryOwner إلى SavedStateRegistryOwner.

الإصدار 1.0.0-alpha01

17 كانون الأول (ديسمبر) 2018

هذا هو الإصدار الأول من SavedState.

الميزات الجديدة

androidx.savedstate هي مجموعة جديدة من واجهات برمجة التطبيقات التجريبية التي تسمح للمطوّرين بتوصيل المكوّنات بعملية restore / saveInstanceState. نقطة الدخول الرئيسية لواجهة برمجة التطبيقات هي SavedStateRegistry<T>، التي توفّر طريقة لاسترداد حالة الحفظ السابقة من خلال consumeRestoredStateForKey وتسجيل طلب استدعاء إلى registerSavedStateProvider لتقديم حالة الحفظ بعد أن يطلبها النظام.