建立簡易小工具

應用程式小工具是小型的應用程式檢視畫面,可以嵌入其他應用程式 (例如主畫面),並定期接收更新。這些檢視畫面在使用者介面中稱為「小工具」,您可以使用應用程式小工具供應商 (或小工具供應商) 發布這些檢視畫面。存放其他小工具的應用程式元件稱為應用程式小工具主機 (或小工具主機)。圖 1 顯示音樂小工具範例:

音樂小工具範例
圖 1 音樂小工具範例。

本文件說明如何使用小工具供應商發布小工具。如要進一步瞭解如何建立自己的 AppWidgetHost 以代管應用程式小工具,請參閱「建構小工具主機」。

如要瞭解如何設計小工具,請參閱「應用程式小工具總覽」。

小工具元件

如要建立小工具,您必須具備下列基本元件:

AppWidgetProviderInfo 物件
說明小工具的中繼資料,例如小工具的版面配置、更新頻率和 AppWidgetProvider 類別。AppWidgetProviderInfo在 XML 中定義,如本文件所述。
AppWidgetProvider 類別
定義基本方法,讓您透過程式輔助方式與小工具互動。透過此方法,當小工具更新、啟用、停用或刪除時,您就會收到廣播訊息。您在資訊清單中宣告 AppWidgetProvider,然後按照本文所述的方式實作
查看版面配置
定義小工具的初始版面配置。如本文件所述,會透過 XML 定義

圖 2 顯示這些元件如何融入整體應用程式小工具處理流程。

應用程式小工具處理流程
圖 2. 應用程式小工具處理流程。

如果小工具需要使用者設定,請實作應用程式小工具設定活動。這個活動可讓使用者修改小工具設定,例如時鐘小工具的時區。

我們也建議您參考下列改善項目:靈活的小工具版面配置其他強化項目進階小工具集合小工具建構小工具主機

宣告 AppWidgetProviderInfo XML

AppWidgetProviderInfo 物件會定義小工具的基本性質。使用單一 <appwidget-provider> 元素在 XML 資源檔案中定義 AppWidgetProviderInfo 物件,並儲存至專案的 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> 屬性:

屬性與說明
targetCellWidthtargetCellHeight (Android 12)、minWidthminHeight
  • 自 Android 12 起,targetCellWidthtargetCellHeight 屬性會以格線儲存格方式指定小工具的預設大小。在 Android 11 以下版本中,系統會忽略這些屬性,如果主畫面不支援格狀版面配置,可以忽略這些屬性。
  • minWidthminHeight 屬性會以 dp 指定小工具的預設大小。如果小工具的最小寬度或高度值與儲存格尺寸不符,系統會將值四捨五入至最接近的儲存格大小。
建議您同時指定 targetCellWidthtargetCellHeight 以及 minWidthminHeight 這兩組屬性,這樣一來,如果使用者的裝置不支援 targetCellWidthtargetCellHeight,應用程式就能改回使用 minWidthminHeight。如果支援,targetCellWidthtargetCellHeight 屬性的優先順序高於 minWidthminHeight 屬性。
minResizeWidthminResizeHeight 指定小工具的絕對最小尺寸。這些值會指定小工具難以辨識或無法使用的大小。使用者可以透過這些屬性,將小工具調整為小於預設小工具的大小。如果的值大於 minWidth,或是未啟用水平調整大小功能,系統會忽略 minResizeWidth 屬性。詳情請參閱 resizeMode。同樣地,如果 minResizeHeight 屬性大於 minHeight,或是未啟用垂直調整大小功能,系統會忽略該屬性。
maxResizeWidthmaxResizeHeight 指定小工具的建議大小上限。如果這些值並非格線儲存格維度的倍數,系統會將這些值四捨五入至最接近的儲存格大小。如果 maxResizeWidth 小於 minWidth,或是未啟用水平調整大小功能,系統會忽略該屬性。查看「resizeMode」。同樣地,如果 maxResizeHeight 屬性大於 minHeight,或是未啟用垂直大小調整功能,系統會忽略該屬性。相關元素已在 Android 12 中推出。
resizeMode 指定可以調整小工具大小的規則。您可以使用這項屬性,讓主畫面小工具可水平、垂直或同時調整兩個軸的大小。使用者按住小工具即可顯示調整大小控點,然後拖曳水平或垂直控點,變更版面配置格線上的尺寸。resizeMode 屬性的值包括 horizontalverticalnone。如要將小工具宣告為可水平和垂直調整大小,請使用 horizontal|vertical

範例

我們假設上表的屬性對小工具大小的影響如下:

  • 格線儲存格寬度為 30 dp,高度為 50 dp。
  • 我們提供下列屬性規格:
<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 開始:

使用 targetCellWidthtargetCellHeight 屬性做為小工具的預設大小。

小工具的大小預設為 2x2。小工具可調整為 2x1 或 4x3。

