State وJetpack Compose

الحالة في التطبيق هي أي قيمة يمكن أن تتغيّر بمرور الوقت. هذا تعريف شامل جدًا ويشمل كل شيء، بدءًا من قاعدة بيانات Room ووصولاً إلى متغيّر في الفئة.

تعرض جميع تطبيقات Android الحالة للمستخدم. في ما يلي بعض الأمثلة على الحالات في تطبيقات Android:

• شريط معلومات سريع يظهر عندما يتعذّر إنشاء اتصال بالشبكة
• مشاركة مدونة والتعليقات المرتبطة بها
• رسوم متحركة للتأثيرات المتموّجة على الأزرار يتم تشغيلها عندما ينقر المستخدم عليها
• ملصقات يمكن للمستخدم رسمها فوق صورة

يساعدك Jetpack Compose في تحديد مكان تخزين الحالة وكيفية استخدامها في تطبيق Android. ويركز هذا الدليل على الرابط بين الحالة وعناصر التركيب، وعلى واجهات برمجة التطبيقات التي يوفّرها Jetpack Compose للعمل مع الحالة بشكلٍ أكثر سهولة.

الحالة والتركيب

Compose عبارة عن عنصر تعريفي، وبالتالي فإنّ الطريقة الوحيدة لتعديله هي من خلال استدعاء العنصر القابل للتركيب نفسه مع وسيطات جديدة. هذه الوسيطات هي تمثيلات لحالة واجهة المستخدم. في أي وقت يتم فيه تعديل حالة، يتم إجراء إعادة تركيب. ونتيجةً لذلك، لا يتم تعديل عناصر مثل TextField تلقائيًا كما هو الحال في العروض المستندة إلى XML الإلزامية. يجب أن يتم إخبار العنصر القابل للتجميع صراحةً بالحالة الجديدة لكي يتم تعديله وفقًا لذلك.

@Composable
private fun HelloContent() {
    Column(modifier = Modifier.padding(16.dp)) {
        Text(
            text = "Hello!",
            modifier = Modifier.padding(bottom = 8.dp),
            style = MaterialTheme.typography.bodyMedium
        )
        OutlinedTextField(
            value = "",
            onValueChange = { },
            label = { Text("Name") }
        )
    }
}
StateOverviewSnippets.kt

إذا نفّذت هذا الإجراء وحاولت إدخال نص، لن يحدث شيء. ويعود سبب ذلك إلى أنّه لا يتم تعديل TextField تلقائيًا، بل يتم تعديله عند تغيير المَعلمة value. ويرجع ذلك إلى آلية عمل عملية الإنشاء وإعادة الإنشاء في Compose.

للاطّلاع على مزيد من المعلومات عن عملية الإنشاء الأولي وإعادة الإنشاء، يُرجى الاطّلاع على مقالة التفكير في وضع "الإنشاء".

الحالة في العناصر القابلة للتجميع

يمكن للدوالّ القابلة للتجميع استخدام واجهة برمجة التطبيقات remember لتخزين عنصر في الذاكرة. يتم تخزين القيمة التي يتم احتسابها بواسطة remember في التركيب أثناء التركيب الأولي، ويتم عرض القيمة المخزّنة أثناء إعادة التركيب. يمكن استخدام remember لتخزين كلّ من الكائنات القابلة للتغيير وغير القابلة للتغيير.

mutableStateOf تُنشئ مراقبة MutableState<T>، وهو نوع مراقبة مدمج مع وقت تشغيل Compose.

interface MutableState<T> : State<T> {
    override var value: T
}

تؤدي أي تغييرات على value إلى إعادة تركيب أي دوال قابلة للتجميع تقرأ value.

هناك ثلاث طرق لتعريف عنصر MutableState في عنصر قابل للتجميع:

• val mutableState = remember { mutableStateOf(default) }
• var value by remember { mutableStateOf(default) }
• val (value, setValue) = remember { mutableStateOf(default) }

هذه التعريفات متكافئة، ويتم تقديمها كطريقة سهلة لاستخدام بنية الجملة في استخدامات مختلفة لحالة. عليك اختيار الرمز الذي ينتج عن العبارة العبارة السهلة القراءة في العبارة المركبة التي تكتبها.

