Google は、黒人コミュニティに対する人種平等の促進に取り組んでいます。取り組みを見る

追加機能をウォッチフェイスに追加する

ウォッチフェイスの追加機能(以下、「追加機能」と表記)は、データ プロバイダからのデータを表示します。 ウォッチフェイスは、Complications API を介して、使いたいデータ プロバイダを選び、基となるデータを取得することができます。これにより、データを取得するコードを作成せずに、日付や時刻にとどまらない多くの情報をウォッチフェイスに表示できます。

Complications API により、ユーザーがデータ プロバイダを選べるようにすることもできます。 また、Wear OS by Google では、データソースを選択するユーザー インターフェースも提供されています。

追加機能

ウォッチフェイスに追加機能を追加するには、以下の手順に従います。

ウォッチフェイスのデフォルト プロバイダを設定する

ウォッチフェイスでは、デフォルト プロバイダを指定できます。ユーザーがプロバイダを選択するまでは、デフォルト プロバイダが使用されます。デフォルト プロバイダを設定するには、WatchFaceService.EnginesetDefaultComplicationProvider() メソッドを使用します。このメソッドはいつでも呼び出すことができますが、指定された追加機能に対してユーザーがすでにプロバイダを選択している場合は、このメソッドを呼び出しても何も起こりません。

ほとんどのプロバイダについては、ウォッチフェイスにデータが届くようにするため、ウォッチフェイスに RECEIVE_COMPLICATION_DATA 権限を付与する必要があります。ただし、一部のシステム プロバイダは、ウォッチフェイスが自力で得ることができる情報のみを提供するため、安全だと見なされています。安全なプロバイダは、権限が付与されていないウォッチフェイスにデータを送信できます(システム プロバイダをご覧ください)。このようなプロバイダは、すぐにデータを提供できるので、デフォルト プロバイダとして使用するのに適しています。

また、あるプロバイダにウォッチフェイスが関連付けられていて、そのプロバイダをデフォルトとして使用したいときは、関連付けられているウォッチフェイスを安全なウォッチフェイスとして登録するようプロバイダにリクエストできます。

システム プロバイダ

システムには、デフォルトとして使用できるプロバイダが含まれています。 WatchFaceService.Engine クラスの setDefaultSystemComplicationProvider() メソッドは、追加機能のデフォルト システム プロバイダを設定します。このメソッドは、システム プロバイダを表す ID(整数値)を受け取ります。利用できる ID の一覧は、SystemProviders クラスから取得できます。

サポートされているシステム プロバイダの一部について、次の表に詳細を示します。

SystemProviders クラスのメソッド名 安全性 デフォルトとして設定可能か 注記
dateProvider() 標準の日付システム プロバイダ。タップすると、標準の Agenda アプリが開きます。
currentTimeProvider() 標準の「時刻と日付」システム プロバイダ。タップしても何も起きません。
batteryProvider() 標準の電池システム プロバイダ。タップしても何も起きません。
stepCountProvider() readDailyTotal で報告される 1 日の合計歩数を表示します。
unreadCountProvider() 通知ストリーム内の未読通知の数を表示します。
worldClockProvider() デフォルトはロンドンまたはニューヨークです。タップすると、タイムゾーンを変更できます。
appsProvider() 最初の「アプリ」アイコンを表示します。タップすると、アプリを選択できます。
nextEventProvider() × 〇(ただし、安全なプロバイダではありません) 標準の「次のイベント」システム プロバイダ。タップすると、標準の Agenda アプリが開きます。

ユーザーがデータ プロバイダを選択できるようにする

Wear OS は、ユーザーが特定の追加機能のプロバイダを選択するためのユーザー インターフェースを(アクティビティを通じて)提供します。ウォッチフェイスは、createProviderChooserHelperIntent メソッドを呼び出して、選択用のインターフェースを表示するインテントを取得できます。

ウォッチフェイスは、createProviderChooserHelperIntent を呼び出したときに、ウォッチフェイス追加機能 ID と、サポートされているタイプの一覧を提供します。タイプは、希望する順番に並べる必要があります。通常は、範囲値などの多くの情報を提供できるタイプを上位にします。

ユーザーがデータ プロバイダを選択すると、その設定は自動的に保存されます。ウォッチフェイスからそれ以上の操作を求められることはありません。

