Android KTX جزء من Android Jetpack.

Android KTX هو مجموعة من إضافات Kotlin التي يتم تضمينها مع Android Jetpack ومكتبات Android الأخرى. توفر إضافات KTX لغة مختصرة ودلالية للغة Kotlin ونظام Android الأساسي وواجهات برمجة تطبيقات أخرى. ولإجراء ذلك، تستفيد هذه الإضافات من العديد من ميزات لغة Kotlin، بما في ذلك ما يلي:

  • وظائف الإضافة
  • خصائص الإضافة
  • مصابيح لامدا
  • المعلمات المسماة
  • القيم الافتراضية للمعلمة
  • كوروتين

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

sharedPreferences
        .edit()  // create an Editor
        .putBoolean("key", value)
        .apply() // write to disk asynchronously

وتتناسب تمامًا حالة الاستخدام هذه مع لغة Kotlin lambda. وتسمح لك باتباع منهج أكثر إيجازًا من خلال تمرير مجموعة من الشفرة ليتم تنفيذها بعد إنشاء المحرر، مما يسمح بتنفيذ الشفرة، ثم السماحSharedPreferences تطبيق التغييرات بالكامل.

في ما يلي مثال على إحدى وظائف Android KTX Core، SharedPreferences.edit، التي تضيف وظيفة تعديل إلى SharedPreferences. تأخذ هذه الدالة علامة boolean اختيارية كوسيطة أولى تشير إلى ما إذا كان يجب تنفيذ التغييرات أو تطبيقها. ويحصل أيضًا على إجراء لتنفيذه على محرّر SharedPreferences في شكل دالة lambda.

// SharedPreferences.edit extension function signature from Android KTX - Core
// inline fun SharedPreferences.edit(
//         commit: Boolean = false,
//         action: SharedPreferences.Editor.() -> Unit)

// Commit a new value asynchronously
sharedPreferences.edit { putBoolean("key", value) }

// Commit a new value synchronously
sharedPreferences.edit(commit = true) { putBoolean("key", value) }

يمكن للمتصل اختيار تنفيذ التغييرات أو تطبيقها. لامدا action هي في حد ذاتها دالة إضافة مجهولة الهوية في SharedPreferences.Editor تعرض Unit، كما هو موضح في توقيعها. لهذا السبب، يمكنك من داخل الوحدة تنفيذ العمل مباشرةً على SharedPreferences.Editor.

وأخيرًا، يتضمّن توقيع SharedPreferences.edit() الكلمة الرئيسية inline. تُخبر هذه الكلمة الرئيسية المحول البرمجي بلغة Kotlin أنه يجب نسخ ولصق (أو تضمين) الرمز المجمّع للدالة في كل مرة يتم فيها استخدام الدالة. ويجنّبك ذلك تكلفة إنشاء فئة جديدة لكل action في كل مرة يتم فيها استدعاء هذه الدالة.

هذا النمط من تمرير الشفرة باستخدام lambda، وتطبيق الإعدادات الافتراضية المعقولة التي يمكن تجاوزها، وإضافة هذه السلوكيات إلى واجهات برمجة التطبيقات الحالية باستخدامinline وظائف الإضافات هي نموذجية للتحسينات التي تقدمها مكتبة Android KTX.

استخدام Android KTX في مشروعك

لبدء استخدام Android KTX، أضِف التبعية التالية إلى ملف build.gradle لمشروعك:

رائع

repositories {
    google()
}

لغة Kotlin

repositories {
    google()
}

وحدات AndroidX

يتم تنظيم Android KTX في شكل وحدات، حيث تحتوي كل وحدة على حزمة واحدة أو أكثر.

يجب تضمين تبعية لكل عنصر من عناصر الوحدة في ملف build.gradle للتطبيق. لا تنسَ إلحاق رقم الإصدار بالعنصر. يمكنك العثور على أحدث أرقام الإصدار في القسم الخاص بكل عنصر في هذا الموضوع.

