شروع به کار با کاشی‌ها

کاشی‌ها برای Wear OS نسخه ۲.۵ ۳

---

برای شروع ارائه کاشی از برنامه‌تان، وابستگی‌های زیر را در فایل build.gradle برنامه‌تان اضافه کنید.

شیار

dependencies {
    // Use to implement support for wear tiles
    implementation "androidx.wear.tiles:tiles:1.6.2"

    // Use to utilize standard components and layouts in your tiles
    implementation "androidx.wear.protolayout:protolayout:1.4.2"

    // Use to utilize components and layouts with Material Design in your tiles
    implementation "androidx.wear.protolayout:protolayout-material:1.4.2"

    // Use to include dynamic expressions in your tiles
    implementation "androidx.wear.protolayout:protolayout-expression:1.4.2"

    // Use to preview wear tiles in your own app
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2"

    // Use to fetch tiles from a tile provider in your tests
    testImplementation "androidx.wear.tiles:tiles-testing:1.6.2"
}

کاتلین

dependencies {
    // Use to implement support for wear tiles
    implementation("androidx.wear.tiles:tiles:1.6.2")

    // Use to utilize standard components and layouts in your tiles
    implementation("androidx.wear.protolayout:protolayout:1.4.2")

    // Use to utilize components and layouts with Material Design in your tiles
    implementation("androidx.wear.protolayout:protolayout-material:1.4.2")

    // Use to include dynamic expressions in your tiles
    implementation("androidx.wear.protolayout:protolayout-expression:1.4.2")

    // Use to preview wear tiles in your own app
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2")

    // Use to fetch tiles from a tile provider in your tests
    testImplementation("androidx.wear.tiles:tiles-testing:1.6.2")
}

،

شیار

dependencies {
    // Use to implement support for wear tiles
    implementation "androidx.wear.tiles:tiles:1.6.2"

    // Use to utilize standard components and layouts in your tiles
    implementation "androidx.wear.protolayout:protolayout:1.4.2"

    // Use to utilize components and layouts with Material Design in your tiles
    implementation "androidx.wear.protolayout:protolayout-material:1.4.2"

    // Use to include dynamic expressions in your tiles
    implementation "androidx.wear.protolayout:protolayout-expression:1.4.2"

    // Use to preview wear tiles in your own app
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.6.2"

    // Use to fetch tiles from a tile provider in your tests
    testImplementation "androidx.wear.tiles:tiles-testing:1.6.2"
}

کاتلین

dependencies {
    // Use to implement support for wear tiles
    implementation("androidx.wear.tiles:tiles:1.6.2")

    // Use to utilize standard components and layouts in your tiles
    implementation("androidx.wear.protolayout:protolayout:1.4.2")

    // Use to utilize components and layouts with Material Design in your tiles
    implementation("androidx.wear.protolayout:protolayout-material:1.4.2")

    // Use to include dynamic expressions in your tiles
    implementation("androidx.wear.protolayout:protolayout-expression:1.4.2")

    // Use to preview wear tiles in your own app
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.6.2")

    // Use to fetch tiles from a tile provider in your tests
    testImplementation("androidx.wear.tiles:tiles-testing:1.6.2")
}

مهم: هنگام ساختن کاشی‌های Material 3، همیشه Material3TileService را به‌جای کلاس پایه TileService یا SuspendingTileService Horologist گسترش دهید. Material3TileService یک میانای برنامه‌سازی کاربردی Kotlin-first با پشتیبانی از کوروتین داخلی، MaterialScope زمینه‌سازی خودکار، و مدیریت منابع تک‌فراخوانی ارائه می‌دهد.

مفاهیم اصلی

کاشی‌ها مانند برنامه‌های Android ساخته نمی‌شوند و از مفاهیم متفاوتی استفاده می‌کنند:

• الگوهای چیدمان: ترتیب کلی عناصر دیداری را در نمایشگر تعریف کنید. این کار با تابع primaryLayout() انجام می‌شود.
• عناصر چیدمان: نشان‌دهنده یک عنصر گرافیکی مجزا، مانند دکمه یا کارت، یا چندین عنصر ازاین‌قبیل است که بااستفاده از ستون، buttonGroup یا موارد مشابه گروه‌بندی شده‌اند. این‌ها در یک الگوی چیدمان جاسازی شده‌اند.

