このページは Cloud Translation API によって翻訳されました。

アプリ用のカスタムクイック設定タイルを作成する

クイック設定は、クイック設定パネルに表示されるタイルで、アクションを表します。ユーザーはタイルをタップして、繰り返し行うタスクをすばやく完了できます。アプリは TileService クラスを通じてユーザーにカスタムタイルを提供し、Tile オブジェクトを使用してタイルの状態をトラッキングできます。たとえば、アプリが提供する VPN をオンまたはオフにできるタイルを作成できます。

VPN タイルがオンとオフになっているクイック設定パネル — **図 1.** VPN タイルがオンとオフに切り替わっているクイック設定パネル。

タイルを作成するタイミングを決定する

ユーザーが頻繁にアクセスする、または迅速なアクセスを必要とする（あるいはその両方）と想定される特定の機能のタイルを作成することをおすすめします。最も効果的なタイルは、これらの両方の条件を満たし、頻繁に実行されるアクションにすばやくアクセスできるものです。

たとえば、フィットネスアプリのタイルを作成して、ユーザーがワークアウトセッションをすばやく開始できるようにします。ただし、ユーザーがワークアウト履歴全体を確認できるような、同じアプリのタイルを作成することはおすすめしません。

フィットネスアプリのタイルのユースケース — **図 2.** フィットネスアプリの推奨タイルと非推奨タイルの例。

タイルの見つけやすさと使いやすさを向上させるために、次の点に注意することをおすすめします。

タイルを使用してアプリを起動することは避けてください。代わりに、アプリショートカットまたは標準のランチャーを使用してください。
1 回限りのユーザーアクションにタイルを使用することは避けてください。代わりに、アプリのショートカットまたは通知を使用してください。
タイルを過剰に作成しないでください。アプリごとに最大 2 つまでをおすすめします。代わりにアプリショートカットを使用してください。
情報を表示するものの、ユーザーが操作できないタイルは使用しないでください。代わりに通知またはウィジェットを使用してください。

タイルを作成する

タイルを作成するには、まず適切なタイルアイコンを作成し、アプリのマニフェストファイルで TileService を作成して宣言する必要があります。

クイック設定のサンプルでは、タイルの作成と管理の方法の例を示しています。

カスタムアイコンを作成する

クイック設定パネルのタイルに表示されるカスタムアイコンを指定する必要があります。（このアイコンは、次のセクションで説明する TileService を宣言するときに追加します）。アイコンは、背景が透明な白一色で、24 x 24 dp の VectorDrawable の形式にする必要があります。

タイルの目的を視覚的に示すアイコンを作成します。これにより、ユーザーはタイルが自分のニーズに合っているかどうかを簡単に判断できます。たとえば、ユーザーがワークアウトセッションを開始できるフィットネスアプリのタイル用に、ストップウォッチのアイコンを作成できます。

TileService を作成して宣言する

TileService クラスを拡張するタイル用のサービスを作成します。

Kotlin

class MyQSTileService: TileService() {

  // Called when the user adds your tile.
  override fun onTileAdded() {
    super.onTileAdded()
  }
  // Called when your app can update your tile.
  override fun onStartListening() {
    super.onStartListening()
  }

  // Called when your app can no longer update your tile.
  override fun onStopListening() {
    super.onStopListening()
  }

  // Called when the user taps on your tile in an active or inactive state.
  override fun onClick() {
    super.onClick()
  }
  // Called when the user removes your tile.
  override fun onTileRemoved() {
    super.onTileRemoved()
  }
}

Java

public class MyQSTileService extends TileService {

  // Called when the user adds your tile.
  @Override
  public void onTileAdded() {
    super.onTileAdded();
  }

  // Called when your app can update your tile.
  @Override
  public void onStartListening() {
    super.onStartListening();
  }

  // Called when your app can no longer update your tile.
  @Override
  public void onStopListening() {
    super.onStopListening();
  }

  // Called when the user taps on your tile in an active or inactive state.
  @Override
  public void onClick() {
    super.onClick();
  }

  // Called when the user removes your tile.
  @Override
  public void onTileRemoved() {
    super.onTileRemoved();
  }
}

アプリのマニフェストファイルで TileService を宣言します。TileService の名前とラベル、前のセクションで作成したカスタムアイコン、適切な権限を追加します。

 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"  // 18-character limit.
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

