تستخدم 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"
}

Kotlin

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().
عناصر التنسيق: تمثّل عنصرًا رسوميًا فرديًا، مثل زر أو بطاقة، أو عدة عناصر من هذا النوع مجمّعة معًا باستخدام عمود أو buttonGroup أو ما شابه. ويتم تضمينها في نموذج تنسيق.

الموارد: تتكوّن عناصر ResourceBuilders.Resources من خريطة لأزواج المفتاح والقيمة لموارد Android (الصور) المطلوبة لعرض تنسيق وإصدار.
المخطط الزمني: عنصر TimelineBuilders.Timeline هو قائمة تتضمّن نسخة واحدة أو أكثر من عنصر التنسيق. يمكنك توفير آليات وتعبيرات مختلفة للإشارة إلى الوقت الذي يجب أن ينتقل فيه العارض من كائن تخطيط إلى آخر، مثل إيقاف عرض التخطيط في وقت محدد.
الحالة: هي بنية بيانات من النوع StateBuilders.State يتم تمريرها بين المربّع والتطبيق، لتمكين المكوّنَين من التواصل مع بعضهما. على سبيل المثال، إذا تم النقر على زر في المربّع، ستحتفظ الحالة بمعرّف الزر. يمكنك أيضًا تبادل أنواع البيانات باستخدام خريطة.
Tile: كائن TileBuilders.Tile يمثّل مربّعًا، ويتألف من timeline وresources version ID وfreshness interval وstate.
Protolayout: يظهر هذا المصطلح في اسم فئات مختلفة ذات صلة بالبطاقات، ويشير إلى مكتبة Protolayout في Wear OS، وهي مكتبة رسومات تُستخدَم في مساحات عرض مختلفة في 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

بعد ذلك، أضِف خدمة داخل علامة <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

يؤدي الإذن وintent filter إلى تسجيل هذه الخدمة كمقدّم مربّعات.

يتم عرض الرمز والتصنيف والوصف ومورد المعاينة للمستخدم عندما يضبط مربّعات الشاشة على هاتفه أو ساعته. يُرجى العِلم أنّ مورد المعاينة يتيح استخدام جميع مؤهِّلات الموارد العادية في Android، لذا يمكن تغيير المعاينة وفقًا لعوامل مثل حجم الشاشة ولغة الجهاز. يمكنك الاطّلاع على قائمة التحقّق من المعاينة للحصول على اقتراحات إضافية.

انشر تطبيقك وأضِف شاشة المعلومات إلى لوحة العرض الدوّارة لشاشات المعلومات (هناك أيضًا طريقة أكثر سهولة للمطوّرين لمعاينة شاشة المعلومات، ولكن في الوقت الحالي، يمكنك تنفيذ ذلك يدويًا).

صورة تعرض مربّع Wear OS تم إنشاؤه باستخدام Material 3، ويعرض النص "مرحبًا". — **الشكل 1:** "Hello World" Tile.

للحصول على مثال كامل، يمكنك الاطّلاع على عيّنة التعليمات البرمجية على GitHub أو الدرس التطبيقي حول الترميز.

إنشاء واجهة مستخدم للمربّعات

يتم إنشاء عناصر واجهة المستخدم التعبيرية في Material 3 باستخدام نهج منظّم يعتمد على نمط أداة الإنشاء الآمنة من حيث النوع في Kotlin.

التنسيق

للحصول على إرشادات حول مبادئ التصميم التي تستند إليها عملية إنشاء تنسيقات مربّعات فعّالة ومتجاوبة، يُرجى الاطّلاع على التنسيقات الشائعة للمربّعات.

لإنشاء التنسيق، اتّبِع الخطوات التالية:

بدء نطاق التصميم المتعدد الأبعاد: استخدِم الدالة materialScope() مع توفير context وdeviceConfiguration المطلوبَين. يمكنك تضمين مَعلمات اختيارية، مثل allowDynamicTheme وdefaultColorScheme. تكون قيمة allowDynamicTheme هي true تلقائيًا، ويمثّل defaultColorScheme السمة ColorScheme المستخدَمة عندما لا تكون الألوان الديناميكية متاحة، مثلاً عندما يوقف المستخدم الميزة أو عندما لا تكون متاحة على الجهاز، أو عندما تكون قيمة allowDynamicTheme هي false. عند استخدام واجهات برمجة تطبيقات ImageResource، مثل backgroundImage() في TileService مخصّص، يمكنك استدعاء materialScopeWithResources() بدلاً من ذلك.

إنشاء واجهة المستخدم ضمن النطاق: يجب تحديد جميع مكوّنات واجهة المستخدم لتنسيق مربّع معيّن ضمن دالة lambda لطلب 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 يستفيد من ثلاثة مواضع مختلفة. من الأعلى إلى الأسفل، هي:

titleSlot، يُستخدم عادةً للعنوان الرئيسي أو الرأس.
‫mainSlot، للمحتوى الأساسي.
‫bottomSlot، يُستخدم غالبًا للإجراءات أو المعلومات التكميلية. هذا هو أيضًا المكان الذي يظهر فيه زر الحافة.

تنسيق المربّعات الذي يعرض titleSlot وmainSlot وbottomSlot — **الشكل 2:** titleSlot وmainSlot وbottomSlot

محتوى كل خانة هو كالتالي:

titleSlot (اختياري): عادةً ما تكون بضع كلمات من إنشاء text().
mainSlot (مطلوبة): مكوّنات منظَّمة في هياكل مثل الصفوف والأعمدة ومجموعات الأزرار. يمكن أيضًا تضمين هذه المكوّنات بشكل متكرر داخل بعضها البعض، على سبيل المثال، يمكن أن يحتوي العمود على صفوف.
bottomSlot (اختياري): عادةً ما يتم ملؤه إما بزر ملاصق للحافة أو تصنيف نصي.

بما أنّه لا يمكن الانتقال للأعلى أو للأسفل في المربّعات، لا تتوفّر مكوّنات للتنقّل بين الصفحات أو الانتقال للأعلى أو للأسفل أو التعامل مع قوائم المحتوى الطويلة. احرص على أن يظل المحتوى مرئيًا عند زيادة حجم الخط أو عندما يصبح النص أطول بسبب الترجمة.

مكونات واجهة المستخدم

توفّر مكتبة protolayout-material3 عددًا كبيرًا من المكوّنات المصمّمة وفقًا لمواصفات Material 3 Expressive واقتراحات واجهة المستخدم.

الأزرار

تكون الأزرار في الأساس موجّهة نحو الإجراء. وهي تعمل على تشغيل إجراءات محددة. يحدد محتوى كل زر، مثل أيقونة أو نص قصير، الإجراء.

‫textButton()‎: زرّ يتضمّن خانة واحدة لمحتوى نصي (قصير)
‫iconButton()‎: زرّ يتضمّن خانة واحدة لتمثيل رمز
‫avatarButton()‎: زر أفاتار على شكل حبة دواء يوفّر ما يصل إلى ثلاث خانات لعرض محتوى يمثّل تصنيفًا مكدّسًا عموديًا وتصنيفًا ثانويًا وصورة (أفاتار) بجانبه
‫imageButton()‎: زر صورة قابل للنقر لا يوفّر خانات إضافية، بل صورة فقط (على سبيل المثال، backgroundImage كخلفية)
‫compactButton()‎: زر صغير يوفّر ما يصل إلى خانتَين لعرض محتوى مكدّس أفقيًا يمثّل رمزًا ونصًا بجانبه
‫button()‎: زر على شكل حبّة دواء يوفّر ما يصل إلى ثلاث خانات لعرض محتوى يمثّل تصنيفًا وتصنيفًا ثانويًا مكدّسَين عموديًا، ورمزًا بجانبهما

أزرار Edge

الزر الجانبي هو زر مخصّص بعرض كامل يتم تثبيته في أسفل الشاشة الدائرية للساعة، ويمثّل الإجراء الأكثر أهمية الذي يمكن اتّخاذه من شاشة المربّع الحالية.

‫iconEdgeButton()‎: زر حافة يوفّر خانة واحدة لعرض رمز أو محتوى صغير دائري مشابه
‫textEdgeButton()‎: زرّ حافة يوفّر خانة واحدة لإدخال نص أو محتوى طويل وعريض مشابه

بطاقات

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

()titleCard: بطاقة عنوان توفّر من خانة واحدة إلى ثلاث خانات، وتكون عادةً مستندة إلى نص
appCard()‎: بطاقة تطبيق توفّر ما يصل إلى خمس خانات، وتكون عادةً مستندة إلى نص
‫textDataCard()‎: بطاقة بيانات توفّر ما يصل إلى ثلاث خانات مكدّسة عموديًا، وتستند عادةً إلى نص أو أرقام
‫iconDataCard(): بطاقة بيانات توفّر ما يصل إلى ثلاث خانات مكدّسة عموديًا، وتستند عادةً إلى نص أو أرقام، مع رمز
‫graphicDataCard()‎: بطاقة بيانات رسومية توفّر خانة للبيانات الرسومية، مثل مؤشر مستوى التقدّم، وما يصل إلى خانتَين مكدّستَين عموديًا، عادةً للأوصاف النصية

مؤشرات التقدم

