Wear Watchface

Wear OS by Google スマートウォッチ向けのアプリを作成します。
最新の更新 現在の安定版リリース 次のリリース候補 ベータ版リリース アルファ版リリース
2021 年 12 月 15 日 1.0.0 - - 1.1.0-alpha01

依存関係の宣言

Wear への依存関係を追加するには、Google の Maven リポジトリをプロジェクトに追加する必要があります。詳しくは、Google の Maven リポジトリをご覧ください。

アプリまたはモジュールの build.gradle ファイルに、必要なアーティファクトの依存関係を追加します。

Groovy

dependencies {
    // Use to implement wear watchfaces
    implementation "androidx.wear.watchface:watchface:1.1.0-alpha01"

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.1.0-alpha01"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.1.0-alpha01"

    // Use to implement a watchface style and complication editor
    implementation "androidx.wear.watchface:watchface-editor:1.1.0-alpha01"
}

Kotlin

dependencies {
    // Use to implement wear watchfaces
    implementation("androidx.wear.watchface:watchface:1.1.0-alpha01")

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.1.0-alpha01"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.1.0-alpha01"

    // Use to implement a watchface style and complication editor
    implementation("androidx.wear.watchface:watchface-editor:1.1.0-alpha01")
}

依存関係について詳しくは、ビルド依存関係の追加をご覧ください。

フィードバック

お寄せいただいたフィードバックは Jetpack 改善の参考にさせていただきます。新しい問題が見つかった場合や、このライブラリを改善するアイデアをお持ちの場合は、お知らせください。新しい問題を報告していただく前に、このライブラリの既存の問題をご確認ください。スターボタンをクリックすると、既存の問題に投票できます。

新しい問題を報告する

詳細については、Issue Tracker のドキュメントをご覧ください。

バージョン 1.1

バージョン 1.1.0-alpha01

2021 年 12 月 15 日

androidx.wear.watchface:watchface-*:1.1.0-alpha01 がリリースされました。バージョン 1.1.0-alpha01 に含まれる commit については、こちらをご覧ください

新機能

  • UserStyleSchemaComplicationSlots を XML で定義できるようになりました。これにより、ウォッチフェイスの構築が簡素化されます。また、WatchFaceMetadataClient クエリは、メタデータを取得するためにサービスにバインドする必要がないので、より高速になります。WatchFaceMetadataClientListenableWatchFaceMetadataClient は試験運用版ではなくなり、安定版 API の一部になります。システムは、オプションで 1 つのウォッチフェイスの複数のインスタンスをサポートできるようになります。インスタンスごとに、異なるユーザー定義のスタイル設定オプションを使用できます。これらはウォッチフェイス選択ツールに表示されます。これをオプトインするには、ウォッチフェイスのマニフェストに次のメタデータタグを含める必要があります。

        <meta-data
            android:name="androidx.wear.watchface.MULTIPLE_INSTANCES_ALLOWED"
            android:value="true" />
    
  • 一部のウォッチフェイスには、UserStyle でキャプチャされない状態があります。このケースと複数のインスタンスをサポートするため、ウォッチフェイスのインスタンス ID を WatchState.watchFaceInstanceId で利用できるようにしました。

  • ComplicationData がキャッシュに保存されるようになりました。これにより、読み込み時にウォッチフェイスの追加機能をすぐに表示できます。ComplicationData は、システムによってメモリ内でキャッシュに保存される場合もあれば、ウォッチフェイス ライブラリによってシリアル化される場合もあります。シリアル化される場合、関連する tapAction はすべて失われます。そうなった場合、ComplicationData.tapActionLostDueToSerializationtrue を返します。ウォッチフェイスは、ウォッチフェイスの追加機能を別の方法でレンダリングして(たとえばグレー表示にするか半透明にして)、タップ不可であることを示す必要があります。システムは、tapAction を含む更新済みの ComplicationData を可能な限り速やかに送信します。

  • 一部の ComplicationData は長時間キャッシュに保存するべきではありません。これをサポートするため、より一般的な機能である ComplicationDataTimeline を追加しました。これを使用すると、時間ゲート付きの ComplicationData のシーケンス(キャッシュして自動的に更新することが可能)を提供してウォッチフェイスに配信することができます。たとえば、さまざまな時間帯における当日の天気予報や、カレンダーの複数の予定を表示するなどです。ComplicationRequestListener に、これらのデータを返すために使用する新しいメソッド onComplicationDataTimeline が追加されました。

  • プライマリ データソースとセカンダリ データソースの ComplicationType を指定できるように、DefaultComplicationDataSourcePolicy が拡張されました。

  • 同期的なウォッチフェイスの追加機能のプロバイダにおいてウォッチフェイスの追加機能が通常より高い頻度(ウォッチフェイスが表示されていてアンビエント モードでないときは最大で毎秒 1 回)で更新されるケースのサポートを追加しました。注: 同期的なウォッチフェイスの追加機能のプロバイダは、メモリ圧迫を避けるため利用が制限されることがあります。

  • PendingIntentTapListener に対する変更は、根本にあるフレームワークの問題(ホームボタンを押してから 5 秒間ウォッチフェイスがアクティビティを起動できない)で解決されたため、元に戻される可能性があります。

