AppState   جزء من Android Jetpack

‫Jetpack AppState هي مجموعة من المكتبات التي تساعدك في توسيع نطاق Jetpack Compose State خارج طبقة واجهة المستخدم لتتمكّن من تحويل الحالة التفاعلية ومشاركتها على مستوى أي طبقة من تطبيقك. تتكوّن AppState من مكتبتَين رئيسيتَين:

  • ‫Transform: هي مكتبة مبنية على بيئة تشغيل Compose تنفّذ مجموعة تعليمات برمجية @Composable بدون واجهة مستخدم لدمج مصادر الحالة وتحويلها إلى State في Compose.
  • StateStore: حاوية تمنع أخطاء الكتابة وتخزّن حالة التطبيق المشتركة وتعرضها على شكل State في Compose. ويُستخدم عادةً لمشاركة الحالة عبر مكوّنات التطبيق المتعددة.

لمعرفة كيفية عمل Compose State خارج الدوال المركّبة لواجهة المستخدم وكيفية توافق Transform وStateStore مع واجهات برمجة تطبيقات Compose الحالية، مثل mutableStateOf وSavedStateHandle.saveable في البنية، يُرجى الاطّلاع على استخدام حالة Compose خارج واجهة المستخدم.

العناصر

للبدء في استخدام AppState، أضِف العناصر التي يحتاجها مشروعك مع أي مكتبات داعمة:

الاسم وظيفته العناصر
تحويل ينتج State في Compose ويلاحظه خارج واجهة المستخدم (transform وlistener). androidx.appstate.transform:transform
تحويل الاختبار أدوات اختبار Transform (transformTest وTransformTestScope) androidx.appstate.transform:transform-testing
StateStore حاوية الحالة الأساسية لمنع أخطاء الكتابة وتعريفات StateStoreKey androidx.appstate.statestore:statestore
دمج StateStore DataStore يتم الاحتفاظ بمفاتيح StateStore واستعادتها على القرص باستخدام Jetpack DataStore. androidx.appstate.statestore:statestore-datastore
المكوّن الإضافي Compose Compiler يتم تجميع دوالّ وكتل @Composable في الوحدات التي تستخدم transform أو listener. org.jetbrains.kotlin.plugin.compose
المكوّن الإضافي KotlinX Serialization يتم إنشاء أدوات تسلسل لـ @Serializable StateStoreKey وأنواع الحالات المخصّصة عند استخدام statestore-datastore. org.jetbrains.kotlin.plugin.serialization
مكتبة KotlinX Serialization مكتبة تسلسل وقت التشغيل لـ @Serializable StateStoreKey وأنواع الحالات المخصّصة عند استخدام statestore-datastore. org.jetbrains.kotlinx:kotlinx-serialization-core

إعداد المشروع

لإضافة مكتبات AppState إلى مشروعك، حدِّد الإصدارات والمكتبات والمكوّنات الإضافية لـ Gradle في ملف libs.versions.toml:

[versions]
appstate = "1.0.0-alpha01"
kotlin = "2.4.10"
kotlinxSerializationCore = "1.11.0"

[libraries]
# Transform library for producing and observing Compose State
androidx-appstate-transform = { module = "androidx.appstate.transform:transform", version.ref = "appstate" }
# Testing utilities for Transform
androidx-appstate-transform-testing = { module = "androidx.appstate.transform:transform-testing", version.ref = "appstate" }
# Core StateStore library
androidx-appstate-statestore = { module = "androidx.appstate.statestore:statestore", version.ref = "appstate" }
# DataStore integration for StateStore (and required serialization runtime)
androidx-appstate-statestore-datastore = { module = "androidx.appstate.statestore:statestore-datastore", version.ref = "appstate" }
kotlinx-serialization-core = { module = "org.jetbrains.kotlinx:kotlinx-serialization-core", version.ref = "kotlinxSerializationCore" }

[plugins]
compose-compiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
# Required only when using statestore-datastore
jetbrains-kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

بعد ذلك، اضبط ملف build.gradle.kts الخاص بالوحدة:

plugins {
    ...
    alias(libs.plugins.compose.compiler)
    // Required only when using statestore-datastore
    alias(libs.plugins.jetbrains.kotlin.serialization)
}

android {
    ...
    buildFeatures {
        compose = true
    }
}

dependencies {
    ...
    implementation(libs.androidx.appstate.transform)
    implementation(libs.androidx.appstate.statestore)

    // Optional: DataStore integration for StateStore
    implementation(libs.androidx.appstate.statestore.datastore)
    implementation(libs.kotlinx.serialization.core)

    ...
    testImplementation(libs.androidx.appstate.transform.testing)
}

عيّنات تعليمات برمجية

يحتوي مستودع وصفات AppState على أمثلة عملية توضّح كيفية استخدام Transform وStateStore في أنماط بنية Android الشائعة وأشكال الأجهزة.

تقديم ملاحظات

يمكنك مشاركة ملاحظاتك أو الإبلاغ عن الأخطاء أو طلب ميزات باستخدام أداة تتبُّع مشاكل Transform أو أداة تتبُّع مشاكل StateStore.