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

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

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

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

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

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

אובייקט AppWidgetProviderInfo

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

כיתה AppWidgetProvider

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

הצגת הפריסה

מגדירה את הפריסה הראשונית של הווידג'ט. הפריסה מוגדרת XML, כפי שמתואר במסמך הזה.

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

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

• החל מ-Android 12 (רמת API 31), אפשר לספק ברירת מחדל את התצורה ולאפשר למשתמשים להגדיר מחדש את הווידג'ט מאוחר יותר. אפשר לעיין בקטע שימוש הגדרות ברירת המחדל של הווידג'ט והפעלה משתמשים להגדיר מחדש ווידג'טים שמוקמו אפשר לקבל פרטים נוספים.
• ב-Android 11 (רמת API 30) ומטה, הפעילות הזו מופעלת בכל פעם המשתמש מוסיף את הווידג'ט למסך הבית.

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

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

האובייקט AppWidgetProviderInfo מגדיר את התכונות החיוניות של ווידג'ט. מגדירים את האובייקט AppWidgetProviderInfo בקובץ משאבים מסוג XML באמצעות <appwidget-provider> ולשמור אותו בתיקייה של הפרויקט res/xml/.

אפשר לראות זאת בדוגמה הבאה:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/example_loading_appwidget"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

מאפייני המידה של הווידג'ט

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

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

בטבלה הבאה מתוארים המאפיינים של <appwidget-provider> שקשורים עד לגודל הווידג'ט:

דוגמה

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

• תא רשת הוא ברוחב של 30dp וגובה של 50dp.
• מפרט המאפיינים הבא סופק:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

החל מ-Android 12:

שימוש במאפיינים targetCellWidth ו-targetCellHeight כברירת המחדל הגודל של הווידג'ט.

גודל הווידג'ט הוא 2x2 כברירת מחדל. ניתן להקטין את גודל הווידג'ט ל-2x1 או עד 4x3.

Android 11 ומטה:

אפשר להשתמש במאפיינים minWidth ו-minHeight כדי לחשב את גודל ברירת המחדל של לווידג'ט.

רוחב ברירת המחדל = Math.ceil(80 / 30) = 3

גובה ברירת המחדל = Math.ceil(80 / 50) = 2

גודל הווידג'ט הוא 3x2 כברירת מחדל. ניתן להקטין את גודל הווידג'ט ל-2x1 או עד למסך מלא.

מאפייני ווידג'ט נוספים

בטבלה הבאה מתוארים המאפיינים של <appwidget-provider> שקשורים לתכונות שאינן גודל הווידג'ט.

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

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

הצהרה על ווידג'ט במניפסט

קודם צריך להצהיר על הכיתה AppWidgetProvider ב-AndroidManifest.xml של האפליקציה כפי שמוצג בדוגמה הבאה:

<receiver android:name="ExampleAppWidgetProvider"
                 android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/example_appwidget_info" />
</receiver>

לרכיב <receiver> נדרש המאפיין android:name, שמציין AppWidgetProvider שמשמש את הווידג'ט. אסור לייצא את הרכיב אלא אם נדרש תהליך נפרד לשידור אל AppWidgetProvider, בדרך כלל זה לא המצב.

הרכיב <intent-filter> חייב לכלול רכיב <action> עם מאפיין android:name. המאפיין הזה מציין שהמאפיין AppWidgetProvider מקבל/ת את ACTION_APPWIDGET_UPDATE שידור. זהו השידור היחיד שעליך להצהיר עליו במפורש. AppWidgetManager שולח באופן אוטומטי את כל שידורי הווידג'ט האחרים ל-AppWidgetProvider בתור הנחוצים.

הרכיב <meta-data> מציין את המשאב AppWidgetProviderInfo ו מחייב את המאפיינים הבאים:

• android:name: מציין את שם המטא-נתונים. כדאי להשתמש android.appwidget.provider כדי לזהות את הנתונים בתור מתאר AppWidgetProviderInfo.
• android:resource: מציין את המשאב AppWidgetProviderInfo המיקום.

הטמעת המחלקה AppWidgetProvider

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

onUpdate()

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

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

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

onAppWidgetOptionsChanged()

האפשרות הזו נקראת כשהווידג'ט ממוקם לראשונה ובכל פעם שהווידג'ט גודל התמונה השתנה. אפשר להשתמש בקריאה החוזרת (callback) הזו כדי להציג או להסתיר תוכן על סמך גודל הווידג'ט טווחים. בודקים את טווחי הגדלים, והחל מ-Android 12, לרשימת הגדלים האפשריים לווידג'ט שיכול להיות - באמצעות getAppWidgetOptions() הפונקציה מחזירה את הערך Bundle שכולל את הבאים:

• OPTION_APPWIDGET_MIN_WIDTH: מכיל את הגבול התחתון של הרוחב, ביחידות dp, של מופע ווידג'ט.
• OPTION_APPWIDGET_MIN_HEIGHT: מכיל את הגבול התחתון של הגובה, ביחידות dp, של מופע ווידג'ט.
• OPTION_APPWIDGET_MAX_WIDTH: מכיל את הגבול העליון של הרוחב, ביחידות dp, של מופע ווידג'ט.
• OPTION_APPWIDGET_MAX_HEIGHT: מכיל את הגבול העליון של הגובה, ביחידות dp, של מופע ווידג'ט.
• OPTION_APPWIDGET_SIZES: מכיל את רשימת הגדלים האפשריים (List<SizeF>), ביחידות dp, לווידג'ט הזה יכולה לקחת אותו. התכונה הושקה ב-Android 12.

onDeleted(Context, int[])

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

onEnabled(Context)

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

onDisabled(Context)

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

onReceive(Context, Intent)

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

עליך להצהיר על הטמעת הכיתה AppWidgetProvider כשידור של מקלט באמצעות הרכיב <receiver> בAndroidManifest. ראו הצהרה על במניפסט שבדף הזה.

טיפול באירועים באמצעות המחלקה onUpdate()

הקריאה החוזרת החשובה ביותר של AppWidgetProvider היא onUpdate(), כי היא נשלחת קריאה כשכל ווידג'ט מתווסף למארח, אלא אם משתמשים בהגדרה פעילות ללא הדגל configuration_optional. אם בווידג'ט אפשר להשתמש אירועי אינטראקציה של משתמשים, ואז רושמים את הגורמים המטפלים באירועים בקריאה החוזרת (callback). אם המיקום הווידג'ט לא יוצר קבצים או מסדי נתונים זמניים ולא מבצע פעולות אחרות שדורש ניקוי, אז onUpdate() עשויה להיות שיטת הקריאה החוזרת היחידה צריך להגדיר.

לדוגמה, אם אתם רוצים ווידג'ט עם לחצן שמפעיל פעילות מקישים, אפשר להשתמש בשיטה הבאה להטמעה של AppWidgetProvider:

class ExampleAppWidgetProvider : AppWidgetProvider() {

    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray
    ) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        appWidgetIds.forEach { appWidgetId ->
            // Create an Intent to launch ExampleActivity.
            val pendingIntent: PendingIntent = PendingIntent.getActivity(
                    /* context = */ context,
                    /* requestCode = */  0,
                    /* intent = */ Intent(context, ExampleActivity::class.java),
                    /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
            )

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            val views: RemoteViews = RemoteViews(
                    context.packageName,
                    R.layout.appwidget_provider_layout
            ).apply {
                setOnClickPendingIntent(R.id.button, pendingIntent)
            }

            // Tell the AppWidgetManager to perform an update on the current
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views)
        }
    }
}

public class ExampleAppWidgetProvider extends AppWidgetProvider {