設定ユーザー インターフェース用の完全な機能を含む推奨コードについては、ウォッチフェイス サンプルアプリをご覧ください。

このコードは以下の機能を備えています。

  • 追加機能を設定する標準インターフェース
  • 他の設定への簡単なアクセス

コードを確認する場合は、AnalogComplicationConfigActivity クラスから始めてください。このクラスには、UI で使用できる設定エントリのリストを返す getDataToPopulateAdapter() メソッドが含まれています。

プロバイダ選択画面を開く

追加機能データを受信してプロバイダ選択画面を開くには、ウォッチフェイスに次の権限が必要です。

    com.google.android.wearable.permission.RECEIVE_COMPLICATION_DATA
    

この権限が付与されていないウォッチフェイスでは、プロバイダ選択画面を開くことができません。

簡単に権限をリクエストして選択画面を開くことができるように、ウェアラブル サポート ライブラリには ComplicationHelperActivity クラスが用意されています。このクラスを ProviderChooserIntent クラスの代わりに使用すると、ほぼすべてのケースで選択画面を起動できます。

必要な権限をリクエストする

ComplicationHelperActivity を使用するには、マニフェスト ファイルでこのアクティビティをウォッチフェイスに追加します。

    <activity android:name="android.support.wearable.complications.ComplicationHelperActivity"/>
    

プロバイダ選択画面を起動するには、インテントを取得する ComplicationHelperActivity.createProviderChooserHelperIntent メソッドを呼び出します。

startActivity または startActivityForResult に新しいインテントを指定すると、選択画面を起動できます。

startActivityForResult に新しいインテントを指定する例を次に示します。

Kotlin

    startActivityForResult(
            ComplicationHelperActivity.createProviderChooserHelperIntent(
                    activity,
                    watchFace,
                    complicationId,
                    ComplicationData.TYPE_LARGE_IMAGE
            ),
            PROVIDER_CHOOSER_REQUEST_CODE
    )
    

Java

    startActivityForResult(
      ComplicationHelperActivity.createProviderChooserHelperIntent(
         getActivity(),
         watchFace,
         complicationId,
         ComplicationData.TYPE_LARGE_IMAGE),
      PROVIDER_CHOOSER_REQUEST_CODE);
    

ヘルパー アクティビティが開始されると、このアクティビティは権限が付与されているかどうかをチェックします。権限が付与されていない場合、ヘルパー アクティビティはランタイム権限リクエストを送信します。権限リクエストが承認された場合(または権限が不要な場合)、プロバイダ選択画面が表示されます。

startActivityForResult にインテントを指定した場合、プロバイダが正常に設定されたときは結果コード RESULT_OK が呼び出し元のアクティビティに返され、プロバイダが設定されなかったときは結果コード RESULT_CANCELLED が返されます。

プロバイダが設定された場合、選択されたプロバイダの ComplicationProviderInfo クラスは、キー ProviderChooserIntent#EXTRA_PROVIDER_INFO を持つエクストラとして結果のデータ インテントに挿入されます。

追加機能データを受信する

追加機能データの受信を開始する際、ウォッチフェイスは追加機能 ID のリストを指定して、WatchFaceService.Engine クラスの setActiveComplications() を呼び出します。ウォッチフェイスは、追加機能を表示するスロットを一意に識別するためにこれらの ID を作成し、createProviderChooserIntent() メソッドに渡して、どの追加機能をどのスロットに割り当てるかをユーザーが決められるようにします。追加機能データは onComplicationDataUpdate() コールバックを通じて送信されます。

一般的に、ウォッチフェイスが追加機能データを受信するには上記の権限が必要ですが、例外もいくつかあります。厳密には、ウォッチフェイスは以下の条件のいずれかが成立する場合にのみ、プロバイダからデータを受信できます。

  • プロバイダが「安全」なシステム プロバイダである
  • プロバイダとウォッチフェイスのアプリが同じである
  • ウォッチフェイスがプロバイダのホワイトリストに「安全」なウォッチフェイスとして登録されている
  • ウォッチフェイスに権限が付与されている