Android 11 以下版本:

使用 minWidthminHeight 屬性計算小工具的預設大小。

預設寬度 = Math.ceil(80 / 30) = 3

預設高度 = Math.ceil(80 / 50) = 2

小工具的大小預設為 3x2。小工具的大小可縮小為 2x1,或最大化至全螢幕。

其他小工具屬性

下表說明與小工具大小以外的屬性相關的 <appwidget-provider> 屬性。

屬性與說明
updatePeriodMillis 定義小工具架構透過呼叫 onUpdate() 回呼方法,從 AppWidgetProvider 要求更新的頻率。但不保證會即時更新這個值並採用這個值,因此建議您盡可能不頻繁更新,最多一小時一次,以節省電池電力。如需選擇適當更新週期的完整注意事項清單,請參閱「更新小工具內容的最佳化」。
initialLayout 指向定義小工具版面配置的版面配置資源。
configure 定義當使用者新增小工具時要啟動的活動,以便設定小工具屬性。請參閱「允許使用者設定小工具」。從 Android 12 開始,應用程式可以略過初始設定。詳情請參閱「使用小工具的預設設定」。
description 指定要為小工具顯示的小工具挑選器說明。相關元素已在 Android 12 中推出。
previewLayout (Android 12) 和 previewImage (Android 11 以下版本)
  • 自 Android 12 起,previewLayout 屬性會指定可擴充的預覽畫面,方便您以 XML 版面配置的形式提供預覽畫面,並將該版面配置設為小工具預設大小。在理想情況下,這項屬性指定的版面配置 XML 會與包含實際預設值的實際小工具版面配置 XML 相同。
  • 在 Android 11 以下版本中,previewImage 屬性可指定小工具設定後顯示的預覽畫面,使用者選取應用程式小工具時會看到此畫面。如未提供,使用者將看到應用程式的啟動器圖示。這個欄位對應 AndroidManifest.xml 檔案 <receiver> 元素中的 android:previewImage 屬性。
注意:建議您同時指定 previewImagepreviewLayout 屬性,以便在使用者裝置不支援 previewLayout 時,讓應用程式改回使用 previewImage。詳情請參閱「與可擴充小工具預覽的回溯相容性」。
autoAdvanceViewId 指定小工具子檢視畫面的檢視畫面 ID (由小工具主機自動進階)。
widgetCategory 宣告小工具是否能顯示在主畫面 (home_screen)、螢幕鎖定畫面 (keyguard),或同時顯示在這兩個畫面中。如果是 Android 5.0 以上版本,則只有 home_screen 有效。
widgetFeatures 宣告小工具支援的功能。舉例來說,如果您希望小工具在使用者新增小工具時採用預設設定,請同時指定 configuration_optionalreconfigurable 標記。這樣就不必在使用者新增小工具後啟動設定活動。使用者之後仍可重新設定小工具

使用 AppWidgetProvider 類別處理小工具廣播

AppWidgetProvider 類別會處理小工具廣播,並根據小工俱生命週期事件更新小工具。以下各節說明如何在資訊清單中宣告 AppWidgetProvider 並實作。

在資訊清單中宣告小工具

首先,在應用程式的 AndroidManifest.xml 檔案中宣告 AppWidgetProvider 類別,如以下範例所示:

<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> 元素必須包含具備 android:name 屬性的 <action> 元素。這項屬性可指定 AppWidgetProvider 接受 ACTION_APPWIDGET_UPDATE 廣播。這是唯一必須明確宣告的廣播訊息。AppWidgetManager 會視需要自動將所有其他小工具廣播傳送至 AppWidgetProvider

<meta-data> 元素會指定 AppWidgetProviderInfo 資源,且需要下列屬性:

  • android:name:指定中繼資料名稱。使用 android.appwidget.provider 將資料識別為 AppWidgetProviderInfo 描述元。
  • android:resource:指定 AppWidgetProviderInfo 資源位置。

實作 AppWidgetProvider 類別

AppWidgetProvider 類別會擴充 BroadcastReceiver 做為處理小工具廣播的便利類別。而只會接收與小工具相關的事件廣播,例如小工具更新、刪除、啟用和停用的時間。發生這些廣播事件時,系統會呼叫下列 AppWidgetProvider 方法:

onUpdate()
系統會呼叫此方法,以 AppWidgetProviderInfoupdatePeriodMillis 屬性定義的間隔更新小工具。詳情請參閱本頁中的其他小工具屬性說明表格
使用者新增小工具時,系統也會呼叫這個方法,因此會執行基本設定,例如為 View 物件定義事件處理常式,或開始載入要顯示在小工具中的資料。不過,如果您宣告的設定活動沒有 configuration_optional 旗標,則當使用者新增小工具時,系統「不會」呼叫這個方法,而系統會針對後續更新呼叫此方法。設定活動完成後,設定活動就必須執行首次更新。詳情請參閱「允許使用者設定應用程式小工具」。
最重要的回呼是 onUpdate()。詳情請參閱本頁中的「使用 onUpdate() 類別處理事件」。
onAppWidgetOptionsChanged()