تتطلّب بنية التفويض by عمليات الاستيراد التالية:

import androidx.compose.runtime.getValue
import androidx.compose.runtime.setValue

يمكنك استخدام القيمة التي تم تذكُّرها كمَعلمة للعناصر القابلة للتجميع الأخرى أو حتى كأحد المنطق في العبارات لتغيير العناصر القابلة للتجميع التي يتم عرضها. على سبيل المثال، إذا لم تكن تريد عرض التحية إذا كان الاسم فارغًا، استخدِم الحالة في عبارة if:

@Composable
fun HelloContent() {
    Column(modifier = Modifier.padding(16.dp)) {
        var name by remember { mutableStateOf("") }
        if (name.isNotEmpty()) {
            Text(
                text = "Hello, $name!",
                modifier = Modifier.padding(bottom = 8.dp),
                style = MaterialTheme.typography.bodyMedium
            )
        }
        OutlinedTextField(
            value = name,
            onValueChange = { name = it },
            label = { Text("Name") }
        )
    }
}
StateOverviewSnippets.kt

على الرغم من أنّ remember يساعدك في الاحتفاظ بالحالة في عمليات إعادة التركيب، لا يتم الاحتفاظ بالحالة في عمليات تغيير الإعدادات. لإجراء ذلك، يجب استخدام rememberSaveable. تحفظ السمة rememberSaveable تلقائيًا أي قيمة يمكن حفظها في Bundle. بالنسبة إلى القيم الأخرى، يمكنك تمرير عنصر مخصّص لجهاز حفظ.

الأنواع الأخرى المتوافقة من الحالات

لا تتطلّب ميزة "الإنشاء" استخدام MutableState<T> للاحتفاظ بالحالة، إذ تتيح استخدام أنواع أخرى من العناصر القابلة للتتبّع. قبل قراءة نوع آخر من أنواع العناصر القابلة للتتبّع في Compose، يجب تحويله إلى State<T> حتى تتمكّن العناصر القابلة للتجميع من إعادة التركيب تلقائيًا عند تغيُّر الحالة.

يتم شحن أداة الإنشاء مع دوال لإنشاء State<T> من أنواع رصد الشائعة المستخدَمة في تطبيقات Android. قبل استخدام عمليات الدمج هذه، أضِف العناصر المناسبة كما هو موضّح أدناه:

• Flow: collectAsStateWithLifecycle()

  يجمع collectAsStateWithLifecycle() القيم من Flow بطريقة تراعي رحلة المستخدِم، ما يسمح لتطبيقك بالادخار موارد التطبيق. ويمثّل أحدث قيمة تمّ بثّها من State. استخدِم واجهة برمجة التطبيقات هذه كطريقة مقترَحة لجمع بيانات مسارات الإحالات الناجحة على تطبيقات Android.

  يجب استخدام الملحق التالي في ملف build.gradle (يجب أن يكون الإصدار 2.6.0-beta01 أو إصدار أحدث):

dependencies {
      ...
      implementation("androidx.lifecycle:lifecycle-runtime-compose:2.8.7")
}

dependencies {
      ...
      implementation "androidx.lifecycle:lifecycle-runtime-compose:2.8.7"
}

• Flow: collectAsState()

  تتشابه الدالة collectAsState مع الدالة collectAsStateWithLifecycle، لأنّها أيضًا تجمع القيم من Flow وتحوّلها إلى Compose State.

  استخدِم collectAsState للرمز البرمجي غير المرتبط بالنظام الأساسي بدلاً من collectAsStateWithLifecycle المخصّص لنظام Android فقط.

  لا يلزم توفُّر تبعيات إضافية لـ collectAsState، لأنّه متاح في compose-runtime.

• LiveData: observeAsState()

  يبدأ observeAsState() بمراقبة هذا LiveData ويمثّل قيمه من خلال State.

  يجب إدراج التبعية التالية في ملف build.gradle:

dependencies {
      ...
      implementation("androidx.compose.runtime:runtime-livedata:1.7.5")
}

