ウォッチフェイスの追加機能

ウォッチフェイスに時刻以外に表示される機能をウォッチフェイスの追加機能と言います。 たとえば、電池インジケーターはウォッチフェイスの追加機能です。Complications API は、ウォッチフェイスとデータ プロバイダ アプリの両方で使用できます。

このドキュメントの以降の部分では、データ プロバイダ、ウォッチフェイス、ウォッチフェイスの追加機能のタイプについて説明します。

追加機能データ プロバイダ

ウォッチフェイスの追加機能で使うデータ（電池残量、天気、歩数のデータなど）をウォッチフェイスに提供するアプリを、「ウォッチフェイスの追加機能データ プロバイダ」と呼びます。これらのデータ プロバイダは生データを提供しますが、そのデータがどのようにウォッチフェイスにレンダリングされるかには関与しません。 ウォッチフェイスにデータを提供するアプリを作成する方法については、ウォッチフェイスの追加機能へのデータの公開をご覧ください。

下の図に示すように、Wear OS by Google は、プロバイダからウォッチフェイスへのデータフローを仲介します。

ウォッチフェイスの追加機能

ウォッチフェイスは、追加機能データ プロバイダからデータを受信します。このため、元データを取得するコードを作成せずに、ウォッチフェイスに追加機能を含めることができます。データのレンダリングの仕方はウォッチフェイスが制御するため、自然な形でデザインにデータを組み込むことができます。詳細については、追加機能のデザイン パターンをご覧ください。

ウォッチフェイスに追加機能を追加する方法については、ウォッチフェイスに追加機能を追加するをご覧ください。

ウォッチフェイスの追加機能のタイプ

ウォッチフェイスの追加機能のタイプとは、ウォッチフェイスの追加機能で表示できるデータの種類、つまりデータ プロバイダから提供されるデータの種類を定義するものです。たとえば、データが主に短い文字列で構成される場合、SHORT_TEXT タイプを使います。ComplicationData オブジェクトは、必ず 1 つのウォッチフェイスの追加機能のタイプを持ちます。そのタイプによって必須フィールドとオプション フィールドが定義されます。一般に、必須フィールドはデータの主な部分を表します。ほとんどのタイプは、必須フィールドから名前が付けられています。

データ プロバイダは、ウォッチフェイスとは違う形でウォッチフェイスの追加機能のタイプを使います。

• データ プロバイダは、提供するウォッチフェイスの追加機能データのタイプ（そのタイプのうち、どのオプション フィールドを提供するかも含みます）と、何種類のタイプをサポートするかを選択します。たとえば、歩数プロバイダは、RANGED_VALUE タイプと SHORT_TEXT タイプをサポートし、「次の打ち合わせ」プロバイダは、SHORT_TEXT タイプと LONG_TEXT タイプをサポートすることが考えられます。
• ウォッチフェイスに含めるウォッチフェイスの追加機能の数と、サポートするウォッチフェイスの追加機能のタイプは選択することができます。たとえば、ウォッチフェイス上にあるダイヤル型のウォッチフェイスの追加機能は、SHORT_TEXT、ICON、RANGED_VALUE の各タイプをサポートし、ウォッチフェイス上のゲージは、RANGED_VALUE タイプしかサポートしないことが考えられます。

さまざまなウォッチフェイスの追加機能のタイプや、各タイプでサポートされているフィールドについては、ウォッチフェイスの各種追加機能の使用とテストをご覧ください。

API の概要

以下に、Complications API の概要を示します。この API は、ウェアラブル サポート ライブラリの一部です。詳しくは、Wear API リファレンスをご覧ください。

• ComplicationData
  • Parcelable（内部的に Bundle を使用）で、不変です。
  • すべてのタイプのウォッチフェイスの追加機能データを表します。
  • インスタンス生成用のビルダーを含みます。
• ComplicationDrawable
  • キャンバスに追加機能全体をレンダリングします。
• ComplicationHelperActivity
  • 次のパーミッションをリクエストするために使用します。
    com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
  • ProviderChooserIntent の代わりに使用すると、ほぼすべてのケースで選択画面を起動できます。
• ComplicationManager
  • 追加機能マネージャー サービスのラッパーで、プロバイダが使用します。
  • プロバイダから追加機能データをシステムに送信します。
• ComplicationProviderService
  • Service を拡張したもので、追加機能システムに応答するコールバック メソッドを含みます。
  • コールバック メソッドは、すべてメインスレッドで呼び出されます。
• ComplicationText
  • ComplicationData オブジェクトでテキストベースの値を提供するために使用します。
  • 時間に依存する値（現在の時刻に依存するテキスト）用のオプションを含みます。
• ProviderChooserIntent
  • インスタンス化できないユーティリティ クラスで、通常は使用しません。代わりに ComplicationHelperActivity を使用します。
• ProviderInfoRetriever
  • ウォッチフェイスに属するすべての追加機能で使われている、現在のデータ プロバイダ情報（アプリ、プロバイダ名、アイコン）を取得するために使用します（ウォッチフェイス設定アクティビティから使用）。
• ProviderUpdateRequester
  • データ プロバイダ アプリから、プロバイダ サービスの onComplicationUpdated を呼び出し、アップデートをプッシュするために使用します。
• SystemProviders
  • ウォッチフェイスが自力で得ることができる情報のみを提供するため、「安全」とみなされているシステム プロバイダの一覧を取得します。
• TextRenderer
  • キャンバスへのテキストの描画をサポートします。

さらに、WatchFaceService.Engine クラスには以下のメソッドが含まれています。

• setActiveComplications()
  • ウォッチフェイスから呼び出し、利用できる追加機能スロットとサポートされているタイプを ComplicationManager オブジェクトに通知します。
• onComplicationDataUpdate()
  • ComplicationManager オブジェクトから呼び出し、ウォッチフェイスに追加機能データを送信します。
• setDefaultSystemComplicationProvider()
  • 追加機能のデフォルト システム プロバイダを設定します。 このメソッドは、システム プロバイダを表す ID（整数）を受け取ります。 利用できる ID の一覧は、SystemProviders クラスから取得できます。