• منابع: اشیای ResourceBuilders.Resources شامل نقشه‌ای از جفت‌های کلید-مقدار منابع Android (تصاویر) است که برای بازپرداخت چیدمان و نسخه لازم است.
• خط زمان: شیء TimelineBuilders.Timeline فهرستی از یک یا چند نمونه از شیء چیدمان است. می‌توانید سازوکارها و عبارت‌های مختلفی را برای نشان دادن زمان تغییر شیء چیدمان توسط پردازنده ارائه دهید، مثلاً برای توقف نمایش چیدمان در زمانی خاص.
• وضعیت: ساختار داده‌ای از نوع StateBuilders.State که بین کاشی و برنامه منتقل می‌شود تا این دو مؤلفه بتوانند با یکدیگر ارتباط برقرار کنند. برای مثال، اگر روی دکمه‌ای در کاشی تک‌ضرب زده شود، وضعیت شناسه دکمه را نگه می‌دارد. همچنین می‌توانید انواع داده‌ها را بااستفاده از نقشه مبادله کنید.
• کاشی: شیء TileBuilders.Tile که نشان‌دهنده کاشی است و شامل خط زمان، شناسه نسخه منابع، فاصله زمانی تازگی، و وضعیت است.
• Protolayout: این اصطلاح در نام کلاس‌های مختلف مرتبط با کاشی‌ها ظاهر می‌شود و به کتابخانه Wear OS Protolayout اشاره دارد، یک کتابخانه گرافیکی که در سطوح مختلف Wear OS استفاده می‌شود.

ایجاد کاشی

استفاده از Material3TileService (توصیه می‌شود)

هنگام ساختن کاشی‌های Material 3 (androidx.wear.tiles:tiles:1.6.0 و بالاتر)، همیشه Material3TileService را به‌جای کلاس سطح پایین‌تر TileService گسترش دهید. Material3TileService معماری Kotlin-first و مبتنی بر نظر ارائه می‌دهد که توسعه کاشی را ساده می‌کند:

• روال‌های مشترک Kotlin داخلی: یک تابع تعلیق MaterialScope.tileResponse(requestParams: TileRequest): Tile واحد را به‌جای استفاده از ListenableFuture و لغو کردن onTileRequest() پیاده‌سازی کنید.
• MaterialScope ازپیش پیکربندی‌شده: tileResponse() با MaterialScope به‌عنوان گیرنده آن اجرا می‌شود (ازطریق پارامترهای سازنده مانند allowDynamicTheme و defaultColorScheme پیکربندی شده است)، بنابراین نیازی نیست چیدمانتان را در فراخوانی materialScope() زائد قرار دهید.
• ثبت منبع تک‌فراخوانی: شامل ProtoLayoutScope برای ثبت خودکار منابع تصویر درون‌خطی و برگرداندن طرح‌بندی کاشی و منابع در یک فراخوانی اتصال‌دهنده سیستم واحد است. چون Material3TileService منابع را به‌طور خودکار مدیریت می‌کند (final onTileResourcesRequest())، onTileResourcesRequest() را لغو نکنید.

class MyTileService : Material3TileService() {

    override suspend fun MaterialScope.tileResponse(requestParams: TileRequest): Tile =
        tile(
            timeline =
            Timeline.fromLayoutElement(
                primaryLayout(
                    mainSlot = {
                        text("Hello, World!".layoutString, typography = BODY_LARGE)
                    }
                )
            )
        )
}
Tile.kt

معماری TileService زیربنایی

Material3TileService بر روی کلاس پایه TileService ساخته می‌شود، که مثال‌های باقی‌مانده در این راهنما از آن برای نشان دادن مفاهیم سطح پایین استفاده می‌کنند.

برای ارائه کاشی از برنامه‌تان، سرویسی از نوع TileService را پیاده‌سازی کنید و آن را در مانیفست خود ثبت کنید. از این طریق، سیستم کاشی‌های لازم را درطول تماس با onTileRequest() و منابع لازم را درطول تماس با onTileResourcesRequest() درخواست می‌کند.

class MyTileService : TileService() {

    override fun onTileRequest(requestParams: RequestBuilders.TileRequest) =
        Futures.immediateFuture(
            Tile.Builder()
                .setResourcesVersion(RESOURCES_VERSION)
                .setTileTimeline(
                    Timeline.fromLayoutElement(
                        materialScope(this, requestParams.deviceConfiguration) {
                            primaryLayout(
                                mainSlot = {
                                    text("Hello, World!".layoutString, typography = BODY_LARGE)
                                }
                            )
                        }
                    )
                )
                .build()
        )

    override fun onTileResourcesRequest(requestParams: ResourcesRequest) =
        Futures.immediateFuture(Resources.Builder().setVersion(RESOURCES_VERSION).build())
}
Tile.kt

مهم: TileService یک خدمات محدودکننده است. اگر هرکدام از روش‌های چرخه حیات خدمات محدودکننده را لغو می‌کنید، مراقب باشید از تعاملات ناخواسته با روش‌های چرخه حیات مختص TileService که در رشته ناهمگام جداگانه‌ای فراخوانی می‌شوند اجتناب کنید.

سپس، سرویسی را در برچسب <application> فایل AndroidManifest.xml خود اضافه کنید.