上記のいずれの条件も成立しない場合、通常であればプロバイダからウォッチフェイスに ComplicationData が送信されるタイミングで、代わりに TYPE_NO_PERMISSION タイプのデータが送信されます。このタイプには、アイコン(感嘆符)と短いテキスト(「--」)が含まれています。これは、便宜上、短いテキストタイプまたはアイコンタイプと同様にレンダリングできるようにするためです。

ウォッチフェイスは TYPE_NO_PERMISSION のデータを受信した場合、追加機能を動作させるために操作が必要であることがユーザーに伝わるように、このデータを適切にレンダリングする必要があります。可能であれば、この状態の追加機能をタップすることにより権限リクエストが起動されるようにします。ウォッチフェイス アプリにヘルパー アクティビティが追加されていれば、ComplicationHelperActivity.createPermissionRequestHelperIntent() を使用してこの動作を実現できます。

ヘルパー アクティビティによる権限リクエストをユーザーが承認すると、ウォッチフェイス上のすべてのアクティブな追加機能に対して自動的に更新がリクエストされます。これにより、TYPE_NO_PERMISSION データが実際のデータに置き換えられます。

追加機能をレンダリングする

ウォッチフェイスは、想定される項目が含まれていさえすれば、自由にデータをレンダリングできます。必須項目は必ず含める必要があります。 タイプによっては、一部の省略可能項目を含めなければならない場合もあります(下のの「注記」列をご覧ください)。

標準の追加機能用のおすすめとして Google スタイルのデザイン ガイドラインが用意されていますが、デベロッパーは独自のスタイルを使用することも、別の方法でデータをウォッチフェイスに提供することもできます。

追加機能を描画する

ComplicationDrawable クラスを使用して、キャンバスに追加機能全体をレンダリングできます。

このクラスは、6 つある主要な追加機能タイプをすべてサポートしており、以下を行います。

  • 追加機能のレイアウトとスタイル設定をすべて処理する。
  • 境界内の背景、アイコン、テキストなどを描画する。
  • さまざまなオプションを設定できるようにする。オプションには、背景色、角の形と角丸の半径、境界線(有無を含む)、テキストの色、書体などが含まれます。
  • 画像のデコードとキャッシュ保存を行う。

ターゲット API レベル 24 では、リソースとして XML 形式の ComplicationDrawable オブジェクトを定義できます。または、プログラムで ComplicationDrawable オブジェクトを作成することもできます。draw() メソッドを使用すると、追加機能の描画と、インタラクティブ モードおよび常に画面表示モードでのスタイル オプションの設定を行えます。

焼き付き防止アイコンと画像が提供されていて、それらがデバイスで必要とされる場合、ComplicationDrawable はそれらを使用できます。これを実現するには、デバイス プロパティを受信したときに、ComplicationDrawable.setBurnInProtection() メソッドを呼び出します。

追加機能の描画に関する詳細な手順と例については、 ComplicationDrawable をご覧ください。これにはサンプル XML も含まれています。このクラスを利用するウォッチフェイス(サンプル XML を含む)の例については、ウォッチフェイス サンプルアプリAnalogComplicationWatchFaceService サンプルをご覧ください。

ComplicationDrawable オブジェクトを使用しない場合は、追加機能のテキストに TextRenderer を使用します。

テキストをレンダリングする

TextRenderer は、追加機能での使用を目的とするクラスで、使用するとキャンバスへのテキスト描画が簡単になります。このクラスには、以下の機能が含まれています。

  • 7 文字(短いテキスト項目の最大長)がリクエストされたテキストのサイズの境界内に収まらない場合、収まるまでテキストを短縮します。
  • 指定された行数のテキストを流し込むことができます。
  • 境界内に収まらない場合、テキストは省略されます。
  • レンダリングは、常時オン画面(常に画面表示モード)用に調整されます。

ウォッチフェイス エンジンを初期化する際に、TextRenderer オブジェクトを作成して、TextRenderer オブジェクトが使用する必要がある TextPaint オブジェクトを渡すことができます。 TextPaint オブジェクトは、フォント、テキストサイズ、色などを定義します。TextRenderer オブジェクトは項目ごとに作成する必要があります。たとえば、テキスト項目用に 1 つ、タイトル項目用に 1 つ作成します。

レンダリングするテキストの境界を指定するコードなどのサンプルについては、 TextRenderer をご覧ください。

追加機能のタップ

