אפשר להגדיר ווידג'טים של אפליקציות. לדוגמה, ווידג'ט של שעון יכול לאפשר למשתמשים להגדיר איזה אזור זמן יוצג.
אם רוצים לאפשר למשתמשים לקבוע את הגדרות הווידג'ט, צריך ליצור ווידג'ט
הגדרה Activity
. הפעילות הזו היא
מופעל אוטומטית על ידי מארח הווידג'ט של האפליקציה בזמן יצירת הווידג'ט.
ואילך, בהתאם לאפשרויות ההגדרה
להגדיר.
הצהרה על פעילות ההגדרות האישיות
יש להצהיר על פעילות ההגדרה כפעילות רגילה במניפסט של Android
חדש. מארח הווידג'ט של האפליקציה מפעיל אותו באמצעות
ACTION_APPWIDGET_CONFIGURE
פעולה, ולכן הפעילות צריכה לקבל את הכוונה הזו. לדוגמה:
<activity android:name=".ExampleAppWidgetConfigurationActivity">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
</intent-filter>
</activity>
מצהירים על הפעילות בקובץ AppWidgetProviderInfo.xml
באמצעות
android:configure
. מידע נוסף על
להצהיר על הקובץ הזה כאן יש דוגמה
איך להצהיר (declare) על פעילות ההגדרות האישיות:
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
...
android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
... >
</appwidget-provider>
הפעילות מוצהרת עם מרחב שמות שמוגדר במלואו, כי מרכז האפליקציות מפנה אליו מחוץ להיקף החבילה.
זה כל מה שצריך כדי להתחיל פעילות של הגדרות אישיות. בשלב הבא, צריך להטמיע את הפעילות בפועל.
הטמעת הפעילות של מערך ההגדרות האישיות
יש שתי נקודות שחשוב לזכור כשמטמיעים את הפעילות:
- המארח של ווידג'ט האפליקציה קורא לפעילות ההגדרות ולתצורה
הפעילות חייבת תמיד להחזיר תוצאה. התוצאה חייבת לכלול את הווידג'ט של האפליקציה
המזהה שהועבר על ידי הכוונה שגרמה להפעלת הפעילות – נשמר ב-Intent
תוספות בתור
EXTRA_APPWIDGET_ID
- המערכת לא שולחת את
ACTION_APPWIDGET_UPDATE
בשידור חי כשמתבצעת פעילות של מערך הגדרות אישיות, כלומר לא להפעיל את ה-methodonUpdate()
בזמן יצירת הווידג'ט. באחריות הפעילות של ההגדרות האישיות לבקש עדכון מ-AppWidgetManager
כשיוצרים את הווידג'ט בפעם הראשונה. אבל, לפעמים נשלחת לפונקציהonUpdate()
כדי לבצע עדכונים נוספים – המערכת מדלגת עליה רק בפעם הראשונה.
בקטע הבא אפשר למצוא דוגמה להחזרת כתוצאה מההגדרה ומעדכנים את הווידג'ט.
עדכון הווידג'ט מהפעילות של ההגדרה
כאשר ווידג'ט משתמש בפעילות של מערך הגדרות אישיות, האחריות
הפעילות לעדכון הווידג'ט כשתהליך ההגדרה הושלם. אפשר לעשות זאת
באמצעות בקשת עדכון ישירות
AppWidgetManager
הנה סיכום של ההליך לעדכון הווידג'ט ולסגירה שלו פעילות הגדרות אישיות:
מקבלים את המזהה של הווידג'ט של האפליקציה לפי הכוונה שהפעילה את הפעילות:
Kotlin
val appWidgetId = intent?.extras?.getInt( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
Java
Intent intent = getIntent(); Bundle extras = intent.getExtras(); int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID; if (extras != null) { appWidgetId = extras.getInt( AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID); }
מגדירים את תוצאת הפעילות ל-
RESULT_CANCELED
.כך, אם המשתמש יוצא מהפעילות לפני שהוא מגיע לסוף, המערכת מודיעה למארח הווידג'ט של האפליקציה שההגדרה בוטלה המארח לא מוסיף את הווידג'ט:
Kotlin
val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) setResult(Activity.RESULT_CANCELED, resultValue)
Java
int resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); setResult(Activity.RESULT_CANCELED, resultValue);
מגדירים את הווידג'ט בהתאם להעדפות של המשתמש.
בסיום ההגדרה, מקבלים מופע
AppWidgetManager
בהתקשרות אלgetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
לעדכן את הווידג'ט באמצעות הפריסה של
RemoteViews
באמצעות התקשרותupdateAppWidget(int,RemoteViews)
:Kotlin
val views = RemoteViews(context.packageName, R.layout.example_appwidget) appWidgetManager.updateAppWidget(appWidgetId, views)
Java
RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget); appWidgetManager.updateAppWidget(appWidgetId, views);
יוצרים את כוונת ההחזרה, מגדירים אותה עם תוצאת הפעילות סיום הפעילות:
Kotlin
val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) setResult(Activity.RESULT_OK, resultValue) finish()
Java
Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); setResult(RESULT_OK, resultValue); finish();
לצפייה
ListWidgetConfigureActivity.kt
למשל, ב-GitHub.
אפשרויות ההגדרה של הווידג'ט
כברירת מחדל, המארח של ווידג'ט האפליקציה מפעיל את פעילות ההגדרה רק פעם אחת, מיד אחרי שהמשתמש מוסיף את הווידג'ט למסך הבית. אבל, הוא יכול לציין אפשרויות שיאפשרו למשתמשים להגדיר מחדש ווידג'טים קיימים אפשר לדלג על ההגדרה הראשונית של הווידג'ט על ידי הגדרת ברירת המחדל של הווידג'ט.
המשתמשים יכולים להגדיר מחדש ווידג'טים שמוקמו
כדי לאפשר למשתמשים להגדיר מחדש ווידג'טים קיימים, צריך לציין את
reconfigurable
לסמן ב-
widgetFeatures
של appwidget-provider
. מומלץ לעיין במדריך להצהרה על
קובץ אחד (AppWidgetProviderInfo.xml
) לפרטים נוספים
מידע. לדוגמה:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
המשתמשים יכולים להגדיר מחדש את הווידג'ט שלהם על ידי נגיעה ו החזקת הווידג'ט והקשה הלחצן הגדרה מחדש, עם התווית 1 בתרשים 1.
![הלחצן מופיע בפינה השמאלית התחתונה](https://developer.android.google.cn/static/images/appwidgets/widget-reconfigure-button.png?authuser=7&hl=he)
שימוש בהגדרות ברירת המחדל של הווידג'ט
כדי לספק חוויית שימוש חלקה יותר בווידג'ט, המשתמשים יכולים לדלג על
שלב ההגדרה הראשוני. כדי לעשות את זה, צריך לציין
configuration_optional
ו-reconfigurable
דגלים בשדה widgetFeatures
. ההגדרה הזו עוקפת
הפעלת פעילות ההגדרות האישיות אחרי שמשתמש מוסיף את הווידג'ט. כפי שצוין
בעבר, המשתמש עדיין יכול להגדיר מחדש את הווידג'ט
לאחר מכן. לדוגמה, ווידג'ט שעון יכול לעקוף את התצורה הראשונית
להציג את אזור הזמן של המכשיר כברירת מחדל.
דוגמה לאופן שבו מסמנים את פעילות ההגדרות האישיות שניתן להגדיר מחדש ואופציונלי:
<appwidget-provider
android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>