‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

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

قطعه‌های 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")
}

مفاهیم اصلی

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

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

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

ایجاد کاشی

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

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

روال‌های مشترک Kotlin داخلی: به‌جای استفاده از ListenableFuture و ملغی کردن onTileRequest()، یک تابع تعلیق‌کننده MaterialScope.tileResponse(requestParams: TileRequest): Tile پیاده‌سازی کنید.
ازپیش پیکربندی‌شده 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

سپس، سرویسی را به برچسب <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 پشتیبانی می‌کند، بنابراین می‌توان پیش‌نمایش را براساس عواملی مثل اندازه صفحه‌نمایش و زبان دستگاه تغییر داد. برای توصیه‌های بیشتر، فهرست وارسی پیش‌نمایش را ببینید.

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

کاشی Wear OS که با Material 3 ساخته شده است و نوشتار «سلام دنیا» را نمایش می‌دهد. — **شکل ۱.** کاشی «سلام دنیا».

برای دیدن نمونه کامل، نمونه کد در GitHub یا کدآزمایی را ببینید.

ایجاد کردن واسط کاربر برای کاشی‌ها

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

چیدمان

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

برای ایجاد چیدمان خود، مراحل زیر را انجام دهید:

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

ساختن واسط کاربر در محدوده: همه عناصر واسط کاربر برای چیدمان کاشی معین باید در لامبدای یک فراخوانی 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، چیدمان کاشی‌ها از رویکردی الهام‌گرفته از «نوشتن» استفاده می‌کند که از سه جایگاه متمایز استفاده می‌کند. از بالا به پایین، این موارد عبارت‌اند از:

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

چیدمان کاشی‌وار که titleSlot،‏ mainSlot، و bottomSlot را نشان می‌دهد — **شکل ۲.** titleSlot،‏ mainSlot، و bottomSlot.

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

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

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

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

کتابخانه protolayout-material3 تعداد زیادی عنصر ارائه می‌دهد که براساس مشخصات «بیانگر Material 3» و توصیه‌های واسط کاربر طراحی شده‌اند.

دکمه‌ها

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

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

دکمه‌های لبه

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

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

کارت‌ها

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

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

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

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

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

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

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

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

«سیستم رنگ بیانی Material 3» که نقش‌های رنگ را در گروه‌هایی مثل اصلی، ثانویه، ثالثه، خطا، سطح، و طرح کلی نشان می‌دهد. — **شکل ۳.** «سیستم رنگ 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	در Primary
labelColor	در Primary
secondaryLabelColor	onPrimary (ماتی ۰٫۸)

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

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

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

از تابع کمکی برای رنگ‌های ازپیش‌تعریف‌شده استفاده کنید. از توابع کمکی مثل 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
```

نقش‌های رنگ جایگزین را به‌طور صریح ارائه دهید. شیء 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

رنگ‌های ثابت را مشخص کنید (بااحتیاط استفاده کنید). اگرچه به‌طورکلی توصیه می‌شود رنگ‌ها را براساس نقش معنایی‌شان مشخص کنید (برای نمونه، 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» استفاده کنید که به کاشی شما کمک می‌کند از روال‌های مطلوب حروف‌چینی برای خوانایی و سلسله‌مراتب پیروی کند. کتابخانه مجموعه‌ای از ۱۸ ثابت طرح حروف معنایی، مانند 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

وجود ندارد.

کمان‌ها

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

ArcLine: خطی منحنی را در اطراف «قوس» رندر می‌کند.
ArcText: نوشتار منحنی را در «قوس» ارائه می‌کند.
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: تصویر را به‌صورت درون‌خطی با نوشتار پرداز می‌کند.

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

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

کار با منابع

کاشی‌ها به هیچ‌یک از منابع برنامه‌تان دسترسی ندارند. این یعنی نمی‌توانید شناسه تصویر 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 استفاده کنید. این کار به‌ویژه اگر ظاهر کاشی شما در دستگاه‌های مختلف متفاوت باشد مفید است.

شروع به کار با کاشی‌ها با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

شیار

کاتلین

شیار

کاتلین

مفاهیم اصلی

ایجاد کاشی

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

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

ایجاد کردن واسط کاربر برای کاشی‌ها

چیدمان

ماشین سکه‌ای

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

دکمه‌ها

دکمه‌های لبه

کارت‌ها

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

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

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

رنگ

نویسه‌نگاری

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

کمان‌ها

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

Spannables

کار با منابع

فهرست وارسی تصویر پیش‌نمایش کاشی

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

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

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