لوحة مفاتيح Android KTX جزء من Android Jetpack.

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

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

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

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

وتتناسب لغة Kotlin lambdas بشكل مثالي مع حالة الاستخدام هذه. إنها تسمح لك بأخذ أكثر إيجازًا من خلال تمرير كتلة من التعليمات البرمجية لتنفيذها بعد إنشاء تم إنشاؤه، والسماح بتنفيذ الرمز البرمجي، ثم السماح لواجهة برمجة تطبيقات 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 lambda هي في حد ذاتها دالة إضافة مجهولة على SharedPreferences.Editor التي تعرض Unit، كما هو موضح في توقيعها. هذا هو السبب في أن داخل يمكنك تنفيذ العمل مباشرةً SharedPreferences.Editor

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

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

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

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

Groovy

repositories {
    google()
}

Kotlin

repositories {
    google()
}

وحدات AndroidX

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

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

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

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

حزمة KTX الأساسية

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

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

Groovy

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

Kotlin

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

فيما يلي قائمة بالحزم الموجودة في وحدة Core KTX:

مجموعة KTX

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

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

Groovy

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

Kotlin

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

تستفيد إضافات المجموعة من التحميل الزائد لمشغل 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 في تطبيقك:

Groovy

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

Kotlin

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

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

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 قيمة LifecycleScope لكل الكائن Lifecycle. أي كوروتين التي تم إطلاقها في هذا النطاق عند إتلاف Lifecycle. يمكنك الوصول إلى CoroutineScope من Lifecycle باستخدام المواقع على lifecycle.coroutineScope أو lifecycleOwner.lifecycleScope

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

Groovy

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

Kotlin

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

يوضح المثال التالي كيفية استخدام 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)
        }
    }
}

ملف LiveData KTX

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

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

Groovy

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

Kotlin

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

في المثال التالي، 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 في تطبيقك:

Groovy

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

Kotlin

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

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

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

تشير رسالة الأشكال البيانية وحدة Palette KTX توفر دعم Kotlin الاصطلاحي للعمل على لوحات الألوان.

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

Groovy

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]

فيديوهات KTX التفاعلية

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

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

Groovy

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

Kotlin

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

كمثال، افترض أن قاعدة بيانات بها قائمة صغيرة من المستخدمين. في تطبيقك، يمكنك تحميل قاعدة البيانات في الذاكرة ثم عرض بيانات المستخدم في واجهة المستخدم. لتحقيق لهذا، يمكنك استخدام 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 في تطبيقك:

Groovy

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

Kotlin

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

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

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

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

لغة SQLite KTX

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

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

Groovy

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

Kotlin

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

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

db.transaction {
    // insert data
}

عرض الطراز KTX

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

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

Groovy

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

Kotlin

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

على سبيل المثال، تُطلق دالة 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()
}

أداة WorkManager KTX

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

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

Groovy

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

Kotlin

dependencies {
    implementation("androidx.work:work-runtime-ktx:2.9.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.

حزمة KTX من Firebase

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

منصة خرائط Google KTX

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

تشغيل Core KTX

حزمة Play Core KTX تُتيح استخدام الكوروتينات في لغة Kotlin في الطلبات المُرسَلة لمرة واحدة وFloodlight لمراقبة تحديثات الحالة من خلال إدراج وظائف الإضافات في SplitInstallManager وAppUpdateManager في مكتبة Play Core.

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

Groovy

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