Android Widget (App Widget) 是嵌入在 Launcher (桌面) 或其他宿主應用中的微型應用視圖。其生命週期由系統服務 AppWidgetService 統一管理,跨進程通過 RemoteViews 機制渲染 UI,確保宿主進程安全性。
BroadcastReceiver 子類,接收更新/啟用/停用/刪除廣播System Server 啟動
│
▼
AppWidgetService 建立實例 (system_server 進程)
│
▼
SystemReady() 呼叫
│
├─▶ 1. 掃描已安裝套件,解析 AppWidgetProvider
│ ├─ Intent Filter: ACTION_APPWIDGET_UPDATE
│ └─ Meta-data: android.appwidget.provider → xml 資源
│
├─▶ 2. 讀取 /data/system/appwidgets.xml
│ ├─ 已綁定 Widget 執行個體資訊 (ID, Provider, Host, 選項)
│ └─ 還原至記憶體快取
│
└─▶ 3. 註冊系統廣播接收器
├─ ACTION_BOOT_COMPLETED
├─ ACTION_PACKAGE_ADDED/CHANGED/REMOVED
└─ ACTION_EXTERNAL_APPLICATIONS_AVAILABLE
│
▼
Launcher 啟動完成 → 發送 ACTION_BOOT_COMPLETED
│
▼
AppWidgetService 接收 → 遍歷已綁定 Widget
│
├─▶ 發送 ACTION_APPWIDGET_ENABLED (Provider 首次建立)
├─▶ 發送 ACTION_APPWIDGET_UPDATE (觸發 onUpdate)
└─▶ 宿主 (Launcher) 綁定 RemoteViews 顯示
系統掃描所有已安裝 APK 的 AndroidManifest.xml,尋找:
<receiver android:name=".MyWidgetProvider"
android:exported="true"
android:label="@string/widget_name">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
</intent-filter>
<meta-data
android:name="android.appwidget.provider"
android:resource="@xml/widget_info" />
</receiver>
@xml/widget_info 定義 Widget 中繼資料:
<appwidget-provider xmlns:android="https://schemas.android.com/apk/res/android"
android:minWidth="180dp"
android:minHeight="110dp"
android:targetCellWidth="3"
android:targetCellHeight="2"
android:maxResizeWidth="360dp"
android:maxResizeHeight="220dp"
android:updatePeriodMillis="1800000" <!-- 30 分鐘更新一次 -->
android:initialLayout="@layout/widget_initial"
android:resizeMode="horizontal|vertical"
android:widgetCategory="home_screen|keyguard"
android:configure="com.example.ConfigActivity"
android:previewImage="@drawable/widget_preview" />
/data/system/appwidgets.xml 記錄每個 Widget 實例:
<appwidgets>
<appwidget
id="12345"
provider="ComponentInfo{com.example/com.example.MyWidgetProvider}"
host="com.android.launcher3"
previewLayout="@layout/widget_preview"
scaledWidth="180"
scaledHeight="110"
spanX="3"
spanY="2"
options="Bundle[{appWidgetCategory=1}]" />
</appwidgets>
// AppWidgetService 內部邏輯簡化版
private void handleBootCompleted() {
for (AppWidgetProviderInfo provider : providers) {
// 發送 ENABLED 廣播 (Provider 第一次建立實例時)
if (provider.isFirstInstance()) {
sendBroadcast(new Intent(AppWidgetManager.ACTION_APPWIDGET_ENABLED)
.setComponent(provider.provider));
}
}
// 遍歷所有已綁定的 Widget ID
for (int appWidgetId : boundWidgetIds) {
// 發送 UPDATE 廣播,Provider 在 onUpdate 中更新 RemoteViews
Bundle options = getWidgetOptions(appWidgetId);
sendUpdateBroadcast(appWidgetId, options);
}
}
public class MyWidgetProvider extends AppWidgetProvider {
// 1. 首個 Widget 實例建立時呼叫 (整個應用生命週期僅一次)
@Override
public void onEnabled(Context context) {
super.onEnabled(context);
// 初始化全域資源:資料庫連線、網路監聽、定時任務
WidgetDataRepository.init(context);
ScheduleManager.startPeriodicUpdate(context);
}
// 2. 每次更新週期到達、使用者新增 Widget、配置變更時呼叫
@Override
public void onUpdate(Context context, AppWidgetManager appWidgetManager, int[] appWidgetIds) {
super.onUpdate(context, appWidgetManager, appWidgetIds);
for (int appWidgetId : appWidgetIds) {
RemoteViews views = buildRemoteViews(context, appWidgetId);
appWidgetManager.updateAppWidget(appWidgetId, views);
}
}
// 3. Widget 實例被移除時呼叫 (最後一個實例移除時觸發 onDisabled)
@Override
public void onDeleted(Context context, int[] appWidgetIds) {
super.onDeleted(context, appWidgetIds);
// 清理該 ID 專屬資源:資料庫記錄、快取檔案
for (int id : appWidgetIds) {
WidgetDataRepository.cleanupForWidget(id);
}
}
// 4. 最後一個 Widget 實例移除時呼叫
@Override
public void onDisabled(Context context) {
super.onDisabled(context);
// 釋放全域資源:停止定時任務、關閉資料庫、取消註冊接收器
ScheduleManager.stopPeriodicUpdate(context);
WidgetDataRepository.shutdown();
}
// 5. Widget 尺寸變更時呼叫 (API 16+)
@Override
public void onAppWidgetOptionsChanged(Context context, AppWidgetManager appWidgetManager,
int appWidgetId, Bundle newOptions) {
super.onAppWidgetOptionsChanged(context, appWidgetManager, appWidgetId, newOptions);
// 根據新尺寸調整 RemoteViews 佈局
RemoteViews views = buildRemoteViewsForSize(context, appWidgetId, newOptions);
appWidgetManager.updateAppWidget(appWidgetId, views);
}
// 6. 處理 Widget 內按鈕點擊 (PendingIntent)
@Override
public void onReceive(Context context, Intent intent) {
super.onReceive(context, intent);
if (ACTION_CUSTOM_CLICK.equals(intent.getAction())) {
int appWidgetId = intent.getIntExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, -1);
handleCustomClick(context, appWidgetId);
}
}
private RemoteViews buildRemoteViews(Context context, int appWidgetId) {
RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.widget_layout);
// 設定文字
views.setTextViewText(R.id.title, "Widget 標題 " + System.currentTimeMillis());
// 設定點擊事件 (啟動 Activity)
Intent launchIntent = new Intent(context, MainActivity.class);
PendingIntent pendingIntent = PendingIntent.getActivity(
context, 0, launchIntent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT);
views.setOnClickPendingIntent(R.id.container, pendingIntent);
// 設定自訂動作 (Service/Receiver)
Intent customIntent = new Intent(ACTION_CUSTOM_CLICK)
.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
PendingIntent customPending = PendingIntent.getBroadcast(
context, appWidgetId, customIntent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_UPDATE_CURRENT);
views.setOnClickPendingIntent(R.id.refresh_btn, customPending);
return views;
}
}
AlarmManager.setExactAndAllowWhileIdle() + WorkManager若 android:configure 設定,使用者新增 Widget 時先啟動配置 Activity,需手動回傳結果:
public class WidgetConfigActivity extends AppCompatActivity {
private int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.widget_config);
// 解析 Intent 取得 Widget ID
Intent intent = getIntent();
Bundle extras = intent.getExtras();
if (extras != null) {
appWidgetId = extras.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID, AppWidgetManager.INVALID_APPWIDGET_ID);
}
// 若無效 ID,直接結束
if (appWidgetId == AppWidgetManager.INVALID_APPWIDGET_ID) {
finish();
return;
}
// 設定結果為取消,使用者若按返回鍵不建立 Widget
setResult(RESULT_CANCELED);
}
public void onConfirmClick(View view) {
// 儲存配置 (如 SharedPreferences keyed by appWidgetId)
saveWidgetConfig(appWidgetId);
// 觸發首次更新
AppWidgetManager manager = AppWidgetManager.getInstance(this);
MyWidgetProvider provider = new MyWidgetProvider();
provider.onUpdate(this, manager, new int[]{appWidgetId});
// 回傳成功結果
Intent result = new Intent();
result.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(RESULT_OK, result);
finish();
}
}
| 問題 | 原因 | 解決方案 |
|---|---|---|
| Widget 不顯示在選單中 | Manifest 缺少 intent-filter 或 meta-data | 檢查 ACTION_APPWIDGET_UPDATE、android.appwidget.provider |
| 開機後 Widget 空白 | onUpdate 未正確建構 RemoteViews | 檢查 buildRemoteViews 邏輯、佈局資源 ID |
| 點擊無反應 | PendingIntent 旗標錯誤 (API 23+ 需 FLAG_IMMUTABLE/FLAG_MUTABLE) | 使用 PendingIntent.FLAG_IMMUTABLE | FLAG_UPDATE_CURRENT |
| 更新不生效 | updatePeriodMillis 太短、系統批次延遲 | 改用 WorkManager + setExactAndAllowWhileIdle |
| 配置 Activity 不關閉 | 未呼叫 setResult(RESULT_OK) 並 finish() | 確認配置完成後正確回傳 |
onAppWidgetOptionsChanged 動態適配onDisabled 完整清理,避免服務洩漏