    public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
        // Perform this loop procedure for each widget that belongs to this
        // provider.
        for (int i=0; i < appWidgetIds.length; i++) {
            int appWidgetId = appWidgetIds[i];
            // Create an Intent to launch ExampleActivity
            Intent intent = new Intent(context, ExampleActivity.class);
            PendingIntent pendingIntent = PendingIntent.getActivity(
                /* context = */ context,
                /* requestCode = */ 0,
                /* intent = */ intent,
                /* flags = */ PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
            );

            // Get the layout for the widget and attach an onClick listener to
            // the button.
            RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget_layout);
            views.setOnClickPendingIntent(R.id.button, pendingIntent);

            // Tell the AppWidgetManager to perform an update on the current app
            // widget.
            appWidgetManager.updateAppWidget(appWidgetId, views);
        }
    }
}

AppWidgetProvider מגדיר רק את השיטה onUpdate(), באמצעותה כדי ליצור PendingIntent שיופעל Activity ומצרף אותו באמצעות setOnClickPendingIntent(int, PendingIntent). היא כוללת לולאה שחוזרת על עצמה כל ערך ב-appWidgetIds, שהוא מערך של מזהים שמזהים כל ווידג'ט שנוצר על ידי הספק הזה. אם המשתמש יוצר יותר ממופע אחד של הווידג'ט, אז כולם מתעדכנים בו-זמנית. עם זאת, רק לוח זמנים אחד של updatePeriodMillis מנוהלת עבור כל המופעים של הווידג'ט. לדוגמה, אם לוח הזמנים לעדכון מוגדרת לכל שעתיים, ונוסף מופע שני של הווידג'ט שעה אחרי הראשונה, ואז שניהם מעודכנים בתקופה שהוגדרה על ידי המערכת תתעלם מתקופת העדכון הראשונה. שניהם מתעדכנים כל שתיים ולא בכל שעה.

לצפייה ExampleAppWidgetProvider.java כדי לקבל פרטים נוספים על הכיתה.

קבלת כוונות שידור של ווידג'ט

AppWidgetProvider הוא שיעור נוחות. אם רוצים לקבל את הווידג'ט שידורים חיים ישירות, אפשר להטמיע BroadcastReceiver משלך או לשנות מברירת המחדל ה קריאה חוזרת (callback) של onReceive(Context,Intent). הכוונות צריכות להיות חשובות הבאים:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

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

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

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

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

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

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

• CheckBox

• Switch

• RadioButton

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

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

// 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)
)

// 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.

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

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

• system_app_widget_background_radius: הרדיוס של רקע הווידג'ט, שאף פעם לא גדול יותר 28dp

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

בדוגמה הבאה מוצג ווידג'ט שמשתמש בו system_app_widget_background_radius לפינה של הווידג'ט system_app_widget_inner_radius לתצוגות בתוך הווידג'ט.

1 פינת הווידג'ט.

2 פינת תצוגה בתוך הווידג'ט.

שיקולים חשובים לגבי פינות מעוגלות

• מרכזי אפליקציות של צד שלישי ויצרני מכשירים יכולים לבטל את הפרמטר system_app_widget_background_radius יהיה קטן מ-28dp. הערך של הפרמטר system_app_widget_inner_radius הוא תמיד 8dp פחות מ- הערך של system_app_widget_background_radius.
• אם בווידג'ט לא נעשה שימוש ב-@android:id/background או בהגדרת רקע שמקצר את התוכן שלו לפי המתאר — באמצעות android:clipToOutline מוגדרת ל-true - מרכז האפליקציות מזהה באופן אוטומטי את הרקע קליפים את הווידג'ט באמצעות מלבן עם פינות מעוגלות של עד 16dp. בקטע מוודאים שהווידג'ט תואם Android 12.

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

<resources>
  <attr name="backgroundRadius" format="dimension" />
</resources>

<resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
</resources>

<resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
</resources>

<shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  ...
</shape>

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
  ...
  android:background="@drawable/my_widget_background" />