API の変更

  • ComplicationData.isCachedtapActionLostDueToSerialization に変更されました。ウォッチフェイスの追加機能のスロットがタップ不可であることを示すために別の方法でレンダリングする必要があるかどうかを判断する際は、後者の方が便利です。(I6de2f
  • ComplicationDataTimelinewear-complication-data-source に追加しました。これを使用すると、時間ゲート付きの ComplicationData のシーケンス(キャッシュして自動的に更新することが可能)を提供してウォッチフェイスに配信することができます。たとえば、さまざまな時間帯における当日の天気予報や、カレンダーの複数の予定を表示するなどです。ComplicationRequestListener に、これらのデータを返すために使用する新しいメソッド onComplicationDataTimeline が追加されました。データソース サービスを一時停止するための新しい Kotlin ラッパー SuspendingTimelineComplicationDataSourceService が追加されました。(Idecdc
  • PendingIntentTapListenerWatchFaceControlClient.getPendingIntentForTouchEvent を追加しました。これにより、タップに反応してインテントを起動する必要があるウォッチフェイスで、ホームボタンを押してから 5 秒間フレームワークが新しいアクティビティの起動をブロックする問題を回避できます。(I98074
  • ウォッチフェイスごとの ComplicationData キャッシュを導入しました。これは、システムがウォッチフェイスの追加機能のデータ値を更新する機会を得るまで、ウォッチフェイスの読み込み時に、最後に確認されたウォッチフェイスの追加機能のデータ値が表示されるようにするためです。OEM 向けの新しい API メソッド WatchFaceControlClient.hasComplicationCache が追加されました。これは、ウォッチフェイスの追加機能をウォッチフェイスに送信する際のシステムの戦略に影響する可能性があります。また、ComplicationData には isCached プロパティがあります。キャッシュに保存されたウォッチフェイスの追加機能にはレンダリングの方法を変えることをおすすめします。これは、tapAction はキャッシュに保存できず、キャッシュに保存されたウォッチフェイスの追加機能では null になるためです。(I404b0
  • ウォッチフェイスのインスタンス ID を WatchState.watchFaceInstanceId で利用できるようになりました。これは、ほとんどのウォッチフェイスでは使用する必要はありませんが、スキーマに格納されていないウォッチフェイスごとの状態がある場合は、ウォッチフェイス インスタンスを識別するキーとして使用できます。これをサポートするため、WatchFaceControlClient.createHeadlessWatchFaceClient を呼び出す際に ID を指定できるようにしました。(I1ff98
  • プライマリ プロバイダ、セカンダリ プロバイダ、代替システム プロバイダ用のデフォルトの ComplicationTypes を設定できるように、DefaultComplicationDataSourcePolicy を拡張しました。ComplicationSlot.defaultDataSourceType は非推奨になりました。(If0ce3
  • ComplicationSlot.configExtras が可変になり、EditorSession.openComplicationDataSourceChooser() を呼び出す前に更新できるようになりました。(I6f852
  • WatchFace.setComplicationDeniedDialogIntentsetComplicationRationaleDialogIntent を追加しました。これらのインテントを起動するのは、ウォッチフェイスの追加機能の権限をリクエストする前にリクエスト理由のダイアログを表示するためと、権限が拒否された場合に、ウォッチフェイスの追加機能を編集するにはその権限が必要であることを説明する別のダイアログを表示するためです(プロバイダ選択ツールは起動に失敗するので、ダイアログが必要です)。(I3a29c
  • UserStyleSchemaComplicationSlots を XML で定義できるようになりました。これにより、ウォッチフェイスの構築が簡素化されます。また、WatchFaceMetadataClient クエリは、メタデータを取得するためにサービスにバインドする必要がないので、より高速になります。(I85bfa
  • ウォッチフェイスが getPendingIntentForTouchEvent をサポートしているかどうかをクライアントが判断できるように、InteractiveWatchFaceClient.supportsPendingIntentForTouchEvent を追加しました。(I0b917
  • WatchFaceMetadataClientListenableWatchFaceMetadataClient は試験運用版ではなくなりました。可能な場合は、ウォッチフェイスへのバインダをオープンせずに、ウォッチフェイスのメタデータを効率的に取得できます。(Ibb827
  • 同期的なウォッチフェイスの追加機能のプロバイダにおいてウォッチフェイスの追加機能が通常より高い頻度で(ウォッチフェイスが表示されていてアンビエント モードでないときは最大で毎秒 1 回)更新されるケースのサポートを追加しました。これを利用するには、プロバイダがマニフェストに新しい androidx.wear.watchface.complications.data.source.SYNCHRONOUS_UPDATE_PERIOD_SECONDS メタデータタグを追加して onSynchronousComplicationRequest をオーバーライドする必要があります。データソースの性質によっては、ウォッチフェイスの追加機能のインタラクティブ モードの開始時と終了時に通知を受け取るために、onStartSynchronousComplicationRequestsonStopInteractiveComplicationRequests をオーバーライドする必要もあります。(I8fe9d

バージョン 1.0

バージョン 1.0.0

2021 年 12 月 1 日

androidx.wear.watchface:watchface-*:1.0.0 がリリースされました。バージョン 1.0.0 に含まれる commit については、こちらをご覧ください

1.0.0 の主な機能

androidx.wear.watchface パッケージは、WearOS ウォッチフェイスの開発で推奨される新しいライブラリです。従来のウェアラブル サポート ライブラリを超える多くの新機能を備えています。

  • ユーザー定義のスタイル設定(カラーパレット、時計の針のスタイル、時間マークの外観の変更など)は、ライブラリによって直接サポートされます(androidx.wear.watchface.style を参照)。また、androidx.wear.watchface.editor により、ウォッチフェイス エディタの開発が非常に簡単になりました。追加のコードを記述しなくても、システム コンパニオン アプリでウォッチフェイスを編集できます。
  • ベスト プラクティスが組み込まれました。このライブラリにより、ウォッチフェイスの追加機能のスクリーン リーダー用コンテンツ ラベルが自動的に生成されます(独自のラベルを追加することもできます)。またバッテリー残量が少なくなり、バッテリー駆動時間を延長するために充電されていない場合は、フレームレートが自動的に低下します。
  • ウォッチフェイスの開発に必要なコードが少なくなりました。多数のボイラープレートがライブラリに移動されたウォッチフェイスの追加機能については、特に少ないコードで済みます。

バグの修正

  • EditorSession.userStyle.compareAndSet を修正しました。(I6f676
  • ウォッチフェイスの非常に短い遅延を修正しました。(Iffb97
  • UI スレッドで InteractiveWatchFaceImpl.onDestroy をディスパッチします。(I83340
  • ブロードキャスト レシーバに関するいくつかの問題を修正しました。(I7d25f

バージョン 1.0.0-rc01

2021 年 11 月 3 日

androidx.wear.watchface:watchface-*:1.0.0-rc01 がリリースされました。バージョン 1.0.0-rc01 に含まれる commit については、こちらをご覧ください

バグの修正

  • フローの移行によって機能しなくなる dump()(adb shell dumpsys によって呼び出されます)を修正しました。(087cf9e

  • writeDirectBootPrefs の適切な順序付けを保証します。writeDirectBootPrefs が常に initStyleAndComplications の後に実行されるようにします。そうしないと、UI スレッドの init が遅延するリスクがあります。(37650ac

  • Renderer.onDestroy が呼び出されることを保証します。レンダラが作成済みであるにもかかわらず WF init が完了せず Engine.onDestroy が呼び出される場合は、Renderer.onDestroy を呼び出す必要があります。(f9952dc

  • isBatteryLowAndNotCharging を最適化 / 修正しました。このパッチにより、isBatteryLowAndNotCharging の初期セットアップがもっと早い段階に移動されるため、createWatchFace と並列で実行できるようになります。さらに、ACTION_POWER_DISCONNECTED をリッスンするようになりました。(ddffd80

  • InteractiveWatchFaceClientImpl.isConnectionAlive はクローズ後に false になります。(ab9774e

バージョン 1.0.0-beta01

2021 年 10 月 27 日

androidx.wear.watchface:watchface-*:1.0.0-beta01 がリリースされました。バージョン 1.0.0-beta01 に含まれる commit については、こちらをご覧ください

バージョン 1.0.0-alpha24

2021 年 10 月 13 日

androidx.wear.watchface:watchface-*:1.0.0-alpha24 がリリースされました。バージョン 1.0.0-alpha24 に含まれる commit については、こちらをご覧ください

API の変更

  • パッケージ androidx.wear.watchface.complications のクラスを新しい wear:watchface:watchface-complications プロジェクトに移動しました。つまり、クラスの重複に関するエラーが発生するため、このライブラリと以前のアルファ版の wear:watchface:watchface-complications-data を含めることはできなくなります。(I97195
  • Renderer.dump の名前が Renderer.onDump に変更され、@UiThread アノテーションが付けられました。(I44845
  • InteractiveWatchFaceClient.addWatchFaceReadyListener の名前を addOnWatchFaceReadyListener に、removeWatchFaceReadyListener の名前を removeOnWatchFaceReadyListener に変更しました。(I48fea
  • EditorSession getComplicationsPreviewDatagetComplicationsDataSourceInfo は、suspend 関数ではなくなり、初期値が null の StateFlow<> のプロパティとなりました。ListenableEditorSession getListenableComplicationPreviewDatagetListenableComplicationsProviderInfo が削除され、基本クラスの新しい StateFlow<> オブジェクトに置き換えられました。Java コードの変更をリッスンする必要がある場合は、androidx.lifecycle.FlowLiveDataConversions.asLiveData を使用して LiveData<> に変換することを検討してください。(Ic5483

バージョン 1.0.0-alpha23

2021 年 9 月 29 日

androidx.wear.watchface:watchface-*:1.0.0-alpha23 がリリースされました。バージョン 1.0.0-alpha23 に含まれる commit については、こちらをご覧ください

新機能

ウォッチフェイス ライブラリは単一のライブラリ グループになったため、ライブラリは移動しました。そのため、次のように gradle のインポートを更新する必要があります。

androidx.wear:wear-complications-data androidx.wear.watchface:watchface-complications-data
androidx.wear:wear-complications-data-source androidx.wear.watchface:watchface-complications-data-source
androidx.wear:wear-watchface androidx.wear.watchface:watchface
androidx.wear:wear-watchface-complications-rendering androidx.wear.watchface:watchface-complications-rendering
androidx.wear:wear-watchface-client androidx.wear.watchface:watchface-client
androidx.wear:wear-watchface-client-guava androidx.wear.watchface:watchface-client-guava
androidx.wear:wear-watchface-data androidx.wear.watchface:watchface-data
androidx.wear:wear-watchface-editor androidx.wear.watchface:watchface-editor
androidx.wear:wear-watchface-editor-guava androidx.wear.watchface:watchface-editor-guava
androidx.wear:wear-watchface-guava androidx.wear.watchface:watchface-guava
androidx.wear:wear-watchface-style androidx.wear.watchface:watchface-style

API の変更

  • 個別の androidx.wear ウォッチフェイス ライブラリとウォッチフェイスの追加機能ライブラリを androidx.wear.watchface ライブラリ グループに移行します。(b25f3c0
  • ウォッチフェイス エディタがヘッドレス編集をサポートしているかどうかをクライアントに知らせるために、EditorRequest.canWatchFaceSupportHeadlessEditing を追加しました。asop/1756809 でサポートが追加されたため、これに関して偽陰性が生じる可能性がありますが、将来のすべてのウォッチフェイスに対しては正しい値が返されます。(ca55590
  • レンダラに dump() メソッドが追加されました。このメソッドをオーバーライドして、ABD shell dumpsys アクティビティ サービス WatchFaceService によって生成された情報にカスタムデータを追加できます。(95235f9
  • InteractiveWatchFaceClient.addWatchFaceReadyListener が最初にエグゼキュータを指定するようになりました。(563ac2f
  • StateFlowCompatHelper が削除されました。代わりに、asLiveData(androidx.lifecycle.asLiveData)を使用する必要があります。(bd35d3
  • CurrentUserStyleRepository.userStyle が変更できなくなりました。(I44889
  • WatchFaceReadyListener の名前を OnWatchFaceReadyListener に変更しました。(Ic12a9

バグの修正

  • InteractiveInstanceManager.deleteInstance で onDestroy を呼び出します。これは、InteractiveWatchFaceImpl がガベージ コレクションされるようにするために必要です。(fce4af8b/199485839