<service
    android:name=".snippets.m3.tile.MyTileService"
    android:label="@string/tile_label"
    android:description="@string/tile_description"
    android:icon="@mipmap/ic_launcher"
    android:exported="true"
    android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER">
    <intent-filter>
        <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" />
    </intent-filter>

    <meta-data android:name="androidx.wear.tiles.PREVIEW"
        android:resource="@drawable/tile_preview" />
</service>
AndroidManifest.xml

اجازه و فیلتر قصد این سرویس را به‌عنوان ارائه‌دهنده کاشی ثبت می‌کنند.

وقتی کاربر کاشی‌ها را در تلفن یا ساعت خود پیکربندی می‌کند، نماد، برچسب، شرح، و منبع پیش‌نمایش به او نشان داده می‌شود. توجه داشته باشید که منبع پیش‌نمایش از همه توصیف‌گرهای منبع استاندارد Android پشتیبانی می‌کند، بنابراین امکان تغییر پیش‌نمایش براساس عواملی مانند اندازه صفحه‌نمایش و زبان دستگاه وجود دارد. برای توصیه‌های بیشتر، بازبینه پیش‌نمایش را ببینید.

برنامه‌تان را مستقر کنید و «کاشی» را به «گردونه کاشی‌ها» اضافه کنید (روش توسعه‌پسندتری هم برای پیش‌دیدن «کاشی» وجود دارد، اما فعلاً این کار را به‌صورت دستی انجام دهید).

شکل ۱. کاشی «سلام دنیا».

برای مشاهده نمونه کامل، نمونه کد در GitHub یا codelab را ببینید.

ایجاد میانای کاربر برای کاشی‌ها

عناصر میانای کاربر «بیانگر» Material 3 بااستفاده از رویکردی ساختاریافته که با الگوی سازنده ایمن تایپی Kotlin پشتیبانی می‌شود ایجاد می‌شوند.

توجه: این راهنما از مخفف «M3» برای اشاره به اصطلاحات قابل‌تعویض «Material 3»،‏ «Material Design 3»، و «Material You» استفاده می‌کند. از مخفف «M2.5» برای اشاره به اصطلاحات قابل‌تعویض «Material 2.5» و «Material Design 2.5» استفاده می‌شود.

چیدمان

برای راهنمایی درباره اصول طراحی پشت ایجاد چیدمان‌های کاشی مؤثر و واکنش‌گرا، به چیدمان‌های رایج برای کاشی‌ها مراجعه کنید.

برای ایجاد چیدمان، کارهای زیر را انجام دهید:

1. راه‌اندازی محدوده «طراحی مواد»: تابع materialScope() را فراخوانی کنید و context و deviceConfiguration لازم را ارائه دهید. می‌توانید پارامترهای اختیاری مثل allowDynamicTheme و defaultColorScheme را اضافه کنید. ‫allowDynamicTheme به‌طور پیش‌فرض true است و defaultColorScheme نشان‌دهنده ColorScheme استفاده‌شده در زمانی است که رنگ‌های پویا دردسترس نیستند—مثلاً وقتی کاربر ویژگی را خاموش کرده است—یا وقتی دستگاه از آن پشتیبانی نمی‌کند، یا allowDynamicTheme false است). هنگام استفاده از میاناهای برنامه‌سازی کاربردی ImageResource مثل backgroundImage() در TileService سفارشی، به‌جای آن materialScopeWithResources() را فراخوانی کنید.

2. میانای کاربر را در محدوده بسازید: همه مؤلفه‌های میانای کاربر برای چیدمان «کاشی» معین باید در لامبدای یک فراخوانی materialScope() سطح بالا تعریف شوند. این توابع مؤلفه، مانند primaryLayout() و textEdgeButton()، توابع افزونه در MaterialScope هستند و فقط هنگامی دردسترس هستند که در این محدوده گیرنده فراخوانی شوند.

   materialScope(
       context = context,
       deviceConfiguration =
       requestParams.deviceConfiguration, // requestParams is passed to onTileRequest
       defaultColorScheme = myFallbackColorScheme
   ) {
       // inside the MaterialScope, you can call functions like primaryLayout()
       primaryLayout(
           titleSlot = { text(text = "Title".layoutString) },
           mainSlot = { text(text = "Main Content".layoutString) },
           bottomSlot = {
               textEdgeButton(
                   labelContent = { text("Action".layoutString) },
                   onClick = clickable()
               )
           }
       )
   }
   GetStarted.kt

ماشین سکه‌ای

در M3، چیدمان کاشی‌ها از رویکردی الهام‌گرفته از Compose استفاده می‌کند که از سه جایگاه متمایز بهره می‌برد. این دکمه‌ها از بالا به پایین عبارت‌اند از:

1. titleSlot، معمولاً برای عنوان اصلی یا سرصفحه.
2. mainSlot، برای محتوای اصلی.
3. bottomSlot، اغلب برای کنش‌ها یا اطلاعات تکمیلی استفاده می‌شود. اینجا همچنین جایی است که دکمه لبه ظاهر می‌شود.

