תחילת העבודה עם כרטיסי מידע

כדי להתחיל לספק רכיבי Tile מהאפליקציה, צריך לכלול את התלויות הבאות בקובץ 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")
}

מושגים מרכזיים

האריחים לא בנויים באותה צורה כמו אפליקציות ל-Android, והם מבוססים על מושגים שונים:

• תבניות פריסה: מגדירות את הסידור הכללי של הרכיבים החזותיים בתצוגה. הפונקציה primaryLayout() מבצעת את הפעולה הזו.
• רכיבי פריסה: מייצגים רכיב גרפי בודד, כמו לחצן או כרטיס, או כמה רכיבים כאלה שמקובצים יחד באמצעות עמודה, buttonGroup או רכיב דומה. הם מוטמעים בתבנית פריסה.

• משאבים: אובייקטים של ResourceBuilders.Resources מורכבים ממפה של זוגות של מפתח/ערך של משאבי Android (תמונות) שנדרשים לעיבוד פריסה, ומגרסה.
• ציר זמן: אובייקט TimelineBuilders.Timeline הוא רשימה של מופע אחד או יותר של אובייקט פריסה. אתם יכולים לספק מנגנונים שונים וביטויים כדי לציין מתי מעבד התצוגה צריך לעבור מאובייקט פריסה אחד לאחר, למשל כדי להפסיק להציג פריסה בזמן מסוים.
• מצב: מבנה נתונים מסוג StateBuilders.State שמועבר בין הרכיב והאפליקציה, כדי לאפשר לשני הרכיבים לתקשר ביניהם. לדוגמה, אם משתמש מקיש על לחצן בפריט, המצב מכיל את מזהה הלחצן. אפשר גם להמיר סוגי נתונים באמצעות מיפוי.
• Tile: אובייקט TileBuilders.Tile שמייצג משבצת, שמורכב מציר זמן, מזהה גרסת משאבים, מרווח עדכניות ומצב.
• ‫Protolayout: המונח הזה מופיע בשם של מחלקות שונות שקשורות לאריחים, והוא מתייחס לספריית Protolayout של Wear OS, ספריית גרפיקה שמשמשת בפלטפורמות שונות של Wear OS.

יצירת משבצת

שימוש ב-Material3TileService (מומלץ)

כשיוצרים רכיבי Material 3 (androidx.wear.tiles:tiles:1.6.0 ומעלה), תמיד מרחיבים את Material3TileService במקום את המחלקה TileService ברמה הנמוכה יותר. ‫Material3TileService מספק ארכיטקטורה מבוססת-Kotlin עם דעה מגובשת, שמפשטת את פיתוח המשבצות:

• קורוטינות מובנות של 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

הרשאת הסינון והכוונה רושמות את השירות הזה כספק של אריחים.

הסמל, התווית, התיאור ומשאב התצוגה המקדימה מוצגים למשתמשים כשהם מגדירים כרטיסי מידע בטלפון או בשעון. שימו לב שמשאב התצוגה המקדימה תומך בכל המסווגים הסטנדרטיים של משאבים ב-Android, כך שאפשר לשנות את התצוגה המקדימה בהתאם לגורמים כמו גודל המסך ושפת המכשיר. המלצות נוספות מופיעות ברשימת המשימות לתצוגה מקדימה.

מפרסים את האפליקציה ומוסיפים את ה-Tile לגלגל ה-Tiles (יש גם דרך ידידותית יותר למפתחים לצפות בתצוגה מקדימה של Tile, אבל בשלב הזה פשוט עושים את זה באופן ידני).

דוגמה מלאה אפשר לראות בדוגמת הקוד ב-GitHub או בסדנת הקוד.

יצירת ממשק משתמש לכפתורים

רכיבי ממשק משתמש של Material 3 Expressive נוצרים באמצעות גישה מובנית שמבוססת על תבנית בונה בטוחה לטיפוסים של Kotlin.

פריסה

כאן מפורטות הנחיות לגבי עקרונות העיצוב שמאחורי יצירת פריסות יעילות ורספונסיביות של כרטיסי מידע.

כדי ליצור את הפריסה:

1. יוצרים היקף של Material Design: קוראים לפונקציה materialScope() ומספקים את הערכים הנדרשים context ו-deviceConfiguration. אפשר לכלול פרמטרים אופציונליים, כמו allowDynamicTheme ו-defaultColorScheme. הערך של allowDynamicTheme הוא true כברירת מחדל, והערך של defaultColorScheme מייצג את ColorScheme שמשמש כשצבעים דינמיים לא זמינים – למשל, אם המשתמש השבית את התכונה – או אם המכשיר לא תומך בה, או אם הערך של allowDynamicTheme הוא false).