首次放置小工具或調整小工具大小時,系統就會呼叫此方法。使用這個回呼,即可根據小工具的大小範圍顯示或隱藏內容。從 Android 12 開始,就能取得小工具執行個體可用的大小範圍清單,並呼叫 getAppWidgetOptions() 以傳回包含下列內容的 Bundle

onDeleted(Context, int[])

每當從小工具主機刪除小工具時,系統就會呼叫此方法。

onEnabled(Context)

初次建立小工具例項時,系統會呼叫此方法。舉例來說,如果使用者加入兩個小工具例項,系統只會在第一次呼叫這個例項。如果您需要開啟新的資料庫,或執行只需要針對所有小工具執行個體進行一次的其他設定,就很適合使用這個方法。

onDisabled(Context)

從小工具主機刪除小工具的最後一個例項時,系統會呼叫此方法。您可以在這裡清除在 onEnabled(Context) 中完成的所有工作,例如刪除臨時資料庫。

onReceive(Context, Intent)

每次廣播與上述回呼方法之前都會呼叫此方法。您通常不需要實作此方法,因為預設的 AppWidgetProvider 實作會篩選所有小工具廣播,並視情況呼叫上述方法。

您必須使用 AndroidManifest 中的 <receiver> 元素,將 AppWidgetProvider 類別實作宣告為廣播接收器。詳情請參閱本頁的「在資訊清單中宣告小工具」。

使用 onUpdate() 類別處理事件

最重要的 AppWidgetProvider 回呼是 onUpdate(),因為系統會在每個小工具新增至主機時呼叫此回呼,除非您在沒有 configuration_optional 旗標的情況下使用設定活動。如果您的小工具接受任何使用者互動事件,請在這個回呼中註冊事件處理常式。如果您的小工具不會建立暫存檔案或資料庫,或執行需要清除的其他工作,那麼 onUpdate() 可能是您唯一需要定義的回呼方法。

舉例來說,如果您希望小工具包含輕觸後啟動活動的按鈕,可以使用下列 AppWidgetProvider 實作方式:

Kotlin

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

Java

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() 方法,使用此方法建立可啟動 ActivityPendingIntent,並使用 setOnClickPendingIntent(int, PendingIntent) 將該方法附加至小工具按鈕。其中包含疊代瀏覽 appWidgetIds 中的每個項目,也就是 ID 陣列,用於識別此提供者建立的每個小工具。如果使用者建立多個小工具執行個體,系統會同時更新所有執行個體。不過,小工具的所有執行個體只能管理一個 updatePeriodMillis 排程。例如,如果將更新排程定義為每兩小時,並在第一個小時後新增小工具的第二個例項,則兩者都會在第一個定義的週期中更新,並忽略第二次更新週期。兩者都每兩小時更新一次,而非每小時更新一次。

詳情請參閱 ExampleAppWidgetProvider.java 類別範例。

接收小工具廣播意圖

AppWidgetProvider 是一種便利類別。如果希望直接接收小工具廣播,可以實作自己的 BroadcastReceiver 或覆寫 onReceive(Context,Intent) 回呼。您需要注意的意圖如下:

建立小工具版面配置

您必須在 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));

提供兩個版面配置:一個指定在 res/layout-v31 中搭載 Android 12 以上版本的裝置,另一個指定在預設 res/layout 資料夾中,指定搭載 Android 11 以下版本的裝置。

實作圓角

Android 12 推出了下列系統參數,用於設定小工具的圓角半徑:

以下範例顯示小工具使用 system_app_widget_background_radius 做為小工具角落,並使用 system_app_widget_inner_radius 表示小工具中的檢視畫面。

小工具顯示小工具背景和檢視畫面的半徑
圖 4. 圓角。

1 小工具的邊角。

2 小工具內檢視區塊的邊角。

圓角的重要注意事項

  • 第三方啟動器和裝置製造商可以將 system_app_widget_background_radius 參數覆寫為小於 28 dp。system_app_widget_inner_radius 參數一律小於 system_app_widget_background_radius 的值 8 dp。
  • 如果您的小工具沒有使用 @android:id/background,或是定義背景,根據外框裁剪內容 (將 android:clipToOutline 設為 true),啟動器會自動識別背景,並使用圓角 (最高 16 dp 的圓角) 裁剪小工具。請參閱「確認您的小工具與 Android 12 相容」。

為了與 Android 舊版本的小工具相容,建議您定義自訂屬性,並使用自訂主題覆寫 Android 12 適用的主題,如以下 XML 檔案範例所示:

/values/attrs.xml

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

/values/styles.xml

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

/values-31/styles.xml

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

/drawable/my_widget_background.xml

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

/layout/my_widget_layout.xml

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