‫circularProgressIndicator()‎: يشير إلى مستوى التقدّم نحو تحقيق هدف معيّن باستخدام عنصر شعاعي
‫segmentedCircularProgressIndicator()‎: يشير إلى مستوى التقدّم نحو تحقيق هدف معيّن باستخدام عنصر شعاعي يتضمّن مراحل مختلفة

تجميع عناصر التنسيق

‫buttonGroup()‎: تنسيق مكوّن يضع العناصر الثانوية في تسلسل أفقي
‫primaryLayout()‎: تنسيق ملء الشاشة الذي يمثّل نمط تنسيق M3 المقترَح، وهو متجاوب ويهتم بموضع العناصر، بالإضافة إلى الهوامش المقترَحة والحشو المطبَّق

تطبيق مظهر

في Material 3 Expressive، يتم تحديد نظام الألوان من خلال 29 دورًا قياسيًا للألوان، يتم تنظيمها في ست مجموعات: أساسية، وثانوية، وثالثية، وخطأ، وسطح، ومخطط تفصيلي.

نظام الألوان التعبيرية في Material 3، يعرض أدوار الألوان منظَّمة في مجموعات مثل الألوان الأساسية والثانوية والثالثية وألوان الخطأ والسطح والمخطط. — **الشكل 3.** نظام الألوان التعبيرية في Material 3

يحدّد ColorScheme لونًا لكل دور من هذه الأدوار الـ 29، وبما أنّه جزء من 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

اللون

يستخدم كل مكوّن فردي مجموعة فرعية من أدوار الألوان الـ 29 التي يحدّدها ColorScheme. على سبيل المثال، تستخدم الأزرار ما يصل إلى أربعة ألوان، يتم أخذها تلقائيًا من المجموعة "الأساسية" في ColorScheme النشط:

رمز المكوّن `ButtonColors`	دور `ColorScheme`
containerColor	الأساسي
iconColor	onPrimary
labelColor	onPrimary
secondaryLabelColor	onPrimary (معدّل الشفافية 0.8)

للحصول على إرشادات مفصّلة حول تطبيق الألوان على تصاميم 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 Expressive، ما يساعد مربّعك على الالتزام بأفضل الممارسات المتعلّقة بأسلوب الخط من أجل تسهيل القراءة والتسلسل الهرمي. توفّر المكتبة مجموعة من 18 ثابتًا دلاليًا للخطوط، مثل 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

أخيرًا، إذا كنت بحاجة إلى التحكّم في الحجم أو التباعد بين الأحرف (لا يُنصح بذلك)، استخدِم basicText() بدلاً من text()، وأنشئ قيمة للسمة fontStyle باستخدام fontStyle()).

الشكل والهوامش

يمكنك تغيير نصف قطر الزاوية لكل مكوّن تقريبًا باستخدام السمةshape الخاصة به. يتم الحصول على القيم من السمة shapes في MaterialScope:

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: يعرض صورة مضمّنة مع النص.

على سبيل المثال، يمكنك كتابة كلمة "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

العمل مع المراجع

لا يمكن لبطاقات المعلومات الوصول إلى أي من موارد تطبيقك. وهذا يعني أنّه لا يمكنك تمرير معرّف صورة 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 وفي التطبيق المصاحب للساعة على الهواتف.

لمساعدة المستخدمين في الاستفادة إلى أقصى حد من صورة المعاينة هذه، يُرجى التحقّق من التفاصيل التالية حول المربّع:

يعكس أحدث تصميم. يجب أن تمثّل المعاينة بدقة أحدث تصميم للمربّع.
استخدام السمات المقترَحة: لتقديم أفضل جودة عرض ممكنة وتجربة مستخدم جيدة، يجب أن تكون أبعاد صورة المعاينة 400 بكسل × 400 بكسل.
يستخدم نسق ألوان ثابتًا. استخدِم نسق الألوان الثابت للمربّع، وليس نسقًا ديناميكيًا.
يجب أن يتضمّن رمز التطبيق. تأكَّد من ظهور رمز تطبيقك في أعلى صورة المعاينة.
عرض حالة التحميل/تسجيل الدخول يجب أن تعرض المعاينة حالة "محمَّلة" أو "مسجَّل الدخول" تعمل بكامل وظائفها، مع تجنُّب أي محتوى فارغ أو عنصر نائب.
استفِد من قواعد حلّ الموارد للتخصيص (اختياري). ننصحك باستخدام قواعد دقة الموارد في Android لتقديم معاينات تتطابق مع حجم شاشة الجهاز أو لغته أو إعدادات لغته. ويكون هذا مفيدًا بشكل خاص إذا كان مظهر المربّع يختلف على الأجهزة.