TileService を管理する

アプリのマニフェストで TileService を作成して宣言したら、その状態を管理する必要があります。

TileService はバインドされたサービスです。TileService は、アプリからリクエストされた場合、またはシステムが TileService と通信する必要がある場合にバインドされます。一般的なバインドされたサービスのライフサイクルには、onCreate()、onBind()、onUnbind()、onDestroy() の 4 つのコールバックメソッドが含まれています。これらのメソッドは、サービスが新しいライフサイクルフェーズに入るたびにシステムによって呼び出されます。

TileService のライフサイクルの概要

バウンドサービスのライフサイクルを制御するコールバックに加えて、TileService ライフサイクルに固有の他のメソッドも実装する必要があります。Service ライフサイクルメソッドと TileService ライフサイクルメソッドは 2 つの別々の非同期スレッドで呼び出されるため、これらのメソッドは onCreate() と onDestroy() の外部で呼び出される可能性があります。

TileService ライフサイクルには次のメソッドが含まれています。これらのメソッドは、TileService が新しいライフサイクルフェーズに入るたびにシステムによって呼び出されます。

onTileAdded(): このメソッドは、ユーザーがタイルを初めて追加したとき、およびユーザーがタイルを削除して再度追加したときにのみ呼び出されます。これは、1 回限りの初期化を行うのに最適なタイミングです。ただし、これでは必要な初期化をすべて満たせない可能性があります。

注: タイルが作成されるたびに onTileAdded() が呼び出されるわけではありません。たとえば、デバイスの電源がオフになる前にタイルが追加されて削除されていない場合、デバイスが再起動または電源オンになっても onTileAdded() は呼び出されません。
onStartListening() と onStopListening(): これらのメソッドは、アプリがタイルを更新するたびに呼び出され、頻繁に呼び出されます。TileService は onStartListening() と onStopListening() の間でバインドされたままになり、アプリはタイルを変更して更新をプッシュできます。
onTileRemoved(): このメソッドは、ユーザーがタイルを削除した場合にのみ呼び出されます。

リスニングモードを選択する

TileService は、アクティブ モードまたは非アクティブ モードでリッスンします。アクティブモードを使用することをおすすめします。アクティブモードはアプリマニフェストで宣言する必要があります。それ以外の場合、TileService は標準モードであり、宣言する必要はありません。

TileService が onStartListening() と onStopListening() のメソッドペアの外に存在することを想定しないでください。

アクティブモード（推奨）

独自のプロセスで状態をリッスンしてモニタリングする TileService には、アクティブモードを使用します。アクティブモードの TileService は、onTileAdded()、onTileRemoved()、タップイベント、アプリプロセスからのリクエスト時にバインドされます。

タイル状態を更新するタイミングが独自のプロセスによって TileService に通知される場合は、アクティブモードをおすすめします。アクティブタイルは、ユーザーにクイック設定パネルが表示されるたびにバインドする必要がないため、システムの負荷を軽減します。

静的 TileService.requestListeningState() メソッドを呼び出して、リスニング状態の開始をリクエストし、onStartListening() へのコールバックを受け取ることができます。

アクティブモードを宣言するには、アプリのマニフェストファイルに META_DATA_ACTIVE_TILE を追加します。

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
         android:value="true" />
    ...
</service>

非アクティブモード

非アクティブモードは標準モードです。タイルがユーザーに表示されるたびにバインドされる場合、TileService は非アクティブモードになります。つまり、TileService は制御できないタイミングで作成され、再度バインドされる可能性があります。また、ユーザーがタイルを表示していない場合は、バインドが解除されて破棄されることもあります。

ユーザーがクイック設定パネルを開くと、アプリは onStartListening() へのコールバックを受け取ります。onStartListening() と onStopListening() の間であれば、Tile オブジェクトは何度でも更新できます。

非アクティブモードを宣言する必要はありません。アプリのマニフェストファイルに META_DATA_ACTIVE_TILE を追加しないだけです。

タイルの状態の概要

ユーザーがタイルを追加すると、タイルは常に次のいずれかの状態になります。

STATE_ACTIVE: オンまたは有効状態を示します。この状態では、ユーザーはタイルを操作できます。

