ユーザーがアプリ ウィジェットを設定できるようにする

ユーザーが特定の特性を構成できるようにウィジェットを設計します。たとえば、時計ウィジェットでは、表示するタイムゾーンをユーザーが設定できます。

ユーザーがウィジェットの設定を構成できるようにするには、ウィジェット構成 Activity を作成します。このアクティビティは、指定した構成オプションに応じて、ウィジェットの作成時または後で、アプリ ウィジェット ホストによって自動的に起動されます。

構成アクティビティを宣言する

Android マニフェスト ファイルで、構成アクティビティを通常のアクティビティとして宣言します。アプリ ウィジェット ホストは ACTION_APPWIDGET_CONFIGURE アクションで起動するため、アクティビティはこのインテントを受け入れる必要があります。次に例を示します。

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

android:configure 属性を使用して AppWidgetProviderInfo.xml ファイルでアクティビティを宣言します。このファイルの宣言についての詳細をご覧ください。構成アクティビティを宣言する方法の例を次に示します。

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

ランチャーはパッケージ スコープ外からアクティビティを参照するため、アクティビティは完全修飾された名前空間で宣言されます。

構成アクティビティを開始するにあたって必要な作業は以上です。次に、実際のアクティビティを実装する必要があります。

構成アクティビティを実装する

アクティビティを実装する際は、次の 2 つの重要な点に留意してください。

  • アプリ ウィジェット ホストは設定アクティビティを呼び出し、設定アクティビティは常に結果を返す必要があります。結果には、インテント エクストラに EXTRA_APPWIDGET_ID として保存された、アクティビティを起動したインテントによって渡されたアプリ ウィジェット ID が含まれていなければなりません。
    • 設定アクティビティが起動されたときにシステムは ACTION_APPWIDGET_UPDATE ブロードキャストを送信しません。つまり、ウィジェットが作成されたときに、ウィジェットの更新が最初に呼び出されることはありません。ウィジェットを初めて作成するときに GlanceAppWidget から更新をリクエストするのは、設定アクティビティの役割です。ただし、以降のサイクルでは更新が自動的にトリガーされます。

構成から結果を返し、Glance ウィジェットを更新する方法の例については、次のセクションのコード スニペットをご覧ください。

設定アクティビティからウィジェットを更新する

ウィジェットが設定アクティビティを使用する場合、設定が完了したときにウィジェットを更新するのはアクティビティの責任です。これを行うには、GlanceAppWidget インスタンスから直接手動更新をトリガーします。

ウィジェットを適切に更新して設定アクティビティを閉じる手順の概要は以下のとおりです。

  1. アクティビティを起動したインテントからアプリ ウィジェット ID を取得します。

    val appWidgetId = intent?.extras?.getInt(
        AppWidgetManager.EXTRA_APPWIDGET_ID,
        AppWidgetManager.INVALID_APPWIDGET_ID
) ?: AppWidgetManager.INVALID_APPWIDGET_ID

  2. アクティビティの結果を RESULT_CANCELED に設定します。

    このようにすると、ユーザーがアクティビティの終了前に戻った場合、システムはアプリ ウィジェット ホストに設定がキャンセルされたことを通知し、ホストはウィジェットを追加しません。

    val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
setResult(Activity.RESULT_CANCELED, resultValue)

  3. ユーザーの設定に応じてウィジェットを構成します（選択内容を永続的な DataStore またはローカル データベースに書き込むなど）。

  4. 構成が完了したら、プラットフォーム ウィジェット ID に対応する GlanceId を取得します。

    val glanceAppWidgetManager = GlanceAppWidgetManager(context)
val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)

  5. GlanceAppWidget インスタンスで update suspend 関数を呼び出して、ウィジェットのコンテンツを更新します。

    // Update the GlanceAppWidget directly
ExampleGlanceWidget().update(context, glanceId)

  6. 戻りインテントを作成し、アクティビティの結果で設定して、アクティビティを終了します。

    val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
setResult(Activity.RESULT_OK, resultValue)
finish()

ウィジェットの構成オプション

デフォルトでは、アプリ ウィジェット ホストは、ユーザーがウィジェットをホーム画面に追加した直後に、設定アクティビティを 1 回だけ起動します。ただし、ユーザーが既存のウィジェットを再構成したり、デフォルトのウィジェット構成を指定して初期ウィジェット構成をスキップしたりできるようにするオプションを指定できます。

配置したウィジェットをユーザーが再設定できるようにする

ユーザーが既存のウィジェットを再設定できるようにするには、appwidget-provider の widgetFeatures 属性で reconfigurable フラグを指定します。次に例を示します。

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

ユーザーは、ウィジェットを長押しして、図 1 の 1 で示されている [再設定] ボタンをタップすることで、ウィジェットを再設定できます。

ボタンが右下に表示される
図 1. ウィジェットの [再構成] ボタン。

ウィジェットのデフォルト設定を使用する

ユーザーが初期設定の手順をスキップできるようにすることで、よりシームレスなウィジェット エクスペリエンスを提供できます。これを行うには、widgetFeatures フィールドで configuration_optional フラグと reconfigurable フラグの両方を指定します。これにより、ユーザーがウィジェットを追加した後の設定アクティビティの起動が省略されます。前述のとおり、ユーザーは後でウィジェットを再構成できます。たとえば、時計ウィジェットでは初期設定を省略して、デフォルトでデバイスのタイムゾーンを表示できます。

構成アクティビティを再構成可能かつ省略可能としてマークする方法の例を次に示します。

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>
前へ
ウィジェットを強化する
次へ
生成されたプレビューをウィジェット選択ツールに追加する