2. בניית ממשק המשתמש בהיקף: כל רכיבי ממשק המשתמש של פריסת Tile מסוימת צריכים להיות מוגדרים בתוך ה-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, פריסת המשבצות מבוססת על גישה שדומה לגישה של יצירת הודעה, וכוללת שלושה משבצות נפרדות. הם מופיעים מלמעלה למטה:

1. התג titleSlot, בדרך כלל לכותרת ראשית או לכותרת.
2. ה-mainSlot, לתוכן הליבה.
3. הסמל 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, מערכת הצבעים מוגדרת על ידי 29 תפקידי צבע סטנדרטיים, שמסודרים ב-6 קבוצות: primary,‏ secondary,‏ tertiary,‏ error,‏ surface ו-outline.

בColorScheme כל אחד מ-29 התפקידים האלה ממופה לצבע תואם, ומכיוון שהוא חלק מMaterialScope וחובה ליצור רכיבים בתוכו, הצבעים נלקחים מהסכמה באופן אוטומטי. בגישה הזו, כל רכיבי ממשק המשתמש עומדים באופן אוטומטי בתקני Material Design.

כדי לאפשר למשתמשים לבחור בין ערכת צבעים שאתם מגדירים – למשל, ערכת צבעים שמשקפת את צבעי המותג שלכם – לבין ערכת צבעים שמסופקת על ידי המערכת – למשל, ערכת צבעים שנגזרת מתצוגת השעון הנוכחית של המשתמש או ערכת צבעים שהמשתמש בחר – צריך לאתחל את 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 הפעיל:

הנחיות מפורטות לגבי שימוש בצבעים בעיצובים של 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, וכך לעזור לכם להקפיד על שיטות מומלצות של טיפוגרפיה שמשפרות את הקריאות ואת ההיררכיה של המודעה. הספרייה מציעה קבוצה של 18 קבועים סמנטיים של טיפוגרפיה, כמו BODY_MEDIUM. הקבועים האלה משפיעים גם על צירים של גופנים שאינם גודל.

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

כדי לקבל שליטה רבה יותר, אפשר לספק הגדרות נוספות. ב-Wear OS 6 ובגרסאות מתקדמות יותר, סביר להניח שנעשה שימוש בגופן משתנה, שאפשר לשנות אותו לאורך הצירים italic,‏ weight,‏ width ו-roundness. אפשר לשלוט בצירים האלה באמצעות הפרמטר 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 שלו. הערכים מגיעים מהמאפיין 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: יוצר קו מעוקל סביב ה-Arc.
• ‫ArcText: מעבד טקסט מעוקל ב-Arc.
• ‫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 מציגה את תמונת התצוגה המקדימה של כרטיס המידע, שמפנה למניפסט של אפליקציית Android, בכלי לעריכת קרוסלת כרטיסי המידע כדי להוסיף כרטיס מידע חדש. הכלי הזה מופיע גם במכשירי Wear OS וגם באפליקציה הנלווית לשעון בטלפונים.

כדי לעזור למשתמשים להפיק את המרב מתמונת התצוגה המקדימה הזו, צריך לוודא את הפרטים הבאים לגבי המשבצת:

• משקף את העיצוב העדכני ביותר. התצוגה המקדימה צריכה לשקף בצורה מדויקת את העיצוב העדכני ביותר של האריח.
• שימוש במאפיינים מומלצים. כדי לספק את איכות התצוגה הטובה ביותר וחוויית משתמש טובה, המידות של תמונת התצוגה המקדימה צריכות להיות 400x400 פיקסלים.
• משתמשים בערכת צבעים סטטית. השתמש בערכת הצבעים הסטטית של האריח, ולא בערכת צבעים דינמית.
• כולל סמל אפליקציה. מוודאים שסמל האפליקציה מופיע בחלק העליון של תמונת התצוגה המקדימה.
• מציג את מצב הטעינה או הכניסה. בתצוגה המקדימה צריך להופיע מצב 'טעינה' או 'התחברות' שפועל באופן מלא, בלי תוכן ריק או תוכן placeholder.
• אפשר להשתמש בכללים לפתרון בעיות במשאבים כדי לבצע התאמה אישית (אופציונלי). כדאי להשתמש בכללים של Android לגבי רזולוציית משאבים כדי לספק תצוגות מקדימות שתואמות לגודל התצוגה, לשפה או להגדרות האזוריות של המכשיר. האפשרות הזו שימושית במיוחד אם המראה של המשבצת משתנה במכשירים שונים.