شکل ۲. titleSlot،‏ mainSlot، و bottomSlot.

محتوای هر جایگاه به‌شرح زیر است:

• titleSlot (اختیاری): معمولاً چند کلمه که توسط text() تولید شده است.
• mainSlot (اجباری): مؤلفه‌هایی که در ساختارهایی مثل ردیف‌ها، ستون‌ها، و گروه‌های دکمه سازمان‌دهی شده‌اند. این مؤلفه‌ها را می‌توان به‌صورت بازگشتی در یکدیگر جاسازی کرد؛ برای مثال، یک ستون می‌تواند حاوی ردیف باشد.
• bottomSlot (اختیاری): معمولاً با دکمه چسبیده به لبه یا برچسب نوشتاری پر می‌شود.

چون کاشی‌ها پیمایش‌شدنی نیستند، مؤلفه‌ای برای صفحه‌بندی، پیمایش، یا مدیریت فهرست‌های طولانی محتوا وجود ندارد. دقت کنید که وقتی اندازه قلم افزایش می‌یابد یا نوشتار به‌دلیل ترجمه طولانی‌تر می‌شود، محتوا همچنان نمایان بماند.

عناصر میانای کاربر

کتابخانه protolayout-material3 تعداد زیادی مؤلفه ارائه می‌دهد که طبق مشخصات Material 3 Expressive و توصیه‌های میانای کاربر طراحی شده‌اند.

دکمه‌ها

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

• textButton(): دکمه‌ای با یک جایگاه برای محتوای نوشتاری (کوتاه)
• iconButton()‎: دکمه‌ای با یک جایگاه برای نمایش نماد
• avatarButton(): دکمه چهرک قرصی‌شکل که حداکثر سه جایگاه برای قرار دادن محتوا ارائه می‌دهد که نشان‌دهنده برچسب و برچسب ثانویه به‌صورت عمودی روی‌هم چیده شده و یک تصویر (چهرک) در کنار آن است
• imageButton()‎: دکمه تصویر کلیک‌کردنی که جایگاه‌های اضافی ارائه نمی‌دهد، فقط تصویر (برای مثال backgroundImage به‌عنوان پس‌زمینه)
• compactButton()‎: دکمه فشرده‌ای که حداکثر دو جایگاه برای محتوای پشته‌ای افقی ارائه می‌دهد که نماد و نوشتار کنار آن را نشان می‌دهد
• button(): دکمه قرصی‌شکل که حداکثر سه جایگاه برای محتوای نشان‌دهنده برچسب و برچسب ثانویه که به‌صورت عمودی روی هم قرار گرفته‌اند و نمادی در کنار آن ارائه می‌دهد

دکمه‌های لبه

دکمه لبه دکمه‌ای تخصصی و تمام‌عرض است که در پایین صفحه گرد ساعت لنگر انداخته است و مهم‌ترین کنشی را که باید از صفحه کاشی فعلی انجام شود نشان می‌دهد.

• iconEdgeButton()‎: دکمه لبه‌ای که یک جایگاه برای قرار دادن نماد یا محتوای کوچک و گرد مشابه ارائه می‌دهد
• textEdgeButton()‎: دکمه لبه‌ای که یک جایگاه برای قرار دادن نوشتار یا محتوای طولانی و عریض مشابه ارائه می‌دهد

کارت‌ها

کارت‌ها عمدتاً اطلاعات‌محور هستند. این کارت‌ها مجموعه‌هایی از داده‌های ساختاریافته مرتبط را نمایش می‌دهند. درحالی‌که می‌توانید کارت‌های تعاملی ایجاد کنید، آن‌ها معمولاً خلاصه‌ای از اطلاعات را نشان می‌دهند که کاربر می‌تواند با تک‌ضرب زدن روی آن جزئیات بیشتری را ببیند یا کنش مرتبطی را انجام دهد.

• titleCard()‎: کارت عنوان که یک تا سه جایگاه ارائه می‌دهد، معمولاً مبتنی بر نوشتار است
• appCard()‎: کارت برنامه که حداکثر پنج جایگاه ارائه می‌دهد، معمولاً مبتنی بر نوشتار است
• textDataCard(): کارت داده‌ای که حداکثر سه جایگاه عمودی روی‌هم چیده شده ارائه می‌دهد، معمولاً مبتنی بر نوشتار یا عدد
• iconDataCard()‎: کارت داده‌ای که حداکثر سه جایگاه پشته‌ای عمودی ارائه می‌دهد، معمولاً مبتنی بر نوشتار یا عدد، با یک نماد
• graphicDataCard(): کارت داده گرافیکی که جایگاهی برای داده‌های گرافیکی، مانند نشانگر پیشرفت، و حداکثر دو جایگاه پشته‌ای عمودی، معمولاً برای توضیحات متنی، ارائه می‌دهد.

