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

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

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

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

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

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

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

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

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

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

כדי לשלוח את העדכון, קוראים לשיטת 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 או מופעלת כוונה להפעיל פעילות.
  • כשמשתמש מקיים אינטראקציה עם האפליקציה בחזית, או בזמן שהאפליקציה כבר מתעדכנת בתגובה להודעה או לשידור של העברת הודעות בענן ב-Firebase ‏ (FCM).

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

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

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

משאבים

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