استفاده از Jetpack Compose در Wear OS

نسخه Compose for Wear OS Material ۲.۵ ۳

---

شکل ۱. Jetpack Compose ویژه Wear OS

Compose برای Wear OS شبیه به Compose برای تلفن همراه است. بااین‌حال، چند تفاوت کلیدی وجود دارد. این راهنما شما را با شباهت‌ها و تفاوت‌ها آشنا می‌کند.

Compose for Wear OS بخشی از Android Jetpack است و مانند سایر کتابخانه‌های Wear Jetpack که استفاده می‌کنید، به شما کمک می‌کند کد بهتری را سریع‌تر بنویسید. این رویکرد توصیه‌شده ما برای ساختن میانای کاربر برای برنامه‌های Wear OS است.

اگر با استفاده از جعبه‌ابزار Jetpack Compose آشنا نیستید، مسیر Compose را بررسی کنید. بسیاری از اصول توسعه برای Compose تلفن همراه برای Compose ویژه Wear OS نیز اعمال می‌شود. برای اطلاعات بیشتر درباره مزایای کلی چارچوب واسط کاربر اعلانی، چرا Compose را ببینید. برای کسب اطلاعات بیشتر درباره Compose for Wear OS، به Compose for Wear OS Pathway و مخزن نمونه‌های Wear OS در GitHub مراجعه کنید.

مهارت‌های Android

مشاهده در GitHub

Wear Compose Material 3

از مهارت Android برای کمک به ساختن بااستفاده از Jetpack Compose در Wear OS، ازجمله انتقال از نسخه‌های قبلی Material به Material3، استفاده کنید.

برای نصب مهارت از Android CLI، این دستور را اجرا کنید:

android skills add wear-compose-m3

طراحی سه‌بعدی در Jetpack Compose در Wear OS

Jetpack Compose در Wear OS پیاده‌سازی Material 3 را ارائه می‌دهد که به شما کمک می‌کند برنامه‌های جذاب‌تری طراحی کنید تجربه‌ها. مؤلفه‌های طراحی مواد در Wear OS براساس موضوع‌دهی Wear Material ساخته شده‌اند. این زمینه‌سازی روشی نظام‌مند برای سفارشی‌سازی «طراحی مواد» و بازتاب بهتر نمانام محصول شما است.

سازگاری

Compose for Wear OS در ساعت‌هایی که از Wear OS 3.0 (سطح ای‌پی‌آی ۳۰) پشتیبانی می‌کنند و ساعت‌هایی که از Wear OS 2.0 (سطح ای‌پی‌آی ۲۵ و بالاتر) استفاده می‌کنند کار می‌کند. استفاده از نسخه ۱.۵ Compose برای Wear OS مستلزم استفاده از نسخه ۱.۸ کتابخانه‌های androidx.compose و Kotlin 1.9.0 است. می‌توانید از نگاشت BOM و نقشه سازگاری Compose با Kotlin برای بررسی سازگاری Compose استفاده کنید.

سطوح

‫Compose for Wear OS ساختن برنامه‌ها را در Wear OS آسان‌تر می‌کند. برای اطلاعات بیشتر، برنامه‌ها را ببینید. از مؤلفه‌های داخلی ما برای ایجاد تجربه‌های کاربری مطابق با دستورالعمل‌های Wear OS استفاده کنید. برای اطلاعات بیشتر درباره مؤلفه‌ها، راهنمای طراحی ما را ببینید.

درحال راه‌اندازی

استفاده از Jetpack Compose با Wear OS مشابه استفاده از Jetpack Compose برای هر پروژه Android دیگری است. تفاوت اصلی این است که Jetpack Compose برای Wear کتابخانه‌های مختص Wear را اضافه می‌کند که ایجاد میاناهای کاربر سفارشی‌شده برای ساعت‌ها را آسان‌تر می‌کند. در برخی موارد، این مؤلفه‌ها نامی مشابه با همتایان غیرپوشیدنی خود دارند، مانند androidx.wear.compose.material3.Button و androidx.compose.material3.Button.

ایجاد برنامه جدید در «استودیو Android»

برای ایجاد پروژه جدیدی که شامل Jetpack Compose باشد، به‌صورت زیر عمل کنید:

1. اگر در پنجره به «استودیو Android» خوش آمدید هستید، روی شروع پروژه جدید «استودیو Android» کلیک کنید. اگر ازقبل پروژه «استودیو Android» را باز کرده‌اید، فایل > جدید > وارد کردن نمونه را از نوار منو انتخاب کنید.
2. Compose for Wear را جستجو کنید و Compose for Wear OS Starter را انتخاب کنید.
3. در پنجره پیکربندی پروژه، کارهای زیر را انجام دهید:
   1. نام برنامه را تنظیم کنید.
   2. مکان پروژه را برای نمونه‌تان انتخاب کنید.