يحتوي Android KTX على وحدة أساسية واحدة توفر إضافات Kotlin لواجهات برمجة التطبيقات لإطار العمل الشائع والعديد من الإضافات الخاصة بالنطاق.

وباستثناء الوحدة الأساسية، فإن جميع عناصر وحدة KTX تحل محل تبعية جافا الأساسية في ملف build.gradle. على سبيل المثال، يمكنك استبدال التبعية androidx.fragment:fragment بـ androidx.fragment:fragment-ktx. تساعد هذه البنية في إدارة الإصدارات بشكل أفضل ولا تضيف متطلبات إعلان اعتمادية إضافية.

Core KTX

تقدم وحدة KTX الأساسية إضافات للمكتبات الشائعة التي تعد جزءًا من إطار عمل Android. لا تحتوي هذه المكتبات على تبعيات مستندة إلى جافا تحتاج إلى إضافتها إلى build.gradle.

لتضمين هذه الوحدة، أضف ما يلي إلى ملف build.gradle لتطبيقك:

أنيق

dependencies {
    implementation "androidx.core:core-ktx:1.10.1"
}

Kotlin

dependencies {
    implementation("androidx.core:core-ktx:1.10.1")
}

في ما يلي قائمة بالحزم المضمنة في وحدة KTX الأساسية:

مجموعة KTX

تحتوي إضافات المجموعة على وظائف مساعدة للعمل مع مكتبات جمع فعّالة للذاكرة في Android، بما في ذلك ArrayMap وLongSparseArray LruCache وغيرها.

لاستخدام هذه الوحدة، أضِف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.collection:collection-ktx:1.2.0"
}

لغة Kotlin

dependencies {
    implementation("androidx.collection:collection-ktx:1.2.0")
}

تستفيد إضافات المجموعة من التحميل الزائد على مشغل لغة Kotlin لتبسيط أشياء مثل تسلسل المجموعة، كما هو موضح في المثال التالي:

// Combine 2 ArraySets into 1.
val combinedArraySet = arraySetOf(1, 2, 3) + arraySetOf(4, 5, 6)

// Combine with numbers to create a new sets.
val newArraySet = combinedArraySet + 7 + 8

جزء KTX

وتقدم وحدة تجزئة KTX عددًا من الإضافات لتبسيط واجهة برمجة التطبيقات للجزء.

لتضمين هذه الوحدة، أضف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.fragment:fragment-ktx:1.5.7"
}

لغة Kotlin

dependencies {
    implementation("androidx.fragment:fragment-ktx:1.5.7")
}

باستخدام وحدة Fragment KTX، يمكنك تبسيط المعاملات المجزأة باستخدام lambda، على سبيل المثال:

fragmentManager().commit {
   addToBackStack("...")
   setCustomAnimations(
           R.anim.enter_anim,
           R.anim.exit_anim)
   add(fragment, "...")
}

يمكنك أيضًا الربط بـ ViewModel في سطر واحد باستخدام المفوَّضين التابعين للموقعَين viewModels وactivityViewModels:

// Get a reference to the ViewModel scoped to this Fragment
val viewModel by viewModels<MyViewModel>()

// Get a reference to the ViewModel scoped to its Activity
val viewModel by activityViewModels<MyViewModel>()

دورة حياة KTX

تحدّد أداة KTX Lifecycle LifecycleScope لكل عنصر من عناصر Lifecycle. ويتم إلغاء أي كوروتين يتم إطلاقه في هذا النطاق عند إتلاف Lifecycle. يمكنك الوصول إلى CoroutineScope من Lifecycle باستخدام السمتَين lifecycle.coroutineScope أو lifecycleOwner.lifecycleScope.

لتضمين هذه الوحدة، أضف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.lifecycle:lifecycle-runtime-ktx:2.6.1"
}

لغة Kotlin

dependencies {
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.6.1")
}