ComplicationDrawable.onTap() メソッドを使用すると、ウォッチフェイスから追加機能にタップイベントを渡すことができます。このメソッドは、ウォッチフェイスのタップにより WatchFaceService.Engine.onTapCommand() メソッドをトリガーする機能がベースになっています。

onTap の呼び出しを使用して、座標を ComplicationDrawable に渡すことができます。これにより、タップ座標を含む ComplicationDrawable に関連付けられたアクションが起動されます。メソッドが呼び出されたとき、関連付けられたアクションが ComplicationDrawable によって起動されると、戻り値 true が返されます。

onTap メソッドが呼び出された後、setHighlightDuration() メソッドを使用して、追加機能のハイライト表示が継続する時間を設定できます。

追加機能に対して ComplicationDrawable を使用していない場合は、独自にタップを検出してタップ アクション PendingIntent を起動する必要があります。ユーザーのタップに応答するウォッチフェイスの作成方法については、インタラクティブなウォッチフェイスを作成するをご覧ください。

追加機能タイプ

追加機能に表示されるデータの種類は、追加機能タイプによって決まります。たとえば、主要なデータが短い文字列である場合は、SHORT_TEXT タイプを利用できます。SHORT_TEXT タイプの場合、省略可能なデータはアイコンと短いタイトルです。

データ プロバイダは、ウォッチフェイス プロバイダとは異なる方法で追加機能タイプを使用します。

  • データ プロバイダは、提供する追加機能データの種類を選択します。たとえば、歩数プロバイダは RANGED_VALUE タイプと SHORT_TEXT タイプをサポートし、「次の打ち合わせ」プロバイダは SHORT_TEXT タイプと LONG_TEXT タイプをサポートします。データ プロバイダは、これらのタイプのどの省略可能項目を含めるかも選択します。
  • ウォッチフェイス プロバイダは、サポートする追加機能タイプの数を選択します。 たとえば、ウォッチフェイス上にある円形の追加機能は SHORT_TEXTICONRANGED_VALUE タイプをサポートし、ウォッチフェイス上のゲージは RANGED_VALUE タイプのみをサポートします。

ComplicationData オブジェクトは、常に 1 つの追加機能タイプを持ちます。追加機能タイプには、それぞれ必須項目と省略可能項目があります。一般的に、必須項目はデータの主な部分を表します。ほとんどのタイプは、必須項目から名前が付けられています。

1 つのタイプに複数の項目が含まれる場合があります。たとえば、SHORT_TEXT は、テキストのみ、タイトルとテキスト、アイコンとテキストのいずれかです。あるタイプをサポートする追加機能は、想定されるすべての項目の組み合わせを表示できる必要があります。ただし、一部の省略可能項目は、表示しなくてもよい場合があります(下の表の「注記」列をご覧ください)。たとえば、RANGED_VALUE タイプの短いタイトル項目は必須ではないので、ゲージなどはテキストなしで表示することもできます。

追加機能タイプの例

追加機能タイプの例を次に示します。

追加機能タイプ

タイプと項目

次の表は、ComplicationData オブジェクトのタイプと項目についての説明を示しています。 ウォッチフェイスが特定の追加機能タイプに対して無効な項目をリクエストすると、その項目のデフォルト値が返されます。 たとえば、ウォッチフェイスが SHORT_TEXT タイプの Long text 項目にアクセスしようとした場合は、Long text 項目のデフォルト値(null)が返されます。

