MENU
  1. ホーム
  2. ソフトウェア
  3. ウィジェット
  4. Androidでウィジェットをプログラムで追加する方法

Androidでウィジェットをプログラムで追加する方法

AndroidポイントB編集部
※本ページにはプロモーション(広告)が含まれています。
Androidでウィジェットをプログラムで追加する方法

ホーム画面にウィジェットをプログラムで追加したいが手順や動きが分からず不安になっていませんか。

この記事を読めば動くコード例を使って実際にウィジェットを追加する流れが身につき、OSごとの注意点やテスト方法までしっかり押さえられるようになります。

項目内容
実体験に基づく手順実際に動かして確認したステップを順を追って分かりやすくまとめます。
OSごとのポイントAndroidのバージョン差による挙動の違いと対処法を具体的に示します。
実機テストとデバッグ技設置テストのやり方やログの見方など現場で役立つ裏ワザを紹介します。

まずは小さなウィジェットを一つ追加してみましょう。動いた瞬間の嬉しさが次の学びにつながります。

Android博士

最初は戸惑うかもしれませんが安心してください。小さな手順を一つずつ進めれば確実に動くようになります。困ったら落ち着いてログを見返す習慣をつけましょう。

目次

Androidでホーム画面にウィジェットをプログラムで追加する手順

Androidでホーム画面にウィジェットをプログラムで追加する手順

ホーム画面にウィジェットをプログラムで追加する方法は大きく2つあります。API26以上で使えるrequestPinAppWidgetでユーザーに追加を促す方法と、AppWidgetHostでアプリ内に直接ウィジェットを表示する方法です。

どちらも準備は同じでManifestでのAppWidgetProvider宣言とres/xmlに置くAppWidgetProviderInfoが必要です。あとはユーザーに追加を頼むか自アプリ内でHostViewを生成してViewGroupに差し込めば完成です。

最初は動作差に戸惑うことがあるので、エミュレーターと実機の両方で確認してください。ログを丁寧に追えば原因が見つかりやすく、段階的に組み立てると失敗が減ります。

Android博士

焦らず順序どおり進めれば着実に動きますよ。小さな成功を積み重ねて自信をつけていきましょう。

AndroidでAPI26以上の端末にウィジェット追加を促す方法

AndroidでAPI26以上の端末にウィジェット追加を促す方法

API26以上ではrequestPinAppWidgetを使うとホームアプリ側でウィジェット追加ダイアログを表示できます。ComponentNameとAppWidgetProviderInfoを用意して、成功時の通知を受け取るためのPendingIntentを渡すのが基本の流れです。

端末やホームアプリによってサポート状況が異なるので、戻り値のbooleanで実行可否を確認し、falseならユーザーに手動で案内する代替を用意してください。initialLayoutやpreviewを整えておくと見栄えが良くなります。

AndroidManifest.xmlでAppWidgetProviderを宣言する場所と書き方

項目内容
配置場所applicationタグ内のreceiver要素に宣言します。
記述の要点receiverでAppWidgetProviderクラスを指定しmeta-dataでres/xmlのAppWidgetProviderInfoを参照します。
備考meta-dataのresourceはAppWidgetProviderInfoのXMLファイルを指すようにします。

res/xmlにAppWidgetProviderInfoのXMLを配置して何を書くか

  • minWidth,minHeightでウィジェットの推奨サイズを指定します。
  • initialLayoutで最初に表示するレイアウトのリソースを指定します。
  • updatePeriodMillisで自動更新間隔を指定しますがバッテリー配慮は必要です。
  • resizeModeやwidgetCategoryでリサイズ可否やカテゴリを指定できます。

ActivityからrequestPinAppWidgetを呼んでユーザーに追加を依頼する方法

手順
ComponentNameとExtrasを用意

追加したいAppWidgetProviderのComponentNameを作り必要なら設定用のBundleを準備します。

手順
完了通知用のPendingIntentを作成

ユーザーが追加した後の処理を受け取るためにBroadcastやActivity用のPendingIntentを用意します。

手順
requestPinAppWidgetを呼ぶ

AppWidgetManager.requestPinAppWidgetにComponentNameとExtrasとPendingIntentを渡して呼び出します。戻り値でサポート可否を確認します。

Androidで自アプリ内のコンテナにウィジェットを表示する方法（AppWidgetHost）

Androidで自アプリ内のコンテナにウィジェットを表示する方法（AppWidgetHost）