يوضح المثال التالي كيفية استخدام lifecycleOwner.lifecycleScope لإنشاء نص محسوب مسبقًا بشكل غير متزامن:

class MyFragment: Fragment() {
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        viewLifecycleOwner.lifecycleScope.launch {
            val params = TextViewCompat.getTextMetricsParams(textView)
            val precomputedText = withContext(Dispatchers.Default) {
                PrecomputedTextCompat.create(longTextContent, params)
            }
            TextViewCompat.setPrecomputedText(textView, precomputedText)
        }
    }
}

KTX LiveData

عند استخدام LiveData، قد تحتاج إلى حساب القيم بشكلٍ غير متزامن. على سبيل المثال، قد ترغب في استرداد تفضيلات المستخدم وعرضها على واجهة المستخدم. بالنسبة إلى هذه الحالات، توفّر أداة LiveData KTX دالة إنشاء liveData التي تستدعي دالة suspend وتعرض النتيجة كعنصر LiveData.

لتضمين هذه الوحدة، أضف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.lifecycle:lifecycle-livedata-ktx:2.6.1"
}

لغة Kotlin

dependencies {
    implementation("androidx.lifecycle:lifecycle-livedata-ktx:2.6.1")
}

في المثال التالي، loadUser() هي وظيفة تعليق معلَّقة في مكان آخر. يمكنك استخدام دالة الإنشاء في liveData لاستدعاء loadUser() بشكل غير متزامن، ثم استخدام emit() لإخراج النتيجة:

val user: LiveData<User> = liveData {
    val data = database.loadUser() // loadUser is a suspend function.
    emit(data)
}

لمزيد من المعلومات عن استخدام الكوروتين مع LiveData، راجِع استخدام الكوروتينات Kotlin مع مكوّنات الهندسة.

يحتوي كل مكون من مكونات مكتبة التنقل على إصدار KTX الخاص به والذي يعدل واجهة برمجة التطبيقات بحيث تكون أكثر إيجازًا ولغةً بتنسيق Kotlin.

لتضمين هذه الوحدات، أضف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.navigation:navigation-runtime-ktx:2.5.3"
    implementation "androidx.navigation:navigation-fragment-ktx:2.5.3"
    implementation "androidx.navigation:navigation-ui-ktx:2.5.3"
}

لغة Kotlin

dependencies {
    implementation("androidx.navigation:navigation-runtime-ktx:2.5.3")
    implementation("androidx.navigation:navigation-fragment-ktx:2.5.3")
    implementation("androidx.navigation:navigation-ui-ktx:2.5.3")
}

استخدم وظائف الإضافة وتفويض الموقع للوصول إلى وسيطات الوجهة والانتقال إلى الوجهات، كما هو موضح في المثال التالي:

class MyDestination : Fragment() {

    // Type-safe arguments are accessed from the bundle.
    val args by navArgs<MyDestinationArgs>()

    ...
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        view.findViewById<Button>(R.id.next)
            .setOnClickListener {
                // Fragment extension added to retrieve a NavController from
                // any destination.
                findNavController().navigate(R.id.action_to_next_destination)
            }
     }
     ...

}

لوحة ألوان KTX

توفر وحدة باليت KTX دعمًا اصطلاحيًا للغة Kotlin للتعامل مع لوحات الألوان.

لاستخدام هذه الوحدة، أضِف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.palette:palette-ktx:1.0.0"
}

لغة Kotlin

dependencies {
    implementation("androidx.palette:palette-ktx:1.0.0")
}

على سبيل المثال، عند العمل معPalette يمكنك استرداد selected نموذج محدّدtarget باستخدام عامل التشغيل get ([ ] ):

val palette = Palette.from(bitmap).generate()
val swatch = palette[target]

سلسلة Kactive Streams KTX

تتيح لك وحدة KTX لساحات المشاركات التفاعلية إنشاء بث LiveData يمكن ملاحظته من ناشر ReactiveStreams.

