ניהול ועדכון של 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
            }
        }
    }
}
GlanceSnippets.kt

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

עדכון של GlanceAppWidget

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

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

MyAppWidget().update(context, glanceId)
GlanceSnippets.kt

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

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

אפשר גם להשתמש באחד מתוספי 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
}
GlanceSnippets.kt

אפשר לקרוא לשיטות האלה מכל חלק באפליקציה. מכיוון שהן פונקציות של 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()
    }
}
GlanceSnippets.kt

למידע נוסף על שגרות משנה, אפשר לעיין במאמר שגרות משנה ב-Kotlin ב-Android.

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

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

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

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

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

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

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

משאבים

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