יצירת ווידג'ט פשוט

אפשר לנסות את הדרך של כתיבת הודעה
‫Jetpack Compose היא ערכת הכלים המומלצת לבניית ממשק משתמש ב-Android. איך יוצרים ווידג'טים באמצעות ממשקי API בסגנון Compose
Jetpack Glance →

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

דוגמה לווידג'ט מוזיקה
איור 1. דוגמה לווידג'ט מוזיקה.

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

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

רכיבי הווידג'ט

כדי ליצור ווידג'ט, צריך את הרכיבים הבסיסיים הבאים:

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

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

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

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

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

הצהרה על קובץ ה-XML של AppWidgetProviderInfo

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

במסמכי Glance מוסבר איך להגדיר את קובץ ה-XML של המטא-נתונים, במאמר בנושא הצהרה על קובץ ה-XML של AppWidgetProviderInfo בקטע בנושא Compose-first.

שימוש במחלקה AppWidgetProvider לטיפול בשידורים של ווידג'טים

המנגנונים של מקלט השידור בפלטפורמה, המסננים להצהרת המניפסט ולולאות האירועים של מחזור החיים מאוחדים מתחת לפלטפורמה. בפיתוח בגישת Compose-first, השידורים האלה מתואמים באמצעות רכיב ה-wrapper‏ GlanceAppWidgetReceiver.

כדי להבין איך לרשום את מקלט השידור במניפסט וליישם שינויים בהגדרות ברירת המחדל של מחזור החיים שתואמים ל-Hilt, אפשר לעיין בקטע Use the AppWidgetProvider class to handle broadcasts (שימוש במחלקה AppWidgetProvider לטיפול בשידורים) במסמכי Glance.

יצירת פריסת הווידג'ט

צריך להגדיר פריסה ראשונית לווידג'ט ב-XML ולשמור אותה בספרייה res/layout/ של הפרויקט. פרטים נוספים זמינים בהנחיות לעיצוב.

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

‫RemoteViews תומך גם ב-ViewStub, שהוא View בלתי נראה בגודל אפס שאפשר להשתמש בו כדי להרחיב משאבי פריסה בזמן ריצה.

תמיכה בהתנהגות עם שמירת מצב

ב-Android 12 נוספה תמיכה בהתנהגות עם שמירת מצב באמצעות הרכיבים הקיימים הבאים:

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

דוגמה לווידג'ט של רשימת קניות שמציג התנהגות עם שמירת מצב
איור 3. דוגמה להתנהגות עם שמירת מצב.

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

Kotlin

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true)

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2)

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
        R.id.my_checkbox,
        RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent)
)

Java

// Check the view.
remoteView.setCompoundButtonChecked(R.id.my_checkbox, true);

// Check a radio group.
remoteView.setRadioGroupChecked(R.id.my_radio_group, R.id.radio_button_2);

// Listen for check changes. The intent has an extra with the key
// EXTRA_CHECKED that specifies the current checked state of the view.
remoteView.setOnCheckedChangeResponse(
    R.id.my_checkbox,
    RemoteViews.RemoteResponse.fromPendingIntent(onCheckedChangePendingIntent));

צריך לספק שני פריסות: אחת שמטרגטת מכשירים עם Android מגרסה 12 ומעלה ב-res/layout-v31, והשנייה שמטרגטת גרסאות קודמות של Android מגרסה 11 ומטה בתיקיית ברירת המחדל res/layout.

הטמעה של פינות מעוגלות

חישוב הרקע החיצוני והרדיוסים הפנימיים הפרופורציונליים הוא סטנדרטי ומשותף. בפיתוח בגישת Compose-first, אפשר להגדיר את זה באופן דינמי ב-Kotlin לצד משאבי עיצוב בהתאמה אישית.

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