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

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

ComplicationSlotsManager を使用する

ウォッチフェイスに追加機能を追加するには、ComplicationSlotsManager を使用します。

ComplicationSlotsManager は、ウォッチフェイスがサポートする追加機能の数と画面内での位置を定義します。ComplicationSlotsManager では、CurrentUserStyleRepository を使用して、追加機能の数または位置の変更をサポートできます。次に例を示します。

 override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager {
        val defaultCanvasComplicationFactory =
            CanvasComplicationFactory { watchState, listener ->
                // ...
            }

        val leftComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 100,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        val rightComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 101,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        return ComplicationSlotsManager(
            listOf(leftComplicationSlot, rightComplicationSlot),
            currentUserStyleRepository
        )
 }

タイプと項目

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

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

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

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

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

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

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