חשיפת נתונים לסיבוכים

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

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

תחילת העבודה

מוסיפים את יחסי התלות הבאים למודול האפליקציה:

dependencies {
  implementiation("androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1")
}

יצירת שירות מקור הנתונים

כשנדרשים נתוני סיבוך, מערכת Wear OS שולחת בקשות עדכון למקור הנתונים. כדי להגיב לבקשות העדכון, במקור הנתונים צריך להטמיע את השיטה onComplicationRequest() של המחלקה SuspendingComplicationDataSourceService.

מערכת Wear OS קוראת ל-onComplicationRequest() כשהיא צריכה נתונים ממקור הנתונים שלכם – למשל, כשסיבוך שמשתמש במקור הנתונים שלכם הופך לפעיל או כשעובר פרק זמן קבוע.

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

קטע הקוד הבא מציג הטמעה לדוגמה:

class MyComplicationDataSourceService : SuspendingComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationData? {
        // Retrieve the latest info for inclusion in the data.
        val text = getLatestData()
        return shortTextComplicationData(text)
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, and title.
            .build()

    // ...
}

הצהרות והרשאות במניפסט

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

במניפסט של האפליקציה, צריך להצהיר על השירות ולהוסיף מסנן Intent של פעולת בקשת עדכון. בנוסף, צריך להוסיף את ההרשאה BIND_COMPLICATION_PROVIDER למניפסט כדי להגן על השירות ולוודא שרק מערכת Wear OS יכולה להתחבר לשירותי הספק.

בנוסף, צריך לכלול מאפיין android:icon באלמנט service שמספק סמל לבן בצבע אחד. מומלץ להשתמש בנכסי וקטור לציור של הסמלים. הסמל מייצג את מקור הנתונים ומוצג בכלי לבחירת נתונים.

הנה דוגמה:

<service
    android:name=".snippets.complication.MyComplicationDataSourceService"
    android:exported="true"
    android:label="@string/my_complication_service_label"
    android:icon="@drawable/complication_icon"
    android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER">
    <intent-filter>
        <action android:name="android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST" />
    </intent-filter>

    <!-- Supported types should be comma-separated e.g. SHORT_TEXT,SMALL_IMAGE -->
    <meta-data
        android:name="android.support.wearable.complications.SUPPORTED_TYPES"
        android:value="SHORT_TEXT" />
    <meta-data
        android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
        android:value="300" />

    <!--
        Optionally, the complication can be configured by the user by specifying a
        configuration activity.
    -->
    <meta-data
        android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
        android:value="MY_CONFIG_ACTION" />

</service>

רכיבי מטא-נתונים

בקובץ המניפסט, שימו לב לרכיבי המטא-נתונים הבאים:

• ‫android:name="android.support.wearable.complications.SUPPORTED_TYPES": מציין את סוגי הנתונים של הרכיבים המורכבים שמקור הנתונים תומך בהם.
• android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": מציין באיזו תדירות המערכת צריכה לבדוק אם יש עדכונים לנתונים.

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

אם לא מגדירים את UPDATE_PERIOD_SECONDS ל-0, צריך להשתמש בערך של לפחות 300 (5 דקות), שהוא תקופת העדכון המינימלית שהמערכת אוכפת, כדי לשמור על חיי הסוללה של המכשיר. בנוסף, חשוב לזכור שבקשות לעדכון מגיעות בתדירות נמוכה יותר כשהמכשיר במצב סביבה או שלא עונדים אותו.

הוספת פעילות של הגדרה

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

מניפסט לדוגמה שכולל רכיב meta-data עם המפתח PROVIDER_CONFIG_ACTION: הערך של הרכיב הזה הוא הפעולה שמשמשת להפעלת פעילות ההגדרה.

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

<intent-filter>
    <action android:name="MY_CONFIG_ACTION" />
    <category android:name="android.support.wearable.complications.category.PROVIDER_CONFIG" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