لتضمين هذه الوحدة، أضف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.lifecycle:lifecycle-reactivestreams-ktx:2.6.1"
}

لغة Kotlin

dependencies {
    implementation("androidx.lifecycle:lifecycle-reactivestreams-ktx:2.6.1")
}

على سبيل المثال، لنفترض أن قاعدة بيانات تحتوي على قائمة صغيرة من المستخدمين. في تطبيقك، يمكنك تحميل قاعدة البيانات إلى الذاكرة ثم عرض بيانات المستخدم في واجهة المستخدم. ولتحقيق ذلك، يمكنك استخدام RxJava. يمكن لمكوِّن Jetpack على Room استرداد قائمة المستخدمين كملف Flowable. في هذا السيناريو، يجب أيضًا إدارة اشتراك ناشر Rx على مدار عمر الجزء أو النشاط.

ومع ذلك، في LiveDataReactiveStreams، يمكنك الاستفادة من RxJava ومن خلال المجموعة الغنيّة من عوامل التشغيل وإمكانات جدولة العمل مع العمل أيضًا مع بساطة LiveData، كما هو موضّح في المثال التالي:

val fun getUsersLiveData() : LiveData<List<User>> {
    val users: Flowable<List<User>> = dao.findUsers()
    return LiveDataReactiveStreams.fromPublisher(users)
}

غرفة KTX

وتضيف إضافات الغرفة دعم الكوروتينات لمعاملات قاعدة البيانات.

لاستخدام هذه الوحدة، أضِف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.room:room-ktx:2.5.1"
}

لغة Kotlin

dependencies {
    implementation("androidx.room:room-ktx:2.5.1")
}

في ما يلي بعض الأمثلة على استخدام الغرفة الآن للكوروتينات. يستخدم المثال الأول دالة suspend لعرض قائمة بكائنات User، بينما يستخدم المثال الثاني لغة Kotlin Flow لعرض الدالة بشكل غير متزامن قائمة User. لاحظ أنه عند استخدام Flow، سيتم إشعارك أيضًا بأي تغييرات في الجداول التي تبحث عنها.

@Query("SELECT * FROM Users")
suspend fun getUsers(): List<User>

@Query("SELECT * FROM Users")
fun getUsers(): Flow<List<User>>

لوحة مفاتيح Kite لـ SQLite

تعمل إضافات SQLite على التفاف الشفرة المرتبطة بـ SQL في المعاملات، مما يؤدي إلى إزالة الكثير من الشفرات النموذجية.

لاستخدام هذه الوحدة، أضِف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.sqlite:sqlite-ktx:2.3.1"
}

لغة Kotlin

dependencies {
    implementation("androidx.sqlite:sqlite-ktx:2.3.1")
}

في ما يلي مثال على استخدام الإضافة transaction لتنفيذ معاملة قاعدة بيانات:

db.transaction {
    // insert data
}

نموذج KTX في طريقة العرض

توفر مكتبة ViewModel KTXviewModelScope() والتي تسهل إطلاقهاالكوروتينات منViewModel {0}{/0}. يتم ربط CoroutineScope بـ Dispatchers.Main ويتم إلغاؤها تلقائيًا عند محو ViewModel. يمكنك استخدام viewModelScope() بدلاً من إنشاء نطاق جديد لكل ViewModel.

لتضمين هذه الوحدة، أضف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:2.6.1"
}

لغة Kotlin

dependencies {
    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.6.1")
}

على سبيل المثال، تُطلق الدالة viewModelScope() عنصر كوروتين ينشئ طلب شبكة في سلسلة محادثات في الخلفية. تعالج المكتبة جميع عمليات الإعداد ومسح النطاق المقابل:

class MainViewModel : ViewModel() {
    // Make a network request without blocking the UI thread
    private fun makeNetworkRequest() {
        // launch a coroutine in viewModelScope
        viewModelScope.launch  {
            remoteApi.slowFetch()
            ...
        }
    }