AppWidgetHostを使うと自分のActivity内にウィジェットを表示できます。AppWidgetManagerでプロバイダ情報を取得しAppWidgetHost.allocateAppWidgetIdでIDを取得してからHostViewを生成してViewGroupに追加します。

ライフサイクルでstartListeningとstopListeningを適切に呼び、ウィジェットの設定画面を起動する場合は結果を受け取ってからViewを追加してください。解放処理も忘れずに行ってください。

ActivityでAppWidgetHostとAppWidgetManagerを初期化するコードの置き場所

手順
フィールドを用意

AppWidgetHostとAppWidgetManagerのフィールドとホストIDをActivity内で定義します。

手順
onCreateで初期化

onCreate内でAppWidgetHost(context,hostId)とAppWidgetManager.getInstance(context)を初期化します。

手順
onStart/onStopで監視を切替

onStartでappWidgetHost.startListening()を呼びonStopでappWidgetHost.stopListening()を呼んでください。

AppWidgetHostでallocateAppWidgetIdを呼んでウィジェットIDを取得する手順

手順
ウィジェットIDを取得

AppWidgetHost.allocateAppWidgetId()を呼んで新しいappWidgetIdを取得します。

手順
ウィジェット選択UIを起動

ACTION_APPWIDGET_PICKのIntentにEXTRA_APPWIDGET_IDを付けて選択Activityを開始しユーザーにウィジェットを選んでもらいます。

手順
結果を受け取る

終了コールバックでEXTRA_APPWIDGET_IDを確認し必要なら構成画面を起動してからHostViewを生成します。

AppWidgetHost.createViewで生成したHostViewを特定のViewGroupに追加する方法

手順
HostViewを生成

appWidgetHost.createView(context,appWidgetId,providerInfo)でHostViewを作成しappWidgetHost.sendUpdateなどで初期更新を行います。

手順
レイアウトに追加

適切なLayoutParamsを設定してcontainer.addView(hostView)で特定のViewGroupに追加します。

手順
終了時の掃除

ウィジェットを削除するときはcontainer.removeView(hostView)とappWidgetHost.deleteAppWidgetId(appWidgetId)で後片付けします。

Androidでウィジェット追加後にできる応用

Androidでウィジェット追加後にできる応用

ウィジェットをホーム画面に置けたら、その先にいろいろな拡張ができます。たとえば追加直後に設定画面を出して個別設定を受け付けたり、外部データを定期取得して表示を更新したり、タップでアプリの深い画面へ飛ばすことができます。

  • 個別設定を開いてウィジェットごとに振る舞いを変える
  • AppWidgetManagerで即時にRemoteViewsを送って表示を更新する
  • WorkManagerやServiceで定期的にデータを取得して反映する

実務だと、設定画面は追加直後に起動して結果を待つ形にするとユーザーが迷いません。定期更新はWorkManagerでまとめて管理するとバッテリー負荷を抑えやすくなります。

Android博士

最初は小さな更新から始めて、表示やタップの挙動を徐々に増やすと安心です。設定は追加直後に済ませるとユーザー体験がとても良くなります。

Androidでウィジェットの設定画面をプログラムから開く方法

Androidでウィジェットの設定画面をプログラムから開く方法

ウィジェットの設定画面は、AppWidgetProviderInfoのconfigure属性で指定するとシステムが追加時に自動で開いてくれます。プログラムから明示的に開きたいときは、Intentを使って設定用Activityを起動します。

一般的な書き方はIntent actionにAppWidgetManager.ACTION_APPWIDGET_CONFIGUREを使い、IntentにAppWidgetManager.EXTRA_APPWIDGET_IDを入れてstartActivityForResultあるいはActivityResultLauncherで受け取る方法です。Serviceから起動する場合はFLAG_ACTIVITY_NEW_TASKが必要か確認してください。

ウィジェットの設定用ActivityをIntentで起動するタイミングと書き方

手順
起動タイミング

ウィジェットIDを割り当てた直後か、ユーザーが追加操作をしたタイミングで起動します。追加フローの中で設定を済ませると混乱が少ないです。

手順
Intentの作り方

Intent intent=new Intent(AppWidgetManager.ACTION_APPWIDGET_CONFIGURE);intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,appWidgetId);startActivityForResult(intent,REQUEST_CODE); といった形で起動します。

手順
起動時の注意

起動前にresolveActivityでIntentが解決できるか確認し、ServiceからだとFLAG_ACTIVITY_NEW_TASKが必要になる点に気をつけてください。

