این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اندروید KTX بخشی از جت‌پک اندروید .

اندروید KTX مجموعه‌ای از افزونه‌های کاتلین است که در اندروید جت‌پک و سایر کتابخانه‌های اندروید گنجانده شده است. افزونه‌های KTX، کاتلین مختصر و اصطلاحی را به جت‌پک، پلتفرم اندروید و سایر APIها ارائه می‌دهند. برای انجام این کار، این افزونه‌ها از چندین ویژگی زبان کاتلین، از جمله موارد زیر، بهره می‌برند:

توابع افزونه
خواص افزونه
لامبداها
پارامترهای نامگذاری شده
مقادیر پیش‌فرض پارامتر
کوروتین‌ها

به عنوان مثال، هنگام کار با SharedPreferences ، قبل از اینکه بتوانید داده‌های تنظیمات را تغییر دهید، باید یک ویرایشگر ایجاد کنید . همچنین باید پس از پایان ویرایش، آن تغییرات را اعمال یا ثبت کنید، همانطور که در مثال زیر نشان داده شده است:

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

لامبداهای کاتلین برای این مورد استفاده کاملاً مناسب هستند. آن‌ها به شما این امکان را می‌دهند که با ارسال یک بلوک کد برای اجرا پس از ایجاد ویرایشگر، رویکرد مختصرتری را در پیش بگیرید، اجازه دهید کد اجرا شود و سپس به API SharedPreferences اجازه دهید تغییرات را به صورت اتمی اعمال کند.

در اینجا مثالی از یکی از توابع Android KTX Core، SharedPreferences.edit ، آورده شده است که یک تابع ویرایش را به SharedPreferences اضافه می‌کند. این تابع یک پرچم boolean اختیاری را به عنوان اولین آرگومان خود دریافت می‌کند که نشان می‌دهد آیا تغییرات را ثبت یا اعمال کند. همچنین عملی را برای انجام در ویرایشگر SharedPreferences به شکل یک لامبدا دریافت می‌کند.

// 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 است. این کلمه کلیدی به کامپایلر کاتلین می‌گوید که باید هر بار که از تابع استفاده می‌شود، بایت‌کد کامپایل شده برای تابع را کپی و پیست (یا inline ) کند. این کار از سربار نمونه‌سازی یک کلاس جدید برای هر action هر بار که این تابع فراخوانی می‌شود، جلوگیری می‌کند.

این الگوی ارسال کد با استفاده از لامبدا، اعمال پیش‌فرض‌های معقول که می‌توانند لغو شوند، و اضافه کردن این رفتارها به APIهای موجود با استفاده از توابع افزونه inline ، نمونه‌ای از پیشرفت‌های ارائه شده توسط کتابخانه KTX اندروید است.

از Android KTX در پروژه خود استفاده کنید

برای شروع استفاده از Android KTX، وابستگی زیر را به فایل build.gradle پروژه خود اضافه کنید:

گرووی

repositories {
    google()
}

کاتلین

repositories {
    google()
}

ماژول‌های اندروید ایکس

اندروید KTX به ماژول‌هایی سازماندهی شده است که هر ماژول شامل یک یا چند بسته است.

شما باید برای هر ماژول مصنوعی، یک وابستگی در فایل build.gradle برنامه خود قرار دهید. به یاد داشته باشید که شماره نسخه را به آن اضافه کنید. می‌توانید شماره آخرین نسخه‌ها را در بخش مربوط به هر ماژول مصنوعی در این تاپیک پیدا کنید.

اندروید KTX شامل یک ماژول تک هسته‌ای است که افزونه‌های کاتلین را برای APIهای رایج فریم‌ورک و چندین افزونه مختص دامنه ارائه می‌دهد.

به استثنای ماژول اصلی، تمام مصنوعات ماژول KTX جایگزین وابستگی جاوا در فایل build.gradle شما می‌شوند. برای مثال، می‌توانید وابستگی androidx.fragment:fragment با androidx.fragment:fragment-ktx جایگزین کنید. این سینتکس به مدیریت بهتر نسخه‌بندی کمک می‌کند و الزامات اعلان وابستگی اضافی اضافه نمی‌کند.

هسته KTX

