הגדרת Watch Face Format

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

דרישות מוקדמות

כדי להכין את סביבת הפיתוח לשימוש ב-Watch Face Format, צריך לבצע את שלבי ההגדרה הבאים:

1. מתקינים את ה-SDK ל-Android 14 (רמת API 34) ואילך. אם תצוגת השעון לא מסתמכת על תכונות או התנהגות שספציפיים לגרסה 2, אפשר להתקין במקום זאת את ה-SDK ל-Android 13 (רמת API 33).

   ערכת ה-SDK מכילה כלים נדרשים אחרים, כולל aapt2 ו-android.jar.

2. לחלופין, אפשר להתקין את Android Studio, שבו אפשר למצוא גם את הכלים האלה.

מבנה הפרויקט

כשיוצרים תצוגת שעון בהתאמה אישית שמשתמשת ב-Watch Face Format, קובץ Android App Bundle שכולל את קובץ תצוגת השעון בהתאמה אישית חייב להיות נפרד לחלוטין מקובץ Android App Bundle שמכיל את הלוגיקה של אפליקציית Wear OS. חנויות אפליקציות מסוימות, כולל Google Play, מונעות העלאה של קובץ Android App Bundle שכולל לוגיקה של Wear OS ותצוגת שעון מותאמת אישית.

יצירת חבילה של תצוגת שעון

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

הצהרה על שימוש ב-Watch Face Format

בקובץ המניפסט של האפליקציה החדשה (AndroidManifest.xml), מוסיפים מאפיין של האפליקציה שמציין את השימוש ב-Watch Face Format. אם אתם לא רוצים להגביל את הגישה לתצוגת השעון למכשירים עם Wear OS מגרסה 5 ואילך, עליכם ליצור 2 חבילות APK שונות של תצוגת השעון, אחת שתומכת בגרסה 2 ואחת שתומכת בגרסה 1. מידע נוסף על הגדרת גרסאות של האפליקציה

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<manifest ...>
    <!--
        Use SDK version 34 for version 2 of WFF, and SDK version 33 for version
        1 of WFF
    -->
    <uses-sdk
        android:minSdkVersion="34"
        android:targetSdkVersion="34" />

    <!--
        WFF is a resource-only format, so the hasCode attribute should be set to
        false to reflect this.
    -->
    <application
        android:label="@string/watch_face_name"
        android:hasCode="false"
        ...>
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="2" />
    </application>
</manifest>

הצהרת מטא-נתונים של תצוגת שעון

יוצרים קובץ חדש בשם watch_face_info.xml בתיקיית המשאבים res/xml של האפליקציה. כאן מגדירים את המטא-נתונים של תצוגת השעון:

<?xml version="1.0" encoding="utf-8"?>
<WatchFaceInfo>
    <!-- Only "Preview" is required. -->
    <Preview value="@drawable/watch_face_preview" />
    <Category value="CATEGORY_EMPTY" />
    <AvailableInRetail value="true" />
    <MultipleInstancesAllowed value="true" />
    <Editable value="true" />
</WatchFaceInfo>

השדות בקובץ הזה מייצגים את הפרטים הבאים:

Preview

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

Category

מגדיר את הקטגוריה של תצוגת השעון. הערך חייב להיות מחרוזת או הפניה למחרוזת, למשל @string/ref_name. כל יצרן מכשיר יכול להגדיר קבוצה משלו של קטגוריות של תצוגות השעון.

ערך ברירת המחדל: empty_category_meta, שמקבץ את תצוגת השעון הזו עם תצוגות שעון אחרות בקטגוריה 'ריקה' בתחתית התצוגה לבחירת תצוגת שעון.

AvailableInRetail

אם תצוגת השעון זמינה במצב הדגמה לקמעונאים של המכשיר. חייב להיות ערך בוליאני או הפניה לערך בוליאני כמו @bool/watch_face_available_in_retail.

ערך ברירת המחדל: false

MultipleInstancesAllowed

אם לתצוגת השעון יכולים להיות כמה מועדפים. חייב להיות ערך בוליאני או הפניה לערך בוליאני כמו @bool/watch_face_multiple_instances_allowed.

ערך ברירת המחדל: false

Editable

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

ערך ברירת המחדל: false

הצהרה על השם של תצוגת השעון

בקובץ המניפסט של האפליקציה (AndroidManifest.xml), מגדירים את המאפיין android:label לשם של תצוגת השעון:

<application android:label="@string/watch_face_name" >

הצהרת תמיכה בצורות של תצוגות שעון (אופציונלי)

השלב הזה נדרש רק אם רוצים לתמוך בהתנהגות שונה בגדלים שונים של תצוגות שעון. אפשר לדלג על השלב הזה אם אתם לא רוצים לשנות את הגודל של תצוגת השעון בהתאם לגודל השעון.

בתיקיית המשאבים res/xml של האפליקציה, מגדירים את צורות תצוגות השעון שאתם תומכים בהן בקובץ watch_face_shapes.xml:

<WatchFaces>
    <!-- The default shape is "CIRCLE". -->
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
    <WatchFace shape="RECTANGLE" width="380" height="400"
               file="@raw/watchface_rectangle"/>
</WatchFaces>

הצהרת פרטים על תצוגת השעון

בספריית המשאבים res/raw של האפליקציה, צריך ליצור קבצים שתואמים לערכי המאפיינים file שמשמשים להצהרה על תמיכה בצורות של תצוגות השעון.

כאן מגדירים את המראה וההתנהגות של תצוגת השעון לכל צורה של תצוגת שעון. אם לא הגדרתם קובץ צורות, צריך ליצור רק קובץ אחד, watchface.xml.

לפי הדוגמה שבדף הזה, קובצי ה-XML הגולמיים יהיו:

• res/raw/watchface.xml
• res/raw/watchface_large_circle.xml
• res/raw/watchface_rectangle.xml

הרכיב הבסיסי (root) הוא תמיד WatchFace:

<WatchFace width="450" height="450" clipShape="CIRCLE">
    <!-- Remainder of your Watch Face Format definition here. -->
    <!-- If this file defines a watch face for a circular device shape, place
         resources used in this file in the "/res/drawable-nodpi" directory. -->
    <!-- If this file defines a watch face for a rectangular or other
         non-circular shape, place resources ued in this file in the
         "/res/drawable-notround-nodpi" directory. -->
</WatchFace>

הערה: כשמגדירים את תצוגת השעון, חשוב לבצע אופטימיזציה של השימוש בזיכרון.

זיהוי בעל התוכן הדיגיטלי של תצוגת השעון (אופציונלי)

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

<application ...>
    ...
    <property
        android:name="com.google.wear.watchface.format.publisher"
        android:value="{toolName}-{toolVersion}" />
</application>

בדיקת התקינות והביצועים של תצוגת השעון

במהלך הפיתוח, ולפני ההעלאה ל-Google Play, כדאי להשתמש בכלים לאימות כדי לוודא ששעון החכם לא מכיל שגיאות ושעומד בהמלצות לשימוש בזיכרון.

• כדאי לקרוא מידע נוסף על אופטימיזציה של שימוש בזיכרון ועל בדיקת שימוש בזיכרון לקראת פרסום.
• מידע נוסף על השימוש במאמת XML כחלק ממחזור הפיתוח.

יצירת App Bundle של תצוגת השעון

כדי ליצור את קובץ ה-Android App Bundle שמכיל את תצוגת השעון, משתמשים במערכת ה-build של Gradle. איך יוצרים אפליקציה באמצעות Gradle

הדגמה לכך מופיעה בדוגמאות ב-GitHub.