4. روی پایان کلیک کنید.
5. بررسی کنید که فایل build.gradle پروژه به‌درستی پیکربندی شده باشد، همان‌طور که در فایل‌های ویژگی‌های Gradle شرح داده شده است.

اکنون آماده‌اید تا توسعه برنامه را بااستفاده از Compose برای Wear OS شروع کنید.

وابستگی‌های جعبه‌ابزار Jetpack Compose

برای استفاده از Jetpack Compose با Wear OS، باید وابستگی‌های جعبه‌ابزار Jetpack Compose را در فایل build.gradle برنامه‌تان اضافه کنید. بیشتر تغییرات وابستگی مربوط به Wear OS در لایه‌های معماری بالایی قرار دارند که در تصویر زیر با کادر قرمز احاطه شده‌اند.

شکل ۲. تغییرات وابستگی برای Wear OS در معماری Compose

این یعنی بسیاری از وابستگی‌هایی که قبلاً با Jetpack Compose استفاده می‌کردید، هنگام هدف‌یابی Wear OS تغییر نمی‌کنند. برای مثال، واسط کاربر، زمان اجرا، کامپایلر، و وابستگی‌های پویانمایی یکسان باقی می‌مانند.

بااین‌حال، Wear OS نسخه‌های خاص خود را از کتابخانه‌های material و material3، foundation، و navigation دارد، بنابراین مطمئن شوید که از کتابخانه‌های مناسب استفاده می‌کنید.

درصورت امکان، از نسخه WearComposeMaterial میاناهای برنامه‌سازی کاربردی استفاده کنید. هرچند ازنظر فنی امکان استفاده از نسخه تلفن همراه Compose Material وجود دارد، اما این نسخه برای الزامات منحصربه‌فرد Wear OS بهینه‌سازی نشده است. علاوه‌براین، ترکیب Compose Material با Compose Material برای Wear OS می‌تواند منجر به رفتار غیرمنتظره شود. برای مثال، چون هر کتابخانه کلاس MaterialTheme خودش را دارد، اگر از هر دو نسخه استفاده شود، ممکن است رنگ‌ها، تایپوگرافی، یا شکل‌ها ناهماهنگ باشند.

جدول زیر تفاوت‌های وابستگی بین Wear OS و تلفن همراه را نشان می‌دهد:

وابستگی Wear OS (androidx.wear.*)	مقایسه	وابستگی تلفن همراه (androidx.*)
androidx.wear.compose:compose-material3	به‌جای	androidx.compose.material:material3
androidx.wear.compose:compose-navigation	به‌جای	androidx.navigation:navigation-compose
androidx.wear.compose:compose-foundation	علاوه‌بر	androidx.compose.foundation:foundation

توجه: می‌توان از سایر وابستگی‌های غیرموبایلی Material، مانند Material Ripple و Material Icons Extended، استفاده کرد.

قطعه کد زیر نمونه‌ای از فایل build.gradle را نشان می‌دهد که شامل این وابستگی‌ها است:

کاتلین

dependencies {

    val composeBom = platform("androidx.compose:compose-bom:2026.09.00")

    // General compose dependencies
    implementation(composeBom)
    implementation("androidx.activity:activity-compose:1.13.0")
    implementation("androidx.compose.ui:ui-tooling-preview:1.12.1")
    // Other compose dependencies

    // Compose for Wear OS dependencies
    implementation("androidx.wear.compose:compose-material3:1.7.1")

    // Foundation is additive, so you can use the mobile version in your Wear OS app.
    implementation("androidx.wear.compose:compose-foundation:1.7.1")

    // Wear OS preview annotations
    implementation("androidx.wear.compose:compose-ui-tooling:1.7.1")

    // If you are using Compose Navigation, use the Wear OS version (NOT THE MOBILE VERSION).
    // Uncomment the line below and update the version number.
    // implementation("androidx.wear.compose:compose-navigation:1.7.1")

    // Testing
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.1.3")
    androidTestImplementation("androidx.test.espresso:espresso-core:3.4.0")
    androidTestImplementation("androidx.compose.ui:ui-test-junit4:1.0.3")
    debugImplementation("androidx.compose.ui:ui-tooling:1.4.1")

}

بازخورد

Compose برای Wear OS را امتحان کنید و از ردیاب مشکل برای ارائه پیشنهاد و بازخورد استفاده کنید.

به کانال compose-wear# در Kotlin Slack بپیوندید تا با انجمن توسعه‌دهندگان ارتباط برقرار کنید و تجربه‌تان را به ما اطلاع دهید.