ماژول Core KTX افزونه‌هایی برای کتابخانه‌های رایج که بخشی از چارچوب اندروید هستند، ارائه می‌دهد. این کتابخانه‌ها وابستگی‌های مبتنی بر جاوا ندارند که لازم باشد به build.gradle اضافه کنید.

برای افزودن این ماژول، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

شیار

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

کاتلین

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

در اینجا لیستی از بسته‌هایی که در ماژول Core KTX وجود دارند، آورده شده است:

مجموعه KTX

افزونه‌های Collection شامل توابع کاربردی برای کار با کتابخانه‌های collection اندروید با مصرف بهینه حافظه، از جمله ArrayMap ، LongSparseArray ، LruCache و موارد دیگر هستند.

برای استفاده از این ماژول، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

شیار

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

کاتلین

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

افزونه‌های مجموعه از سربارگذاری عملگر کاتلین برای ساده‌سازی مواردی مانند الحاق مجموعه‌ها استفاده می‌کنند، همانطور که در مثال زیر نشان داده شده است:

// 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

ماژول Fragment KTX تعدادی افزونه برای ساده‌سازی API فرگمنت ارائه می‌دهد.

برای افزودن این ماژول، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

شیار

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

کاتلین

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

با ماژول Fragment KTX، می‌توانید تراکنش‌های fragment را با lambdaها ساده کنید، برای مثال:

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

همچنین می‌توانید با استفاده از نماینده‌های ویژگی viewModels و activityViewModels ، در یک خط به یک ViewModel متصل شوید:

// 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

Lifecycle KTX برای هر شیء Lifecycle یک LifecycleScope تعریف می‌کند. هر کوروتینی که در این scope راه‌اندازی شود، با از بین رفتن Lifecycle لغو می‌شود. می‌توانید با استفاده از ویژگی‌های lifecycle.coroutineScope یا lifecycleOwner.lifecycleScope به CoroutineScope مربوط به Lifecycle دسترسی داشته باشید.

برای افزودن این ماژول، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

شیار

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

کاتلین

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

لایودایتا KTX

هنگام استفاده از LiveData، ممکن است نیاز به محاسبه مقادیر به صورت غیرهمزمان داشته باشید. برای مثال، ممکن است بخواهید تنظیمات کاربر را بازیابی کرده و آنها را به رابط کاربری خود ارائه دهید. برای این موارد، LiveData KTX یک تابع سازنده liveData ارائه می‌دهد که یک تابع suspend را فراخوانی می‌کند و نتیجه را به عنوان یک شیء LiveData ارائه می‌دهد.

برای افزودن این ماژول، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

شیار

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

کاتلین

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

در مثال زیر، loadUser() یک تابع suspend است که در جای دیگری تعریف شده است. می‌توانید از تابع سازنده liveData برای فراخوانی loadUser() به صورت ناهمگام استفاده کنید و سپس از emit() برای انتشار نتیجه استفاده کنید:

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

برای اطلاعات بیشتر در مورد استفاده از کوروتین‌ها با LiveData ، به بخش «استفاده از کوروتین‌های کاتلین با کامپوننت‌های معماری» مراجعه کنید.

هر جزء از کتابخانه Navigation نسخه KTX مخصوص به خود را دارد که API را برای مختصرتر و با اصطلاحات کاتلین سازگار می‌کند.

برای اضافه کردن این ماژول‌ها، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

شیار

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

کاتلین

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

از توابع افزونه و واگذاری ویژگی برای دسترسی به آرگومان‌های مقصد و پیمایش به مقصدها، همانطور که در مثال زیر نشان داده شده است، استفاده کنید:

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 پشتیبانی اصطلاحی از کاتلین را برای کار با پالت‌های رنگ ارائه می‌دهد.

برای استفاده از این ماژول، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

شیار

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

کاتلین

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

به عنوان مثال، هنگام کار با یک نمونه Palette ، می‌توانید با استفاده از عملگر get ( [ ] )، نمونه selected را برای یک target مشخص بازیابی کنید:

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

جریان‌های واکنشی KTX

ماژول Reactive Streams KTX به شما امکان می‌دهد یک جریان LiveData قابل مشاهده از یک ناشر ReactiveStreams ایجاد کنید.

برای افزودن این ماژول، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

شیار

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

کاتلین

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

