萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> Android 開發

Android 開機載入 Widget 流程深度解析

AppWidget 架構概覽

Android Widget (App Widget) 是嵌入在 Launcher (桌面) 或其他宿主應用中的微型應用視圖。其生命週期由系統服務 AppWidgetService 統一管理,跨進程通過 RemoteViews 機制渲染 UI,確保宿主進程安全性。

核心類別職責

  • AppWidgetService (系統服務):Widget 生命週期管理、提供者註冊、更新排程、綁定管理
  • AppWidgetProvider (開發者實作):BroadcastReceiver 子類,接收更新/啟用/停用/刪除廣播
  • AppWidgetHost (宿主端):Launcher 實作,負責分配 ID、綁定視圖、處理點擊
  • RemoteViews:跨進程 UI 描述,支援有限 View 集合與動作綁定

開機啟動流程時序圖

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 顯示

關鍵步驟詳細分析

步驟 1:掃描 Widget 提供者

系統掃描所有已安裝 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" />

步驟 2:還原已綁定 Widget 狀態

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

步驟 3:BOOT_COMPLETED 觸發更新流程

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

AppWidgetProvider 核心回調方法

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;
    }
}

定時更新機制 (updatePeriodMillis)

  • 最小間隔 30 分鐘 (1800000ms),系統會對齊批次執行以省電
  • 裝置睡眠時不會喚醒執行,喚醒後會補發
  • 需精確控制時機請用 AlarmManager.setExactAndAllowWhileIdle() + WorkManager

進階:Widget 配置 Activity

若 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()確認配置完成後正確回傳

最佳實踐總結

  1. 最小化 RemoteViews 操作:只更新必要 View,避免完整重建
  2. 離線快取資料:Widget 可能在無網路時顯示,預先快取
  3. 使用 WorkManager 替代 updatePeriodMillis:更精確、支援條件觸發、電池優化友善
  4. 針對不同尺寸提供佈局:onAppWidgetOptionsChanged 動態適配
  5. 釋放資源:onDisabled 完整清理,避免服務洩漏
copyright © 萬盛學電腦網 all rights reserved