たとえば、ユーザーが時間指定のワークアウトセッションを開始できるフィットネスアプリのタイルの場合、STATE_ACTIVE は、ユーザーがワークアウトセッションを開始し、タイマーが実行中であることを意味します。
STATE_INACTIVE: オフまたは一時停止の状態を示します。この状態では、ユーザーはタイルを操作できます。

フィットネスアプリのタイルの例をもう一度使用すると、STATE_INACTIVE のタイルは、ユーザーがワークアウトセッションを開始していないが、必要に応じて開始できることを意味します。
STATE_UNAVAILABLE: 一時的に利用できない状態を示します。この状態では、ユーザーはタイルを操作できません。

たとえば、STATE_UNAVAILABLE のタイルは、何らかの理由で現在ユーザーがタイルを利用できないことを意味します。

注意: 現在は利用できないが、後で利用可能な状態にできるタイルには STATE_UNAVAILABLE を使用します。コンポーネントがユーザーに再度提供されることがない場合は、COMPONENT_ENABLED_STATE_DISABLED を setComponentEnabledSetting() に渡します。

システムは Tile オブジェクトの初期状態のみを設定します。Tile オブジェクトの状態は、ライフサイクルの残りの期間にわたって設定します。

システムは、Tile オブジェクトの状態を反映するために、タイルのアイコンと背景を色付けすることがあります。STATE_ACTIVE に設定された Tile オブジェクトが最も暗く、STATE_INACTIVE、STATE_UNAVAILABLE の順に明るくなります。正確な色相は、メーカーとバージョンによって異なります。

オブジェクトの状態を反映して色が変わる VPN タイル — **図 4.** タイルの状態（アクティブ、非アクティブ、利用不可）を反映するように色付けされたタイルの例。

タイルを更新する

onStartListening() へのコールバックを受け取ったら、タイルを更新できます。タイルのモードに応じて、onStopListening() へのコールバックを受け取るまで、タイルを少なくとも 1 回更新できます。

アクティブモードでは、onStopListening() へのコールバックを受け取る前に、タイルを 1 回だけ更新できます。非アクティブモードでは、onStartListening() と onStopListening() の間でタイルを何度でも更新できます。

getQsTile() を呼び出すことで、Tile オブジェクトを取得できます。Tile オブジェクトの特定のフィールドを更新するには、次のメソッドを呼び出します。

Tile オブジェクトのフィールドを正しい値に設定したら、updateTile() を呼び出してタイルを更新する必要があります。これにより、システムは更新されたタイルのデータを解析し、UI を更新します。

Kotlin

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
  super.onStartListening()
  val state = getStateFromService()
  qsTile.label = state.label
  qsTile.contentDescription = tile.label
  qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.icon = state.icon
  qsTile.updateTile()
}

Java

public class StateModel {
  final boolean enabled;
  final String label;
  final Icon icon;

  public StateModel(boolean e, String l, Icon i) {
    enabled = e;
    label = l;
    icon = i;
  }
}