タイプ 必須項目 省略可能項目 注記
SHORT_TEXT 短いテキスト アイコン
焼き付き防止アイコン
短いタイトル
アイコンと短いタイトルのいずれかまたは両方が提供された場合、いずれか一方のみが表示されると想定されます。
ICON アイコン 焼き付き防止アイコン テキストが不要な場合に使用します。アイコンは単色であると想定され、ウォッチフェイスによって着色される場合があります。
RANGED_VALUE
最小値
最大値
アイコン
焼き付き防止アイコン
短いテキスト
短いタイトル
省略可能項目は表示されるとは限りません。 独自の進行状況バーを描画したい場合は、setRangedValueProgressHidden() メソッドを使用して、ComplicationDrawable クラスが提供する進行状況バーを非表示にできます。
LONG_TEXT 長いテキスト 長いタイトル
アイコン
焼き付き防止アイコン
小さい画像
提供された場合、タイトルが表示されると想定されます。
SMALL_IMAGE 小さい画像 小さい画像は、写真スタイルまたはアイコン スタイルのどちらかのスタイルをとります。写真スタイルはスペースを覆うことが必要とされ、切り抜かれる場合があります。アイコン スタイルは切り抜かれないことが必要とされ、パディングされる場合があります。 画像は可変であるため、焼き付き防止を使用するデバイスまたは低ビットの常に画面表示モードを備えたデバイスでは、常に画面表示モードでの表示に適さない画像が表示されることがあります。焼き付き防止または低ビットの常に画面表示モードが有効になっている場合、ウォッチフェイスは安全な Burn-in protection small image を使用できます。そうでない場合は、画像が適切かどうかをウォッチフェイスが判断するのは難しいので、画像を表示するべきではありません。
LARGE_IMAGE 大きい画像 この画像は、ウォッチフェイス全体を覆うのに十分な大きさを持つと想定されます。 画像は可変であるため、焼き付き防止を使用するデバイスまたは低ビットの常に画面表示モードを備えたデバイスでは、常に画面表示モードでの表示に適さない画像が表示されることがあります。焼き付き防止または低ビットの常に画面表示モードが有効になっている場合、画像が表示に適しているかどうかを判断するのは難しいので、ウォッチフェイスは常に画面表示モードで画像を表示するべきではありません。

下記の表のタイプは空データ用であり、任意の追加機能スロットに送信される可能性があります。これらのタイプには項目がないため、サポートされるタイプのリストに含める必要はありません。ウォッチフェイスは、これらのタイプから、次の 3 つのケースを判別することができます。

  • プロバイダが選択されていない場合
  • ユーザーがスロットに「空」を選択している場合
  • プロバイダに送信するデータがない場合

プロバイダは、更新リクエストに対して TYPE_EMPTY を送信してはなりません。代わりに TYPE_NO_DATA を送信する必要があります。

「空」のデータに対する追加機能タイプの詳細を次の表に示します。

追加機能タイプ 説明
TYPE_NOT_CONFIGURED 追加機能がアクティベートされているが、ユーザーがプロバイダを選択しておらず、デフォルトも設定されていない場合に、システムから送信されます。

プロバイダが送信することはできません。

TYPE_EMPTY 追加機能がアクティベートされており、ユーザーがプロバイダではなく「空」を選択している場合、または、ウォッチフェイスがプロバイダを選択しておらず、デフォルトとしてこのタイプが設定されている場合に、システムから送信されます。

プロバイダが送信することはできません。

TYPE_NO_DATA 追加機能(プロバイダが選択されている)がアクティベートされている場合、プロバイダから実際のデータを受信する前に追加機能をクリアするため、システムから送信されます。

送信する実際のデータがない場合、プロバイダはこのタイプを送信する必要があります。

追加機能データの項目を使用する

ComplicationData オブジェクトの項目には、さまざまな機能があります。たとえば、テキスト項目には主要データが含まれ、タイトル項目には説明データが含まれます。歩数計の追加機能では、「2,543」という値を持つテキスト項目と、「歩数」という値を持つタイトル項目があるかもしれません。

次の表は、ComplicationData オブジェクトの項目に関する説明を示しています。追加機能タイプによって、項目に値が設定されている場合と設定されていない場合があります。