dependencies {
      ...
      implementation "androidx.compose.runtime:runtime-livedata:1.7.5"
}

• RxJava2: subscribeAsState()

  subscribeAsState() هي دوالّ إضافية تحوّل تدفقات التفاعلية في RxJava2 (مثل Single وObservable Completable) إلى Compose State.

  يجب إدراج التبعية التالية في ملف build.gradle:

dependencies {
      ...
      implementation("androidx.compose.runtime:runtime-rxjava2:1.7.5")
}

dependencies {
      ...
      implementation "androidx.compose.runtime:runtime-rxjava2:1.7.5"
}

• RxJava3: subscribeAsState()

  subscribeAsState() هي دوالّ إضافية تحوّل تدفقات التفاعلية في RxJava3 (مثل Single وObservable Completable) إلى Compose State.

  يجب إدراج التبعية التالية في ملف build.gradle:

dependencies {
      ...
      implementation("androidx.compose.runtime:runtime-rxjava3:1.7.5")
}

dependencies {
      ...
      implementation "androidx.compose.runtime:runtime-rxjava3:1.7.5"
}

جدار الحماية المتتبِّع لحالة الاتصال مقابل جدار الحماية غير المتتبِّع لحالة الاتصال

إنّ العنصر القابل للتجميع الذي يستخدم remember لتخزين عنصر ينشئ حالة داخلية، ما يجعل العنصر القابل للتجميع يعتمد على الحالة. HelloContent هو مثال على عنصر قابل للدمج يتضمّن حالة لأنّه يحتفظ بحالة name ويُعدّلها داخليًا. يمكن أن يكون ذلك مفيداً في الحالات التي لا يحتاج فيها المتصل إلى التحكّم في الحالة ويمكنه استخدامها بدون الحاجة إلى إدارة الحالة بنفسه. ومع ذلك، تكون العناصر القابلة للتجميع التي تحتوي على حالة داخلية أقل قابلية لإعادة الاستخدام ويصعب اختبارها.

العنصر القابل للتجميع غير المحدد الحالة هو عنصر قابل للتجميع لا يحتفظ بأي حالة. إنّ إحدى الطرق السهلة لتحقيق وظائف بدون حالة هي استخدام حالة الرفع.

أثناء تطوير مكونات قابلة لإعادة الاستخدام، غالبًا ما تريد عرض إصدار يعتمد على الحالة وإصدار لا يعتمد على الحالة من المكوّن نفسه. يكون الإصدار الذي يتضمّن حالة مناسبًا للمتصلين الذين لا يهتمون بالحالة، ويكون الإصدار الذي لا يتضمّن حالة ضروريًا للمتصلين الذين يحتاجون إلى التحكّم في الحالة أو رفعها.

نقل القيمة

إنّ تصعيد الحالة في Compose هو نمط لنقل الحالة إلى المُرسِل الذي يُنشئ العنصر القابل للتجميع لإلغاء حالة العنصر القابل للتجميع. النمط العام لرفع الحالة في Jetpack Compose هو استبدال متغيّر الحالة بمعاملتَين:

• ‫value: T: القيمة الحالية المعروضة
• onValueChange: (T) -> Unit: حدث يطلب تغيير القيمة، حيث يكون T هو القيمة الجديدة المقترَحة

ومع ذلك، يمكنك استخدام onValueChange أو أيّ تنسيق آخر. إذا كانت هناك أحداث أكثر تحديدًا مناسبة للعنصر القابل للإنشاء، عليك تحديدها باستخدام الدوالّ اللامدا.

إنّ الحالة التي يتمّ رفعها بهذه الطريقة لها بعض السمات المهمة:

• مصدر واحد للحقيقة: من خلال نقل الحالة بدلاً من تكرارها، نضمن توفّر مصدر واحد للحقيقة. ويساعد ذلك في تجنّب حدوث أخطاء.
• مُدمجة: يمكن فقط للعناصر القابلة للتجميع التي تتضمّن حالة تعديل حالتها. وهو داخلي بالكامل.
• قابلة للمشاركة: يمكن مشاركة الحالة المُرفوعة مع عناصر قابلة للتجميع متعددة. إذا أردت قراءة name في عنصر مركب مختلف، ستسمح لك عملية الرفع بقراءة ذلك.
• قابلة للاعتراض: يمكن للمتصلين بالعناصر القابلة للتجميع التي لا تتضمّن حالة أن يقرّروا تجاهل الأحداث أو تعديلها قبل تغيير الحالة.
• غير مرتبطة: يمكن تخزين حالة العناصر القابلة للتجميع التي لا تتضمّن حالة في أي مكان. على سبيل المثال، أصبح من الممكن الآن نقل name إلى ViewModel.