    // No need to override onCleared()
}

لوحة مفاتيح KTX في مدير العمل

يوفر WorkManager KTX دعمًا من الدرجة الأولى للكوروتينات.

لتضمين هذه الوحدة، أضف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "androidx.work:work-runtime-ktx:2.8.1"
}

لغة Kotlin

dependencies {
    implementation("androidx.work:work-runtime-ktx:2.8.1")
}

بدلاً من توسيع Worker، يمكنك الآن توسيع CoroutineWorker الذي يحتوي على واجهة برمجة تطبيقات مختلفة قليلاً. على سبيل المثال، إذا أردت إنشاء CoroutineWorker بسيط لإجراء بعض عمليات الشبكة، يمكنك إجراء ما يلي:

class CoroutineDownloadWorker(context: Context, params: WorkerParameters)
        : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result = coroutineScope {
        val jobs = (0 until 100).map {
            async {
                downloadSynchronously("https://www.google.com")
            }
        }

        // awaitAll will throw an exception if a download fails, which
        // CoroutineWorker will treat as a failure
        jobs.awaitAll()
        Result.success()
    }
}

لمزيد من المعلومات عن استخدام CoroutineWorker، يُرجى الاطّلاع على سلسلة المحادثات في CoroutineWorker.

يضيف WorkManager KTX وظائف إضافة إلى Operations و ListenableFutures لتعليق الكورتين الحالي.

في ما يلي مثال يعلّق Operation الذي يعرضه enqueue():

// Inside of a coroutine...

// Run async operation and suspend until completed.
WorkManager.getInstance()
        .beginWith(longWorkRequest)
        .enqueue().await()

// Resume after work completes...

وحدات KTX أخرى

كما يمكنك تضمين وحدات KTX إضافية موجودة خارج AndroidX.

Firebase KTX

تحتوي بعض حزم Firebase SDK لنظام التشغيل Android على مكتبات إضافة Kotlin تتيح لك كتابة رموز لغة Kotlin الاصطلاحية عند استخدام Firebase في تطبيقك. لمزيد من المعلومات، اطلع على الموضوعات التالية:

لوحة خرائط Google KTX

تتوفر إضافات KTX لحزم Android SDK في "منصة خرائط Google" التي تسمح لك بالاستفادة من العديد من ميزات لغة Kotlin، مثل وظائف الإضافات والمعلمات المُسمّاة والوسيطات التلقائية وتدمير التصريحات والكوروتينات. لمزيد من المعلومات، اطلع على الموضوعات التالية:

تشغيل Core KTX

يضيف Play Core KTX دعمًا لكوروتينات Kotlin لطلبات اللقطة الواحدة و"التدفق" لمراقبة تحديثات الحالة من خلال إضافة وظائف الإضافة إلى SplitInstallManager وAppUpdateManager في مكتبة Play Core.

لتضمين هذه الوحدة، أضف ما يلي إلى ملف build.gradle لتطبيقك:

رائع

dependencies {
    implementation "com.google.android.play:core-ktx:1.8.1"
}

لغة Kotlin

dependencies {
    implementation("com.google.android.play:core-ktx:1.8.1")
}

في ما يلي مثال على Flow لمراقبة الحالة:

// Inside of a coroutine...

// Request in-app update status updates.
manager.requestUpdateFlow().collect { updateResult ->
    when (updateResult) {
        is AppUpdateResult.Available -> TODO()
        is AppUpdateResult.InProgress -> TODO()
        is AppUpdateResult.Downloaded -> TODO()
        AppUpdateResult.NotAvailable -> TODO()
    }
}

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

للتعرف على مزيد من المعلومات حول Android KTX، اطلع على فيديو DevBytes.

للإبلاغ عن مشكلة أو اقتراح ميزة، استخدِم أداة تتبُّع المشاكل في Android KTX.