نشانگرهای پیشرفت

• circularProgressIndicator(): پیشرفت به‌سمت هدف را بااستفاده از عنصر شعاعی نشان می‌دهد
• segmentedCircularProgressIndicator(): پیشرفت به‌سمت یک هدف را بااستفاده از یک عنصر شعاعی با مراحل متمایز نشان می‌دهد

عناصر چیدمان گروه

• buttonGroup(): چیدمان مؤلفه‌ای که فرزندانش را در یک توالی افقی قرار می‌دهد
• primaryLayout()‎: چیدمان تمام‌صفحه که نشان‌دهنده سبک چیدمان پیشنهادی M3 است که واکنش‌گرا است و جای‌گذاری عناصر را به‌همراه حاشیه‌ها و فاصله‌گذاری‌های توصیه‌شده اعمال‌شده مدیریت می‌کند

اعمال کردن زمینه

در Material 3 Expressive، سیستم رنگ با ۲۹ نقش رنگ استاندارد تعریف می‌شود که در شش گروه سازمان‌دهی شده‌اند: اصلی، فرعی، سوم، خطا، سطح، و طرح کلی.

شکل ۳.‏ سیستم رنگ Material 3 Expressive.

ColorScheme هریک از این ۲۹ نقش را به رنگ مربوطه نگاشت می‌کند، و چون بخشی از MaterialScope است و مؤلفه‌ها باید در آن ایجاد شوند، به‌طور خودکار رنگ‌ها را از طرح می‌گیرند. این رویکرد به همه عناصر میانای کاربر اجازه می‌دهد به‌طور خودکار از استانداردهای «طراحی مواد» پیروی کنند.

برای اینکه به کاربران اجازه دهید بین آرایش رنگی که شما تعریف می‌کنید (مثلاً آرایشی که رنگ‌های نمانام شما را منعکس می‌کند) و آرایشی که سیستم ارائه می‌دهد (که یا از صفحه ساعت فعلی کاربر گرفته شده است یا توسط کاربر انتخاب شده است) انتخاب کنند، MaterialScope را به‌صورت زیر مقداردهی اولیه کنید:

val myColorScheme =
    ColorScheme(
        primary = Color.rgb(0, 0, 255).argb, // Blue
        onPrimary = Color.rgb(255, 255, 255).argb, // White
        // 27 more
    )

materialScope(
    context = context,
    deviceConfiguration = requestParams.deviceConfiguration,
    defaultColorScheme = myColorScheme
) {
    // If the user selects "no theme" in settings, myColorScheme is used.
    // Otherwise, the system-provided theme is used.
}
GetStarted.kt

اگر این گزینه را انتخاب کنید، نماد کاشی تک‌رنگ ارائه دهید تا بتوان آن را به‌درستی رنگ‌آمیزی کرد تا در هر زمینه‌ای به‌طور بهینه دیده شود.

برای اینکه کاشی‌هایتان حتماً در آرایش رنگ‌هایی که ارائه می‌دهید نشان داده شوند، پشتیبانی از زمینه‌سازی پویا را با تنظیم allowDynamicTheme روی false غیرفعال کنید:

materialScope(
    context = context,
    deviceConfiguration = requestParams.deviceConfiguration,
    allowDynamicTheme = false,
    defaultColorScheme = myColorScheme
) {
    // myColorScheme is *always* used.
}
GetStarted.kt

رنگ

هر مؤلفه جداگانه از زیرمجموعه‌ای از ۲۹ نقش رنگی تعریف‌شده توسط ColorScheme استفاده می‌کند. برای مثال، دکمه‌ها از حداکثر چهار رنگ استفاده می‌کنند که به‌طور پیش‌فرض از گروه «اصلی» ColorScheme فعال گرفته می‌شود:

کد مؤلفه ButtonColors	نقش ColorScheme
containerColor	اصلی
iconColor	onPrimary
labelColor	onPrimary
secondaryLabelColor	onPrimary (opacity 0.8)

برای راهنمایی دقیق درباره اعمال رنگ در طراحی‌های Wear OS، به راهنمای طراحی رنگ مراجعه کنید.

ممکن است لازم باشد برای عناصر میانای کاربر خاص از نشان‌های رنگ پیش‌فرض منحرف شوید. برای مثال، ممکن است بخواهید یک textEdgeButton از رنگ‌های گروه «ثانویه» یا «ثالث» به‌جای «اولیه» استفاده کند تا برجسته شود و کنتراست بهتری ارائه دهد.

می‌توانید رنگ‌های مؤلفه را به چند روش سفارشی‌سازی کنید:

1. از تابع کمکی برای رنگ‌های ازپیش‌تعریف‌شده استفاده کنید. از توابع کمکی مثل filledTonalButtonColors() برای اعمال سبک‌های دکمه استاندارد برای Material 3 Expressive استفاده کنید. این توابع نمونه‌های ازپیش پیکربندی‌شده ButtonColors ایجاد می‌کنند که سبک‌های رایج مانند توپر، رنگی، یا خطی را به نقش‌های مناسب از ColorScheme فعال در MaterialScope نگاشت می‌کنند. این به شما امکان می‌دهد سبک‌های ثابتی را بدون تعریف دستی هر رنگ برای انواع دکمه‌های رایج اعمال کنید.

   textEdgeButton(
       colors = filledButtonColors(), // default
       /* OR colors = filledTonalButtonColors() */
       /* OR colors = filledVariantButtonColors() */
       // ... other parameters
   )
   GetStarted.kt

   برای کارت‌ها، از خانواده معادل filledCardColors() تابع‌ها استفاده کنید.

   همچنین می‌توانید شیء ButtonColors برگردانده‌شده توسط توابع کمکی را بااستفاده از روش copy() آن‌ها اصلاح کنید، اگر فقط نیاز به تغییر یک یا دو نشان دارید:

   textEdgeButton(
       colors =
       filledButtonColors()
           .copy(
               containerColor = colorScheme.tertiary,
               labelColor = colorScheme.onTertiary
           ),
       // ... other parameters
   )
   GetStarted.kt

2. نقش‌های رنگ جایگزین را به‌طور صریح ارائه دهید. شیء ButtonColors خودتان را ایجاد کنید و آن را به مؤلفه ارسال کنید. برای کارت‌ها، از شیء معادل CardColors استفاده کنید.

   textEdgeButton(
       colors =
       ButtonColors(
           // the materialScope makes colorScheme available
           containerColor = colorScheme.secondary,
           iconColor = colorScheme.secondaryDim,
           labelColor = colorScheme.onSecondary,
           secondaryLabelColor = colorScheme.onSecondary
       ),
       // ... other parameters
   )
   GetStarted.kt

3. رنگ‌های ثابت را مشخص کنید (بااحتیاط استفاده کنید). درحالی‌که به‌طور کلی توصیه می‌شود رنگ‌ها را با نقش معنایی‌شان (مثلاً colorScheme.primary) مشخص کنید، می‌توانید مقادیر رنگ را مستقیماً نیز ارائه دهید. از این رویکرد باید به‌ندرت استفاده شود، زیرا می‌تواند منجر به ناهماهنگی با زمینه کلی شود، به‌ویژه اگر زمینه به‌طور پویا تغییر کند.

   textEdgeButton(
       colors = filledButtonColors().copy(
           containerColor = android.graphics.Color.RED.argb, // Using named colors
           labelColor = 0xFFFFFF00.toInt().argb // Using a hex code for yellow
       ),
       // ... other parameters
   )
   GetStarted.kt

نویسه‌نگاری

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

برای ایجاد هماهنگی بصری در سراسر پلاتفرم Wear OS و بهینه‌سازی عملکرد، همه نوشتارها در کاشی‌ها بااستفاده از قلم ارائه‌شده توسط سیستم پردازش می‌شوند. یعنی کاشی‌ها از طرح حروف سفارشی پشتیبانی نمی‌کنند. در Wear OS 6 و بالاتر، این قلم مختص سازنده اصلی محصول است. در بیشتر موارد، این قلم متغیر خواهد بود و تجربه گویاتر و کنترل دقیق‌تری ارائه می‌دهد.

برای ایجاد سبک نوشتار، معمولاً از روش text() ترکیب‌شده با ثابت‌های تایپوگرافی استفاده می‌کنید. این مؤلفه به شما امکان می‌دهد از نقش‌های ازپیش تعریف‌شده تایپوگرافی در Material 3 Expressive استفاده کنید، که به کاشی شما کمک می‌کند تا از روال‌های مطلوب تایپوگرافی تثبیت‌شده برای خوانایی و سلسله‌مراتب پیروی کند. این کتابخانه مجموعه‌ای از ۱۸ ثابت معنایی طرح حروف ارائه می‌دهد، مانند BODY_MEDIUM. این ثابت‌ها بر محورهای قلم غیر از اندازه نیز تأثیر می‌گذارند.

text(
    text = "Hello, World!".layoutString,
    typography = BODY_MEDIUM,
)
GetStarted.kt

برای کنترل بیشتر، می‌توانید تنظیمات بیشتری ارائه دهید. در Wear OS 6 و نسخه‌های بالاتر، احتمالاً از قلم متغیر استفاده می‌شود که می‌توانید آن را در محورهای ایتالیک، وزن، عرض، و گردی اصلاح کنید. می‌توانید این محورها را بااستفاده از پارامتر settings کنترل کنید:

text(
    text = "Hello, World".layoutString,
    italic = true,

    // Use elements defined in androidx.wear.protolayout.LayoutElementBuilders.FontSetting
    settings =
    listOf(
        weight(500),
        width(100F),
        roundness(100)
    ),
)
GetStarted.kt