في المثال، يمكنك استخراج name وonValueChange من HelloContent ونقلها إلى أعلى الشجرة إلى HelloScreen قابلة للتجميع تُدخِل HelloContent.

@Composable
fun HelloScreen() {
    var name by rememberSaveable { mutableStateOf("") }

    HelloContent(name = name, onNameChange = { name = it })
}

@Composable
fun HelloContent(name: String, onNameChange: (String) -> Unit) {
    Column(modifier = Modifier.padding(16.dp)) {
        Text(
            text = "Hello, $name",
            modifier = Modifier.padding(bottom = 8.dp),
            style = MaterialTheme.typography.bodyMedium
        )
        OutlinedTextField(value = name, onValueChange = onNameChange, label = { Text("Name") })
    }
}
StateOverviewSnippets.kt

من خلال رفع الحالة من HelloContent، يصبح من الأسهل التفكير في العنصر القابل للتجميع وإعادة استخدامه في حالات مختلفة واختباره. HelloContent مفصولة عن طريقة تخزين حالتها. ويعني ذلك أنّه في حال تعديل HelloScreen أو استبداله، لن يكون عليك تغيير كيفية تنفيذ HelloContent.

يُعرف النمط الذي تنخفض فيه الحالة وتزيد فيه الأحداث باسم تدفق البيانات أحادي الاتجاه. في هذه الحالة، تنخفض الحالة من HelloScreen إلى HelloContent وترتفع الأحداث من HelloContent إلى HelloScreen. من خلال اتّباع تدفق البيانات أحادي الاتجاه، يمكنك فصل العناصر القابلة للتجميع التي تعرِض الحالة في واجهة المستخدم عن أجزاء تطبيقك التي تخزِّن الحالة وتغيّرها.

اطّلِع على صفحة أماكن رفع الحالة لمعرفة المزيد من المعلومات.

استعادة الحالة في ميزة "الإنشاء"

تعمل واجهة برمجة التطبيقات rememberSaveable بالطريقة نفسها التي تعمل بها remember لأنّها تحافظ على الحالة في عمليات إعادة التركيب، وكذلك في عمليات إعادة إنشاء النشاط أو العملية باستخدام آلية حالة النسخة المحفوظة. على سبيل المثال، يحدث ذلك عند تدوير الشاشة.

طُرق تخزين الحالة

يتم تلقائيًا حفظ جميع أنواع البيانات التي تتم إضافتها إلى Bundle. إذا أردت حفظ عنصر لا يمكن إضافته إلى Bundle، تتوفّر عدة خيارات.

Parcelize

أبسط حلّ هو إضافة التعليق التوضيحي @Parcelize إلى الجسم. يصبح العنصر قابلاً للتقسيم ويمكن تجميعه. على سبيل المثال، تنشئ هذه التعليمة البرمجية نوع بيانات City قابلاً للتقسيم وتحفظه في القيمة state.

@Parcelize
data class City(val name: String, val country: String) : Parcelable

@Composable
fun CityScreen() {
    var selectedCity = rememberSaveable {
        mutableStateOf(City("Madrid", "Spain"))
    }
}
StateOverviewSnippets.kt

MapSaver

إذا لم تكن @Parcelize مناسبة لأي سبب، يمكنك استخدام mapSaver لتحديد قاعدتك الخاصة لتحويل عنصر إلى مجموعة من القيم التي يمكن للنظام حفظها في Bundle.

data class City(val name: String, val country: String)

val CitySaver = run {
    val nameKey = "Name"
    val countryKey = "Country"
    mapSaver(
        save = { mapOf(nameKey to it.name, countryKey to it.country) },
        restore = { City(it[nameKey] as String, it[countryKey] as String) }
    )
}

