Register now for Android Dev Summit 2019!

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

ウォッチフェイスの追加機能とは、時間以外のものを表示するウォッチフェイス内の何らかの機能を指します。たとえば、電池インジケーターはウォッチフェイスの追加機能です。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 クラスから取得できます。