درنهایت، اگر لازم است اندازه یا فاصله حروف را کنترل کنید (توصیه نمی‌شود)، به‌جای text()‎ از basicText()‎ استفاده کنید و بااستفاده از fontStyle()‎، مقداری برای ویژگی fontStyle بسازید.

شکل و حاشیه‌ها

می‌توانید شعاع گوشه تقریباً هر مؤلفه‌ای را بااستفاده از ویژگی shape آن تغییر دهید. مقادیر از ویژگی MaterialScope shapes می‌آیند:

textButton(
    height = expand(),
    width = expand(),
    shape = shapes.medium, // OR another value like shapes.full
    colors = filledVariantButtonColors(),
    labelContent = { text("Hello, World!".layoutString) },
)
GetStarted.kt

پس‌از تغییر شکل مؤلفه، اگر فکر می‌کنید که فضای خیلی زیاد یا خیلی کمی در اطراف لبه نمایشگر باقی می‌ماند، حاشیه‌ها را بااستفاده از پارامتر margin از primaryLayout() تنظیم کنید:

primaryLayout(
    mainSlot = {
        textButton(
            shape = shapes.small,
            /* ... */
        )
    },
    // margin constants defined in androidx.wear.protolayout.material3.PrimaryLayoutMargins
    margins = MAX_PRIMARY_LAYOUT_MARGIN,
)
GetStarted.kt

توجه: کاشی‌ها از دگرگونی شکل بین شکل‌های دکمه که برای برنامه‌هایی که از Compose برای Wear OS استفاده می‌کنند دردسترس است پشتیبانی نمی‌کنند. برای مثال، هیچ کاشی‌ای معادل IconToggleButtonShapes وجود ندارد.

کمان‌ها

از فرزندان محتوای Arc زیر پشتیبانی می‌شود:

• ArcLine: خطی منحنی را در اطراف «کمان» رندر می‌کند.
• ‫ArcText: نوشتار منحنی را در «قوس» ارائه می‌کند.
• ArcAdapter: عنصر چیدمان پایه‌ای را در کمان ارائه می‌کند که مماس بر کمان رسم شده است.

توجه: درحالی‌که ArcText نوشتار منحنی را در اطراف «کمان» ترسیم می‌کند، استفاده از Text در ArcAdapter نوشتار خطی را در مماس با کمان ترسیم می‌کند.

برای اطلاعات بیشتر، به اسناد مرجع برای هریک از انواع عنصر مراجعه کنید.

اصلاح‌کننده‌ها

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

• ظاهر دیداری چیدمان را تغییر دهید. برای مثال، پس‌زمینه، حاشیه، یا لایه داخلی به عنصر چیدمانتان اضافه کنید.
• فراداده درباره چیدمان اضافه کنید. برای مثال، یک اصلاح‌کننده معنایی به عنصر چیدمانتان اضافه کنید تا با صفحه‌خوان‌ها استفاده شود.
• عملکرد اضافه کنید. برای مثال، برای تعاملی کردن کاشی، یک اصلاح‌کننده کلیک‌کردنی به عنصر چیدمانتان اضافه کنید. برای اطلاعات بیشتر، به تعامل با کاشی‌ها مراجعه کنید.

برای مثال، می‌توانیم ظاهر و فراداده پیش‌فرض Image را سفارشی‌سازی کنیم، همان‌طور که در نمونه کد زیر نشان داده شده است:

private fun myImage(): LayoutElement =
    Image.Builder()
        .setWidth(dp(24f))
        .setHeight(dp(24f))
        .setResourceId("image_id")
        .setModifiers(
            Modifiers.Builder()
                .setBackground(Background.Builder().setColor(argb(0xFFFF0000.toInt())).build())
                .setPadding(ModifiersBuilders.Padding.Builder().setStart(dp(12f)).build())
                .setSemantics(Semantics.Builder().setContentDescription("Image description").build())
                .build()
        )
        .build()
Tile.kt

Spannables

‫Spannable نوع خاصی از محتوا است که عناصر را مشابه نوشتار چیدمان می‌کند. این کار زمانی مفید است که می‌خواهید سبک متفاوتی را فقط برای یک رشته فرعی در بلوک بزرگ‌تری از نوشتار اعمال کنید، چیزی که با عنصر Text امکان‌پذیر نیست.

محتوی Spannable با Span فرزند پر شده است. فرزندان دیگر یا نمونه‌های تودرتوی Spannable مجاز نیستند.

دو نوع فرزند Span وجود دارد:

• ‫SpanText: نوشتار را با سبک خاصی ارائه می‌کند.
• SpanImage: تصویری را در خط با نوشتار ارائه می‌دهد.