@Composable
fun CityScreen() {
    var selectedCity = rememberSaveable(stateSaver = CitySaver) {
        mutableStateOf(City("Madrid", "Spain"))
    }
}
StateOverviewSnippets.kt

ListSaver

لتجنّب الحاجة إلى تحديد مفاتيح الخريطة، يمكنك أيضًا استخدام listSaver واستخدام مؤشراتها كمفاتيح:

data class City(val name: String, val country: String)

val CitySaver = listSaver<City, Any>(
    save = { listOf(it.name, it.country) },
    restore = { City(it[0] as String, it[1] as String) }
)

@Composable
fun CityScreen() {
    var selectedCity = rememberSaveable(stateSaver = CitySaver) {
        mutableStateOf(City("Madrid", "Spain"))
    }
}
StateOverviewSnippets.kt

عناصر الاحتفاظ بالحالة في ميزة "الإنشاء"

يمكن إدارة عملية تصعيد الحالة البسيطة في الدوال القابلة للتجميع نفسها. ومع ذلك، إذا زادت حالة تتبُّعها أو إذا ظهرت الحاجة إلى تنفيذ منطق في دوال قابلة للتجميع، من الممارسات الجيدة تفويض مسؤوليات المنطق والحالة إلى فئات أخرى: حائزو الحالة.

للاطّلاع على مزيد من المعلومات، يمكنك الاطّلاع على مستندات نقل الحالة في أداة Compose أو بشكلٍ عام على صفحة حاملو الحالة وحالة واجهة المستخدم في دليل التصميم.

إعادة تشغيل عمليات احتساب ميزة "تذكر كلمات المرور" عند تغيير المفاتيح

يتم استخدام واجهة برمجة التطبيقات remember بشكل متكرّر مع MutableState:

var name by remember { mutableStateOf("") }
StateOverviewSnippets.kt

في هذه الحالة، يؤدي استخدام الدالة remember إلى الاحتفاظ بقيمة MutableState في عمليات إعادة التركيب.

بشكل عام، تأخذ remember مَعلمة calculation lambda. عند تشغيل remember للمرة الأولى، يتمّ استدعاء دالة lambda calculation وتخزين نتيجتها. أثناء إعادة التركيب، تعرض remember القيمة التي تم تخزينها آخر مرة.

بالإضافة إلى حالة التخزين المؤقت، يمكنك أيضًا استخدام remember لتخزين أي عنصر أو نتيجة عملية في التركيب تتطلّب وقتًا طويلاً لبدء تشغيلها أو حسابها. قد لا تحتاج إلى تكرار هذا الحساب في كل عملية إعادة تركيب. على سبيل المثال، إنشاء عنصر ShaderBrush هذا، وهو عملية مكلفة:

val brush = remember {
    ShaderBrush(
        BitmapShader(
            ImageBitmap.imageResource(res, avatarRes).asAndroidBitmap(),
            Shader.TileMode.REPEAT,
            Shader.TileMode.REPEAT
        )
    )
}
StateOverviewSnippets.kt

تخزِّن remember القيمة إلى أن تغادر "التركيبة". ومع ذلك، هناك طريقة لإبطال القيمة المخزّنة مؤقتًا. تأخذ واجهة برمجة التطبيقات remember أيضًا مَعلمة key أو keys. إذا تغيّر أيّ من هذه المفاتيح، في المرة التالية التي تتم فيها إعادة تركيب الدالة، تبطل remember ذاكرة التخزين المؤقت وتنفِّذ عملية الحسابات وحدة lambda مرة أخرى. تمنحك هذه الآلية إمكانية التحكّم في مدة بقاء العنصر في التركيب. ويظلّ الحساب صالحًا إلى أن تتغيّر المدخلات، بدلاً من أن تغادر القيمة التي تم تذكُّرها من "التركيب".

توضّح الأمثلة التالية آلية عمل هذه الآلية.

