ניהול ועדכון של GlanceAppWidget

בקטעים הבאים מוסבר איך לעדכן את GlanceAppWidget ולנהל את המצב שלו.

ניהול המצב של GlanceAppWidget

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

אפשר לחלק את המושג "מצב" לחלקים הבאים:

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

שימוש במצב האפליקציה

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

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

class DestinationAppWidget : GlanceAppWidget() {

    // ...

    @Composable
    fun MyContent() {
        val repository = remember { DestinationsRepository.getInstance() }
        // Retrieve the cache data everytime the content is refreshed
        val destinations by repository.destinations.collectAsState(State.Loading)

        when (destinations) {
            is State.Loading -> {
                // show loading content
            }

            is State.Error -> {
                // show widget error content
            }

            is State.Completed -> {
                // show the list of destinations
            }
        }
    }
}

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

עדכון של GlanceAppWidget

אתם יכולים לבקש לעדכן את תוכן הווידג'ט באמצעות GlanceAppWidget. כמו שמוסבר בקטע ניהול המצב של GlanceAppWidget, ווידג'טים של אפליקציות מתארחים בתהליך אחר. התכונה "בקצרה" מתרגמת את התוכן לRemoteViews בפועל ושולחת אותם למארח. כדי לעדכן את התוכן, צריך ליצור מחדש את RemoteViews ב-Glance ולשלוח אותם שוב.

כדי לשלוח את העדכון, מפעילים את השיטה update של המכונה GlanceAppWidget, ומספקים את context ואת glanceId:

MyAppWidget().update(context, glanceId)

כדי לקבל את הערך של glanceId, שולחים שאילתה ל-GlanceAppWidgetManager:

val manager = GlanceAppWidgetManager(context)
val widget = GlanceSizeModeWidget()
val glanceIds = manager.getGlanceIds(widget.javaClass)
glanceIds.forEach { glanceId ->
    widget.update(context, glanceId)
}

לחלופין, אפשר להשתמש באחד מהתוספים של GlanceAppWidget update:

// Updates all placed instances of MyAppWidget
MyAppWidget().updateAll(context)

// Iterate over all placed instances of MyAppWidget and update if the state of
// the instance matches the given predicate
MyAppWidget().updateIf<State>(context) { state ->
    state == State.Completed
}

אפשר לקרוא לשיטות האלה מכל חלק באפליקציה. מכיוון שהן פונקציות suspend, מומלץ להפעיל אותן מחוץ להיקף של ה-thread הראשי. בדוגמה הבאה, הם מופעלים ב-CoroutineWorker:

class DataSyncWorker(
    val context: Context,
    val params: WorkerParameters,
) : CoroutineWorker(context, params) {

    override suspend fun doWork(): Result {
        // Fetch data or do some work and then update all instance of your widget
        MyAppWidget().updateAll(context)
        return Result.success()
    }
}

פרטים נוספים על שגרות המשך זמינים במאמר שגרות המשך ב-Kotlin ב-Android.

מתי לעדכן ווידג'טים

לעדכן ווידג'טים באופן מיידי או מדי פעם.

הווידג'ט יכול להתעדכן מיד כשהאפליקציה פעילה. לדוגמה:

  • כשמשתמש יוצר אינטראקציה עם ווידג'ט, מופעלת פעולה, קריאת lambda או Intent להפעלת פעילות.
  • כשהמשתמש מבצע אינטראקציה עם האפליקציה בחזית, או כשהאפליקציה כבר מתעדכנת בתגובה להודעה או לשידור של "העברת הודעות בענן ב-Firebase"‏ (FCM).

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

הווידג'ט יכול להתעדכן מדי פעם כשהאפליקציה לא פועלת. לדוגמה:

  • אפשר להשתמש ב-updatePeriodMillis כדי לעדכן את הווידג'ט פעם אחת בכל 30 דקות.
  • אפשר להשתמש ב-WorkManager כדי לתזמן עדכונים בתדירות גבוהה יותר, למשל כל 15 דקות.
  • עדכון הווידג'ט בתגובה לשידור.

משאבים

הקודם
מעקב אחר מדדים בווידג'ט
הבא
פיתוח ממשק משתמש באמצעות 'בקצרה'