הפעילות יכולה לקבל פרטים על משבצת הסיבוך שהיא מגדירה מה-Intent בתוך השיטה onCreate() של הפעילות:

// Keys defined on ComplicationDataSourceService
val id = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_ID, -1)
val type = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_TYPE, -1)
val source = intent.getStringExtra(EXTRA_CONFIG_DATA_SOURCE_COMPONENT)

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

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()

שימוש בעדכונים בדחיפה

במקום לציין את מרווח העדכונים במניפסט של האפליקציה, אפשר להשתמש במופע של ComplicationDataSourceUpdateRequester כדי להפעיל עדכונים באופן דינמי. כדי לבקש עדכון, אפשר להתקשר אל requestUpdate().

זהירות: כדי לשמור על חיי הסוללה של המכשיר, לא מומלץ להתקשר אל requestUpdate() מהמופע של ComplicationDataSourceUpdateRequester בתדירות גבוהה יותר מפעם ב-5 דקות בממוצע.

ציון ערכים שתלויים בזמן

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

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

• TimeFormatComplicationText – מעצב ערך של תאריך או שעה.
• TimeDifferenceComplicationText – ספירה עולה או יורדת עד לזמן שצוין.

נתונים בציר הזמן

כדי להגדיר מקורות נתונים של רכיבי מידע שמספקים רצף של ערכים בזמנים מוגדרים מראש, משתמשים ב-SuspendingTimelineComplicationDataSourceService.

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

class MyTimelineComplicationDataSourceService : SuspendingTimelineComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationDataTimeline? {
        if (request.complicationType != ComplicationType.SHORT_TEXT) {
            return ComplicationDataTimeline(
                defaultComplicationData = NoDataComplicationData(),
                timelineEntries = emptyList()
            )
        }
        // Retrieve list of events from your own datasource / database.
        val events = getCalendarEvents()
        return ComplicationDataTimeline(
            defaultComplicationData = shortTextComplicationData("No event"),
            timelineEntries = events.map {
                TimelineEntry(
                    validity = TimeInterval(it.start, it.end),
                    complicationData = shortTextComplicationData(it.name)
                )
            }
        )
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, title etc
            .build()

    // ...
}

ההתנהגות של SuspendingTimelineComplicationDataSourceService היא כזו:

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

הוספת ערכים דינמיים

החל מ-WearOS 4, בחלק מהסיבוכים אפשר להציג ערכים שמתעדכנים בתדירות גבוהה יותר, על סמך ערכים שזמינים ישירות בפלטפורמה. כדי לספק את היכולת הזו ברכיבי המידע, צריך להשתמש בשדות ComplicationData שמקבלים ערכים דינמיים. הפלטפורמה מעריכה ומעדכנת את הערכים האלה לעיתים קרובות, בלי לדרוש שהספק של התוסף יפעל.

שדות לדוגמה כוללים את GoalProgressComplicationDataשדה הערך הדינמי ואת DynamicComplicationText, שאפשר להשתמש בהם בכל שדה ComplicationText. הערכים הדינמיים האלה מבוססים על הספרייה androidx.wear.protolayout.expression.

במצבים מסוימים, הפלטפורמה לא יכולה להעריך ערכים דינמיים:

• לפעמים הערך הדינמי לא זמין: זה קורה, למשל, כשהמכשיר לא על היד. במקרים כאלה, הפלטפורמה משתמשת בערך של שדה ברירת המחדל לביטול ערך דינמי במקום זאת, ב שדה הפלייסהולדר של NoDataComplicationData.
• הערך הדינמי אף פעם לא זמין: המצב הזה קורה במכשיר שפועלת בו גרסה ישנה יותר של Wear OS 4. במצב כזה, הפלטפורמה משתמשת בשדה גיבוי של מכשיר משני, כמו getFallbackValue().

מקורות מידע שקשורים לנושא

• סוגים ושדות

• מאגר הדוגמאות של Wear OS