به عنوان مثال، یک پایگاه داده با لیست کوچکی از کاربران را فرض کنید. در برنامه خود، پایگاه داده را در حافظه بارگذاری می‌کنید و سپس داده‌های کاربر را در رابط کاربری خود نمایش می‌دهید. برای دستیابی به این هدف، می‌توانید از RxJava استفاده کنید. کامپوننت Room Jetpack می‌تواند لیست کاربران را به عنوان یک 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.8.3"
}

کاتلین

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

در اینجا چند مثال آورده شده است که Room اکنون از کوروتین‌ها استفاده می‌کند. مثال اول از یک تابع suspend برای بازگرداندن لیستی از اشیاء User استفاده می‌کند، در حالی که مثال دوم از Flow کاتلین برای بازگرداندن غیرهمزمان لیست 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 برنامه خود اضافه کنید:

شیار

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

کاتلین

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

در اینجا مثالی از استفاده از افزونه transaction برای انجام تراکنش پایگاه داده آورده شده است:

db.transaction {
    // insert data
}

ویو مدل KTX

کتابخانه ViewModel KTX تابعی به نام viewModelScope() ارائه می‌دهد که اجرای کوروتین‌ها را از ViewModel شما آسان‌تر می‌کند. CoroutineScope به Dispatchers.Main متصل است و با پاک شدن ViewModel به طور خودکار لغو می‌شود. می‌توانید به جای ایجاد یک scope جدید برای هر ViewModel viewModelScope() استفاده کنید.

برای افزودن این ماژول، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

شیار

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

کاتلین

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

به عنوان مثال، تابع viewModelScope() زیر یک کوروتین را اجرا می‌کند که درخواست شبکه را در یک نخ پس‌زمینه ایجاد می‌کند. این کتابخانه تمام تنظیمات و پاکسازی مربوط به scope را مدیریت می‌کند:

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.11.0"
}

کاتلین

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

به جای گسترش Worker ، اکنون می‌توانید CoroutineWorker گسترش دهید که API کمی متفاوت دارد. برای مثال، اگر می‌خواهید یک 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 ، به بخش Threading در 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

برخی از کیت‌های توسعه نرم‌افزار فایربیس برای اندروید، کتابخانه‌های توسعه کاتلین دارند که به شما امکان می‌دهند هنگام استفاده از فایربیس در برنامه خود، کد کاتلین ایدیوماتیک بنویسید. برای اطلاعات بیشتر، به مباحث زیر مراجعه کنید:

پلتفرم نقشه گوگل KTX

افزونه‌های KTX برای SDKهای اندروید پلتفرم نقشه‌های گوگل موجود است که به شما امکان می‌دهد از چندین ویژگی زبان کاتلین مانند توابع افزونه، پارامترهای نامگذاری شده و آرگومان‌های پیش‌فرض، اعلان‌های destructuring و coroutineها استفاده کنید. برای اطلاعات بیشتر، به مباحث زیر مراجعه کنید:

بازی Core KTX

Play Core KTX با افزودن توابع افزونه به SplitInstallManager و AppUpdateManager در کتابخانه Play Core، پشتیبانی از کوروتین‌های کاتلین برای درخواست‌های تک‌مرحله‌ای و Flow برای نظارت بر به‌روزرسانی‌های وضعیت را اضافه می‌کند.

برای افزودن این ماژول، کد زیر را به فایل build.gradle برنامه خود اضافه کنید:

گرووی

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

کاتلین

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 استفاده کنید.

اندروید KTX بخشی از جت‌پک اندروید .

از Android KTX در پروژه خود استفاده کنید

گرووی

کاتلین

ماژول‌های اندروید ایکس

هسته KTX

شیار

کاتلین

مجموعه KTX

شیار

کاتلین

قطعه KTX

شیار

کاتلین

چرخه عمر KTX

شیار

کاتلین

لایودایتا KTX

شیار

کاتلین

ناوبری KTX

شیار

کاتلین

پالت KTX

شیار

کاتلین

جریان‌های واکنشی KTX

شیار

کاتلین

اتاق KTX

شیار

کاتلین

SQLite KTX

شیار

کاتلین

ویو مدل KTX

شیار

کاتلین

مدیر کار KTX

شیار

کاتلین

سایر ماژول‌های KTX

فایربیس KTX

پلتفرم نقشه گوگل KTX

بازی Core KTX

گرووی

کاتلین

اطلاعات بیشتر