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

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

تتطلّب بنية التفويض 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.8")
}

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

• RxJava2: subscribeAsState()

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

  الاعتمادية التالية مطلوبة في ملف build.gradle:

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

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

• RxJava3: subscribeAsState()

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

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

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

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

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

إنّ العنصر القابل للتجميع الذي يستخدم 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

أداة حفظ الخرائط

إذا لم تكن @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 واستخدام مؤشراتها كمفاتيح:

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. عند تشغيل 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. إن الكشف عن هذه الدوال لإنشاء مثيل يحافظ على إعادة التركيب هو نمط شائع في Compose. تتلقّى الدالة 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 الفعّالة في ميزة "الإنشاء"