برای مثال، می‌توانید «world» را در کاشی «Hello world» مورب کنید و تصویری را بین کلمات درج کنید، همان‌طور که در نمونه کد زیر نشان داده شده است:

private fun mySpannable(): LayoutElement =
    LayoutElementBuilders.Spannable.Builder()
        .addSpan(SpanText.Builder().setText("Hello ").build())
        .addSpan(SpanImage.Builder().setWidth(dp(24f)).setHeight(dp(24f)).setResourceId("image_id").build())
        .addSpan(
            SpanText.Builder()
                .setText("world")
                .setFontStyle(FontStyle.Builder().setItalic(true).build())
                .build()
        )
        .build()
Tile.kt

کار با منابع

مهم: هنگام استفاده از Material3TileService، منابع به‌طور خودکار ازطریق ProtoLayoutScope داخلی آن ثبت می‌شوند، وقتی‌که ImageResource (مانند imageResource(androidImageResource(R.drawable.icon))) را مستقیماً به مؤلفه‌های Material 3 مانند icon() یا backgroundImage() ارسال می‌کنید. onTileResourcesRequest() در Material3TileService ملغی نشود.

کاشی‌ها به هیچ‌یک از منابع برنامه‌تان دسترسی ندارند. این یعنی نمی‌توانید شناسه تصویر Android را به عنصر چیدمان Image ارسال کنید و انتظار داشته باشید که حل شود. درعوض، روش onTileResourcesRequest() را لغو کنید و هر منبعی را به‌صورت دستی ارائه دهید.

دو روش برای ارائه تصاویر در روش onTileResourcesRequest() وجود دارد:

• بااستفاده از setAndroidResourceByResId()، منبع ترسیم‌شدنی ارائه دهید.
• تصویری پویا به‌عنوان ByteArray بااستفاده از setInlineResource() ارائه کنید.

override fun onTileResourcesRequest(
    requestParams: ResourcesRequest
) = Futures.immediateFuture(
    Resources.Builder()
        .setVersion("1")
        .addIdToImageMapping(
            "image_from_resource",
            ResourceBuilders.ImageResource.Builder()
                .setAndroidResourceByResId(
                    ResourceBuilders.AndroidImageResourceByResId.Builder()
                        .setResourceId(R.drawable.ic_walk)
                        .build()
                ).build()
        )
        .addIdToImageMapping(
            "image_inline",
            ResourceBuilders.ImageResource.Builder()
                .setInlineResource(
                    ResourceBuilders.InlineImageResource.Builder()
                        .setData(imageAsByteArray)
                        .setWidthPx(48)
                        .setHeightPx(48)
                        .setFormat(ResourceBuilders.IMAGE_FORMAT_RGB_565)
                        .build()
                ).build()
        ).build()
)
Tile.kt

بازبینه تصویر پیش‌نمایش کاشی

سیستم تصویر پیش‌نمایش کاشی را که در مانیفست برنامه Android به آن ارجاع داده شده است، در ویرایشگر گردونه کاشی برای افزودن کاشی جدید نمایش می‌دهد. این ویرایشگر هم در دستگاه‌های Wear OS و هم در برنامه همراه ساعت در تلفن‌ها نشان داده می‌شود.

برای کمک به کاربران در استفاده حداکثری از این تصویر پیش‌نمایش، جزئیات زیر را درباره کاشی‌تان به‌تأیید برسانید:

• جدیدترین طراحی را نشان می‌دهد. پیش‌نمایش باید جدیدترین طراحی کاشی شما را به‌طور دقیق نشان دهد.
• از ابعاد توصیه‌شده استفاده می‌کند. برای ارائه بهترین کیفیت نمایش ممکن و تجربه کاربری خوب، تصویر پیش‌نمایش باید ابعاد ۴۰۰ پیکسل در ۴۰۰ پیکسل داشته باشد.
• از زمینه رنگ ثابت استفاده می‌کند. از زمینه رنگ ثابت کاشی استفاده کنید، نه زمینه پویا.
• شامل نماد برنامه. تأیید کنید که نماد برنامه‌تان در بالای تصویر پیش‌نمایش نشان داده می‌شود.
• وضعیت بارشده/واردشده به سیستم را نشان می‌دهد. پیش‌نمایش باید وضعیت «بارشده» یا «واردشده به سیستم» کاملاً کاربردی را نمایش دهد و از هرگونه محتوای خالی یا جای‌بان اجتناب کند.
• از قوانین حل‌وفصل منابع برای سفارشی‌سازی استفاده کنید (اختیاری). برای ارائه پیش‌نمایش‌هایی که با اندازه نمایشگر، زبان، یا تنظیمات منطقه دستگاه مطابقت داشته باشند، استفاده از قوانین وضوح منابع Android را مدنظر قرار دهید. این کار به‌ویژه زمانی مفید است که ظاهر کاشی شما در دستگاه‌های مختلف متفاوت باشد.