項目 説明
短いテキスト 小さい追加機能用の主要テキスト項目。 この項目の最大長は 7 文字を超えてはなりません(時間に依存する任意のテキストを含みます)。ウォッチフェイスは、任意の 7 文字の文字列をレンダリングできると想定されます。 列の幅は、使用される文字によって異なります。 ウォッチフェイスは、追加機能内に収まるようにテキストサイズを調整する必要があります。 テキストが 7 文字を超える場合は、切り捨てられることがあります。
アイコン データまたはデータのソースを表す単色の画像。 着色可能でなければなりません。この項目には、ベクター ドローアブルが推奨されます。
焼き付き防止アイコン 焼き付き防止を使用するデバイスにおいて、常に画面表示モードで表示されるアイコンを有効にする項目。焼き付き防止を使用するデバイスのウォッチフェイスでは、常に画面表示モードの場合、ピクセルの塗りつぶしブロックを表示してはなりません。Burn-in protection icon 項目は、icon 項目を含むすべての追加機能タイプの省略可能項目です。 Burn-in protection icon 項目にピクセルの塗りつぶしブロックを含めてはなりません。 標準アイコンが焼き付き防止に適さない場合、プロバイダは Burn-in protection icon 項目を提供する必要があります。焼き付き防止が有効になっているデバイスにおいて、常に画面表示モードでレンダリングするウォッチフェイスでは、Burn-in protection icon 項目が利用できる場合、icon 項目の代わりにその項目を使用する必要があります。
小さい焼き付き防止画像 焼き付き防止を使用するデバイスにおいて、常に画面表示モードで表示される画像を有効にする項目。焼き付き防止を使用するデバイスのウォッチフェイスでは、常に画面表示モードの場合、ピクセルの塗りつぶしブロックを表示してはなりません。Burn-in protection small image 項目は、small image 項目を含むすべての追加機能タイプの省略可能項目です。 Burn-in protection small image 項目にピクセルの塗りつぶしブロックを含めてはなりません。 標準の小さい画像が焼き付き防止に適さない場合、プロバイダは Burn-in protection small image 項目を提供する必要があります。焼き付き防止が有効になっているデバイスにおいて、常に画面表示モードでレンダリングするウォッチフェイスでは、Burn-in protection small image 項目が利用できる場合、small image 項目の代わりにその項目を使用する必要があります。
短いタイトル 小さい追加機能用の説明項目。 Short text 項目と組み合わせた場合にのみ、意味があるものになる可能性があります。 この項目の最大長は 7 文字を超えてはなりません(時間に依存する任意のテキストを含みます)。ウォッチフェイスは、任意の 7 文字の文字列をレンダリングできると想定されます。 列の幅は、使用される文字によって異なります。 ウォッチフェイスは、追加機能内に収まるようにテキストサイズを調整する必要があります。 テキストが 7 文字を超える場合は、切り捨てられることがあります。
長いテキスト テキストベースの大きい追加機能用の主要データ項目。
長いタイトル テキストベースの大きい追加機能用の説明項目。長いテキスト項目と組み合わせた場合にのみ、意味があるものになる可能性があります。
数値(浮動小数点数)で表現されたデータ。最小値項目と最大値項目を境界として相対的に描画されることが想定されます(ただし、必ずしもこれらの境界の間に収まる必要はありません)。
最小値 が描画される範囲の下限。値および最大値と組み合わせた場合にのみ、意味があるものになります。
最大値 が描画される範囲の上限。値および最小値と組み合わせた場合にのみ、意味があるものになります。
小さい画像 データまたはデータのソースを表す小さい画像。フルカラーに対応しています。ウォッチフェイス全体を覆うことは想定されません。
大きい画像 ウォッチフェイス全体を覆うのに十分な解像度を持つ画像。フルカラーに対応しています。

追加機能タイプをテストする

追加機能タイプには、それぞれテキストやアイコンなどの項目があります。ウォッチフェイスが特定の追加機能タイプをサポートする場合、すべての有効な項目の組み合わせをサポートする必要があります。

ウォッチフェイスに追加機能データがどのように表示されるかをテストできます。 具体的には、テストスイートを使用して追加機能タイプの表示をテストします。 この方法では、ComplicationData オブジェクトの有効な項目の組み合わせをテストするためのコードの記述は不要です。

テストスイートは、サンプルとして利用できるデータ プロバイダです。特定の追加機能タイプについて有効な項目の組み合わせを 1 つずつ順番にテストできます。

テストスイートを利用するには:

  1. デバイスまたはエミュレータに、テストスイート APK をインストールします。
  2. ウォッチフェイスにアクセスし、メイン設定アイコンをタップします。
  3. 設定 UI を使用して、テストスイート WearComplication-ProviderTestSuite を選択します。
  4. テストする追加機能のデータタイプを選択します。
  5. 追加機能をタップして、データタイプの組み合わせを表示します。
  6. 追加機能を繰り返しタップして、テスト対象のすべての項目の組み合わせが正しく表示されることを確認します。

たとえば、追加機能が短いテキストをサポートしている場合は、追加機能をタップして、短いテキストの項目のすべての主要な組み合わせを確認します。