追加時のコールバックで設定完了を受け取りウィジェットを確定する方法

手順
設定画面からの返却

設定用Activityは設定完了時にsetResult(RESULT_OK,new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID,appWidgetId));finish();のようにして戻します。

手順
追加確定の処理

呼び出し元のonActivityResultあるいはActivityResultCallbackでresultCodeを確認し、AppWidgetManager.getInstance(context).updateAppWidget(appWidgetId,remoteViews)で最初の表示を反映させます。

Androidでウィジェットの内容をプログラムで即時更新する方法

Androidでウィジェットの内容をプログラムで即時更新する方法

ウィジェットを即時に更新する基本はAppWidgetManager.updateAppWidgetです。RemoteViewsを組み立てて対象のappWidgetIdかComponentNameに対して送ると、ホーム画面の見た目がすぐ変わります。

コレクション系ビュー(ListViewやStackView)を使う場合はnotifyAppWidgetViewDataChangedでデータの差し替えを通知します。重い処理は必ずバックグラウンドで実行してください。

AppWidgetManager.updateAppWidgetでRemoteViewsを送る具体的な手順

手順
RemoteViewsを作る

RemoteViews rv=new RemoteViews(context.getPackageName(),R.layout.widget_layout);rv.setTextViewText(R.id.title,”表示テキスト”);rv.setOnClickPendingIntent(R.id.button,pendingIntent);

手順
AppWidgetManagerで更新

AppWidgetManager awm=AppWidgetManager.getInstance(context);awm.updateAppWidget(appWidgetId,rv);複数IDならawm.updateAppWidget(appWidgetIds,rv)を使います。

手順
コレクションの更新

ListViewなどを使っている場合はawm.notifyAppWidgetViewDataChanged(appWidgetId,R.id.listView)を呼んでデータを再読込させます。

ServiceやWorkManagerで更新トリガーをスケジュールする設定方法

手順
WorkManagerで定期更新

PeriodicWorkRequestを使ってWorker内でAppWidgetManager.updateAppWidgetを呼ぶと安定して動きます。ネットワークやバッテリーの制約をConstraintsで指定してください。

手順
即時トリガーや重い処理

即時更新はWorkManager.enqueueまたはForegroundServiceで行います。長時間の同期や大きな処理はサービスで分離すると安全です。

手順
端末の節電対策に配慮

Dozeやアプリ最適化で実行が遅れる場合があるため、重要な更新は短い周期にせず必要なときだけ動かす設計が望ましいです。

よくある質問

よくある質問
ウィジェットをプログラムで勝手にホーム画面に追加できますか。

ユーザーの同意なしに完全に自動で追加することは基本的にできません。Android8以上ではAppWidgetManager.requestPinAppWidgetを使ってユーザーに追加を促す流れが必要で、ランチャーの対応が必須です。

どのAPIを使えば良いですか。

Android8以上はAppWidgetManager.requestPinAppWidgetを使うのが一番簡単です。古い端末ではACTION_APPWIDGET_PICKとstartActivityForResultを使ってピン操作を促す方法がよく使われます。

特別なパーミッションは必要ですか。

普通のアプリではユーザー操作で追加するため特別なパーミッションは不要です。端末に組み込まれたシステムアプリであればBIND_APPWIDGET権限を使って自動追加できるケースがあります。

テストでホームに出てこないときのチェックポイントは何ですか。

ランチャーがウィジェットのピンをサポートしているかをまず確認してください。エミュレーターのランチャーだと動かないことがあるので実機で試すかログを見てAppWidget関連のエラーを探すと原因が分かりやすいです。

まとめ

まとめ

ホーム画面にウィジェットをプログラムで追加する手順をやさしくまとめます。許可の扱いとAppWidgetHostの準備、サイズと初期表示を押さえれば迷わず実装できます。

主な流れは3つあります。ウィジェットプロバイダの定義とmanifestの登録、AppWidgetManagerとAppWidgetHostでウィジェットIDを取得して配置、RemoteViewsで初期表示と更新を行うことです。

つまずきやすいのはランタイム権限とメーカーごとのランチャー挙動です。権限チェックや例外処理、実機での手動追加と動作の確認を忘れないでください。気軽に試して設定を少しずつ改善していきましょう。

注意点としてAndroidのバージョン差と各ランチャー実装で挙動が変わることが多いので、複数端末での実機確認を必ず行ってください。

ウィジェット
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！
目次