@Override
public void onStartListening() {
  super.onStartListening();
  StateModel state = getStateFromService();
  Tile tile = getQsTile();
  tile.setLabel(state.label);
  tile.setContentDescription(state.label);
  tile.setState(state.enabled ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setIcon(state.icon);
  tile.updateTile();
}

タップを処理する

タイルが STATE_ACTIVE または STATE_INACTIVE の場合、ユーザーはタイルをタップしてアクションをトリガーできます。次に、システムはアプリの onClick() コールバックを呼び出します。

アプリが onClick() へのコールバックを受信すると、ダイアログやアクティビティを起動したり、バックグラウンド作業をトリガーしたり、タイルの状態を変更したりできます。

Kotlin

var clicks = 0
override fun onClick() {
  super.onClick()
  counter++
  qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.label = "Clicked $counter times"
  qsTile.contentDescription = qsTile.label
  qsTile.updateTile()
}

Java

int clicks = 0;

@Override
public void onClick() {
  super.onClick();
  counter++;
  Tile tile = getQsTile();
  tile.setState((counter % 2 == 0) ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setLabel("Clicked " + counter + " times");
  tile.setContentDescription(tile.getLabel());
  tile.updateTile();
}

ダイアログを起動する

showDialog() は、クイック設定パネルを折りたたんでダイアログを表示します。追加の入力やユーザーの同意が必要な場合は、ダイアログを使用してアクションにコンテキストを追加します。

アクティビティを起動する

startActivityAndCollapse() は、パネルを折りたたみながらアクティビティを開始します。アクティビティは、ダイアログよりも詳細な情報を表示する場合や、アクションのインタラクティブ性が高い場合に便利です。

アプリでユーザーの操作が大幅に必要になる場合は、アクティビティの起動は最後の手段としてのみ行うべきです。代わりに、ダイアログまたは切り替えの使用をご検討ください。

タイルを長押しすると、ユーザーに [アプリ情報] 画面が表示されます。この動作をオーバーライドして、代わりに設定アクティビティを起動するには、ACTION_QS_TILE_PREFERENCES を使用してアクティビティの 1 つに <intent-filter> を追加します。

Android API 28 以降では、PendingIntent に Intent.FLAG_ACTIVITY_NEW_TASK が必要です。

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
}

または、特定の Activity セクションの AndroidManifest.xml にフラグを追加することもできます。

タイルを切り替え可能としてマークする

タイルが主に 2 状態のスイッチとして機能する場合（タイルの最も一般的な動作）、タイルを切り替え可能としてマークすることをおすすめします。これにより、タイルの動作に関する情報をオペレーティングシステムに提供し、アクセシビリティを全体的に向上させることができます。

TOGGLEABLE_TILE メタデータを true に設定して、タイルを切り替え可能としてマークします。

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

安全にロックされたデバイスに対して安全な操作のみを実行

ロックされたデバイスのロック画面の上にタイルが表示されることがあります。タイルに機密情報が含まれている場合は、isSecure() の値を確認してデバイスが安全な状態かどうかを判断し、それに応じて TileService の動作を変更する必要があります。

ロック中にタイルアクションを実行しても安全な場合は、startActivity() を使用してロック画面の上にアクティビティを起動します。

タイルのアクションが安全でない場合は、unlockAndRun() を使用して、デバイスのロックを解除するようユーザーに促します。成功すると、システムはこのメソッドに渡された Runnable オブジェクトを実行します。

タイルを追加するようユーザーに促す

タイルを手動で追加するには、次の手順を行う必要があります。

下にスワイプしてクイック設定パネルを開きます。
編集ボタンをタップします。
デバイスのすべてのタイルをスクロールして、お客様のタイルを見つけます。
タイルを長押しして、アクティブなタイルのリストにドラッグします。

ユーザーはいつでもタイルを移動または削除できます。

Android 13 以降では、requestAddTileService() メソッドを使用して、ユーザーがデバイスにタイルを追加する操作を大幅に簡素化できます。このメソッドは、クイック設定パネルにタイルを直接追加するようユーザーにリクエストを促します。プロンプトには、アプリ名、指定されたラベル、アイコンが含まれます。

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

コールバックには、タイルが追加されたかどうか、追加されなかったかどうか、すでに存在していたかどうか、エラーが発生したかどうかに関する情報が含まれます。

ユーザーにプロンプトを表示するタイミングと頻度を決定する際は、裁量権を行使してください。requestAddTileService() は、コンテキスト内でのみ呼び出すことをおすすめします。たとえば、ユーザーがタイルで利用できる機能を初めて操作するときなどです。

システムは、特定の ComponentName のリクエストがユーザーによって十分に拒否されたと判断した場合、そのリクエストの処理を停止する場合があります。ユーザーは、このサービスの取得に使用された Context から決定されます。これは現在のユーザーと一致する必要があります。

アプリ用のカスタム クイック設定タイルを作成する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

タイルを作成するタイミングを決定する

タイルを作成する

カスタム アイコンを作成する

TileService を作成して宣言する

Kotlin

Java

TileService を管理する

TileService のライフサイクルの概要

リスニング モードを選択する

アクティブ モード（推奨）

非アクティブ モード

タイルの状態の概要

タイルを更新する

Kotlin

Java

タップを処理する

Kotlin

Java

ダイアログを起動する

アクティビティを起動する

タイルを切り替え可能としてマークする

安全にロックされたデバイスに対して安全な操作のみを実行

タイルを追加するようユーザーに促す

アプリ用のカスタムクイック設定タイルを作成する

カスタムアイコンを作成する

リスニングモードを選択する

アクティブモード（推奨）

非アクティブモード