في هذا المقتطف، تم إنشاء ShaderBrush واستخدامه كخلفية لوحة ألوان لعنصر Box قابل للتركيب. تخزِّن remember مثيل ShaderBrush لأنّ إعادة إنشائه باهظة التكلفة، كما شرحنا سابقًا. يأخذ remember avatarRes كمَعلمة key1، وهي صورة الخلفية المحدّدة. إذا حدث تغيير في avatarRes، تتم إعادة إنشاء الفرشاة باستخدام الصورة الجديدة، ويتم إعادة تطبيقها على Box. ويمكن أن يحدث ذلك عندما يختار المستخدم صورة أخرى لتكون الخلفية من أداة اختيار.

@Composable
private fun BackgroundBanner(
    @DrawableRes avatarRes: Int,
    modifier: Modifier = Modifier,
    res: Resources = LocalContext.current.resources
) {
    val brush = remember(key1 = avatarRes) {
        ShaderBrush(
            BitmapShader(
                ImageBitmap.imageResource(res, avatarRes).asAndroidBitmap(),
                Shader.TileMode.REPEAT,
                Shader.TileMode.REPEAT
            )
        )
    }

    Box(
        modifier = modifier.background(brush)
    ) {
        /* ... */
    }
}
StateOverviewSnippets.kt

في المقتطف التالي، يتم تصعيد الحالة إلى فئة حامل حالة عادية MyAppState. ويعرِض دالة rememberMyAppState لتهيئة مثيل من الفئة باستخدام remember. إنّ عرض هذه الدوال لإنشاء مثيل يبقى سليمًا بعد عمليات إعادة التركيب هو نمط شائع في أداة "الإنشاء". تتلقّى الدالة rememberMyAppState العنصر windowSizeClass، الذي يُستخدَم كمَعلمة key للدالة remember. في حال تغيّرت هذه المَعلمة، يجب على التطبيق إعادة إنشاء فئة حامل الحالة العادية باستخدام القيمة الأخيرة. وقد يحدث ذلك مثلاً إذا غيّر المستخدم وضع الجهاز.

@Composable
private fun rememberMyAppState(
    windowSizeClass: WindowSizeClass
): MyAppState {
    return remember(windowSizeClass) {
        MyAppState(windowSizeClass)
    }
}

@Stable
class MyAppState(
    private val windowSizeClass: WindowSizeClass
) { /* ... */ }
StateOverviewSnippets.kt

تستخدِم الدالة Compose طريقة تنفيذ equals في الفئة لتحديد ما إذا كان قد حدث تغيير في المفتاح وإبطال القيمة المخزّنة.

تخزين الحالة باستخدام مفاتيح بعد إعادة التركيب

واجهة برمجة التطبيقات rememberSaveable هي برنامج تضمين لواجهة برمجة التطبيقات remember يمكنه تخزين data في Bundle. لا تسمح واجهة برمجة التطبيقات هذه ببقائها في حالة إعادة التركيب فحسب، بل تسمح أيضًا بإعادة إنشاء النشاط وإيقاف العملية التي بدأها النظام. تتلقّى rememberSaveable مَعلمات input للغرض نفسه الذي تتلقّى فيه remember مَعلمات keys. يتم إلغاء صلاحية ذاكرة التخزين المؤقت عند تغيير أيّ من المدخلات. في المرة التالية التي تتم فيها إعادة تركيب الدالة، يُعيد rememberSaveable تنفيذ وحدة LAMBDA الحسابية.

في المثال التالي، يخزِّن rememberSaveable القيمة userTypedQuery إلى أن يتم تغيير typedQuery:

var userTypedQuery by rememberSaveable(typedQuery, stateSaver = TextFieldValue.Saver) {
    mutableStateOf(
        TextFieldValue(text = typedQuery, selection = TextRange(typedQuery.length))
    )
}
StateOverviewSnippets.kt

مزيد من المعلومات

لمزيد من المعلومات عن الحالة وJetpack Compose، يمكنك الرجوع إلى المراجع التالية الإضافية.

نماذج

الدروس التطبيقية حول الترميز

• استخدام State في أداة Compose في Jetpack

الفيديوهات

• الاستعداد لإنشاء المحتوى

المدوّنات

• إدارة حالة TextField الفعّالة في ميزة "الإنشاء"