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

ウォッチフェイスの追加機能（以下、「追加機能」と表記）は、データソースからのデータを表示します。ウォッチフェイスの形式を使用して、基になるデータを取得するデータソースを選択できます。これにより、データを取得するコードを作成しなくても、ウォッチフェイスで時刻以外の情報を表示できます。

Watch Face Format を使用する

Complication 要素を使用すると、1 つのウォッチフェイス内に最大 8 個の追加機能を定義できます。この要素を使用すると、各ウォッチフェイスの追加機能がウォッチフェイスのどこに表示されるかを定義することもできます。

詳しくは、GitHub の WatchFaceFormat サンプルをご覧ください。

タイプと項目

次の表は、ComplicationData オブジェクトのタイプと項目について説明しています。ウォッチフェイスが、対象のウォッチフェイスの追加機能のタイプで無効な項目をリクエストすると、その項目に対するデフォルト値が返されます。たとえば、ウォッチフェイスが SHORT_TEXT タイプの LONG_TEXT 項目にアクセスしようとすると、LONG_TEXT 項目のデフォルト値である null が返されます。省略可能な項目は表示されるとは限りません。

型	必須項目	省略可能項目	注
SHORT_TEXT	短いテキスト	アイコン 焼き付き防止アイコン 短いタイトル コンテンツの説明	アイコンと短いタイトルの両方を指定した場合は、いずれか 1 つのみが表示されます。
MONOCHROMATIC_IMAGE	モノクロ画像	焼き付き防止アイコン コンテンツの説明	テキストが不要な場合に使用します。アイコンは単色であると想定され、ウォッチフェイスによって着色される場合があります。
RANGED_VALUE	値 最小値 最大値	モノクロ画像 焼き付き防止アイコン 短いテキスト 短いタイトル 色傾斜 動的な値 コンテンツの説明	独自の進行状況バーを描画する場合は、isRangedValueProgressHidden() メソッドを使用して、ComplicationDrawable クラスが提供する進行状況バーを非表示にできます。
GOAL_PROGRESS	値 目標値	モノクロ画像 焼き付き防止アイコン 短いテキスト 短いタイトル 色傾斜 動的な値 コンテンツの説明	GOAL_PROGRESS は、値がゼロから始まり目標値を超えてもよい歩数などを対象としています。
LONG_TEXT	長いテキスト	長いタイトル モノクロ画像 焼き付き防止アイコン 小さい画像 コンテンツの説明	長いタイトルを指定した場合は、それが表示されます。
SMALL_IMAGE	小さい画像	コンテンツの説明	小さい画像のスタイルは、写真スタイルまたはアイコン スタイルのいずれかです。写真スタイルは、スペースを埋めることが想定され、トリミングが可能です。アイコン スタイルは、トリミングが不可能で、パディングが可能です。 画像は可変であるため、焼き付き防止または低ビットの常に画面表示モードが有効なデバイスでは、常に画面表示モードでの表示に適さない画像が表示されることがあります。焼き付き防止または低ビットの常に画面表示モードが有効になっている場合、ウォッチフェイスは安全な焼き付き防止の小さい画像を使用する場合があります。それ以外の場合、画像が適切かどうかをウォッチフェイスが判断することは難しいため、画像は表示されません。
LARGE_IMAGE	大きい画像	コンテンツの説明	この画像は、ウォッチフェイス全体に表示できる十分な大きさがあるものです。 画像は可変であるため、焼き付き防止または低ビットの常に画面表示モードが有効なデバイスでは、常に画面表示モードでの表示に適さない画像が表示されることがあります。焼き付き防止または低ビットの常に画面表示モードが有効になっている場合、画像が表示に適しているかどうかをウォッチフェイスが判断することは難しいため、常に画面表示モードで画像は表示されません。
WEIGHTED_ELEMENTS	要素リスト	モノクロ画像 焼き付き防止アイコン 短いテキスト 短いタイトル コンテンツの説明	各要素は色と太さ（0 より大きい値）で構成されます。レンダリングされた要素のサイズは、その太さに比例している必要があります。 太さを特定の値に合計する必要はありません。 ウォッチフェイスでは WEIGHTED_ELEMENTS の色を変更できます。

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

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

ソースは、更新リクエストに対して TYPE_EMPTY を送信できません。代わりに TYPE_NO_DATA を送信してください。

追加機能のタイプ	説明
TYPE_NOT_CONFIGURED	追加機能がアクティベートされているが、ユーザーがソースを選択しておらず、デフォルトが設定されていない場合に、システムから送信されます。 ソースからは送信できません。
TYPE_EMPTY	追加機能がアクティベートされていて、ユーザーがソースでなく「空」を選択した場合、またはウォッチフェイスがソースを選択しておらず、デフォルトとしてこの追加機能タイプが設定されている場合に、システムから送信されます。 ソースからは送信できません。
TYPE_NO_DATA	ソースが存在する追加機能がアクティベートされている場合に、ソースから実際のデータを受信する前に追加機能をクリアするために、システムから送信されます。 ソースに実際の送信データがない場合は、ソースから送信できます。

一部のデバイスでは、ウォッチフェイスとウォッチフェイスの追加機能で Watch Face Format を使用する必要があります

既存のウォッチフェイスが Jetpack ウォッチフェイス ライブラリまたは ウェアラブル サポート ライブラリを使用している場合、次のデバイスではウォッチフェイスの追加機能にすべてのデータソースのデータが表示されます。

• Wear OS 4 以前を搭載したデバイス。
• Wear OS 5 への OTA アップグレードを受け取るデバイス。

また、既存のウォッチフェイスが Jetpack ウォッチフェイス ライブラリまたはウェアラブル サポート ライブラリを使用していて、これらのデバイスのいずれかにインストールされている場合、ウォッチフェイスは引き続きアップデートを受け取ることができます。

ただし、Wear OS 5 を搭載してリリースされる新しいスマートウォッチでは、ウォッチフェイスに Watch Face Format を使用する必要があります。そのため、ウォッチフェイス形式を使用するように移行することをおすすめします。