Wear Watchface

Wear OS by Google スマートウォッチ向けのアプリを作成します。
最新の更新 安定版リリース リリース候補版 ベータ版リリース アルファ版リリース
2022 年 11 月 9 日 1.1.1 - - 1.2.0-alpha04

依存関係の宣言

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

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

Groovy

dependencies {
    // Use to implement wear watchfaces
    implementation "androidx.wear.watchface:watchface:1.2.0-alpha04"

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

    // Use to implement a watchface style and complication editor
    implementation "androidx.wear.watchface:watchface-editor:1.2.0-alpha04"

    // Can use to render complications.
    // This library is optional and watchfaces may have custom implementation for rendering
    // complications.
    implementation "androidx.wear.watchface:watchface-complications-rendering:1.2.0-alpha04"
}

Kotlin

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

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

    // Use to implement a watchface style and complication editor
    implementation("androidx.wear.watchface:watchface-editor:1.2.0-alpha04")

    // Can use to render complications.
    // This library is optional and watchfaces may have custom implementation for rendering
    // complications.
    implementation "androidx.wear.watchface:watchface-complications-rendering:1.2.0-alpha04"
}

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

フィードバック

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

新しい問題を報告する

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

バージョン 1.2

バージョン 1.2.0-alpha04

2022 年 11 月 9 日

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

新機能

  • Android T について、ウォッチフェイスの追加機能の新しい 2 つのタイプ(GoalProgressComplicationDataWeightedElementsComplicationData)のサポートを追加しました。
  • GoalProgressComplicationDataRangedValueComplicationData に似ていますが、(RangedValueComplicationData の場合は値が [min .. max] の範囲に収まるのに対して)対象とする値を超えることがあるため、ビジュアル デザインに影響してすべてのウォッチフェイスに対応できなくなる可能性があります。
  • GoalProgressComplicationData により、円グラフなどで単純なデータの内訳を確認できるようになりました。
  • ColorRamps のサポート(オプション)を RangedValueComplicationData に追加しました。
  • Android T について、ComplicationPersistencePolicysetCachePolicyComplicationData に追加しました。これにより、ウォッチフェイスの追加機能が保持されるかどうか(再起動の後にキャッシュに保存されるかどうか)をプロバイダが管理できるようになりました。ほとんどのウォッチフェイスの追加機能では、キャッシュ制御を設定する必要はありませんが、設定しておくと、頻繁に更新される追加機能(健康に関するデータのウォッチフェイスの追加機能など)の場合に、古いデータで特殊なケースを修正できることもあります。また、ComplicationDisplayPolicy を追加して、DO_NOT_SHOW_WHEN_DEVICE_LOCKED により、対応するウォッチフェイスでウォッチフェイスの追加機能がデバイスのロック中に表示されないようにしました。(Ic9574

API の変更

  • GoalProgressComplicationDataWeightedElementsComplicationDataColorRamp は試験運用版ではなくなりました。(Ica9e2
  • ComplicationPersistencePolicyComplicationDisplayPolicy が Android T の API として適切にマークされるようになりました。(I31d88
  • 非推奨の ComplicationSlotOverlay コンストラクタに DeprecationLevel.WARNING が追加され、Java から再度呼び出せるようになりました。(Ib308c
  • ComplicationRequestListenerCanvasComplicationComplicationTapFilterInteractiveWatchFaceClient の Java 互換性の問題を、@JvmDefaultWithCompatibility アノテーションを付けることで修正しました。(Id94fc
  • 試験運用版の ProtoLayoutComplicationDataListComplicationData を削除しました。これらの API についてのデベロッパー ストーリーが明確ではなかったため、Google では今後また確認していく予定です。(I9df05
  • ValueType を再び RangedValueComplicationData に追加しました。WeightedElementsComplicationData で背景色がサポートされるようになりました。DiscreteRangedValueComplicationData を、その機能が WeightedElementsComplicationData のサブセットであるため、削除しました。(I6446c

バグの修正

  • isForScreenShot を equals とハッシュコードに含めます。onRenderParametersChanged が正しい isForScreenshot 値を取得していることを確認します。(I04a41
  • ヘッドレス クライアントからの WatchFaceControlService のリークを修正しました。(e90e00

バージョン 1.2.0-alpha03

2022 年 10 月 5 日

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

新機能

  • 新機能はありませんが、ウォッチフェイス エディタに関するバグをいくつか修正しました。

API の変更

  • rootUserStyleSettings が試験運用版ではなくなったため、UserStyleSchema.userStyleSettings が非推奨になりました。(Ie96e3
  • rootUserStyleSettings が試験運用版ではなくなりました。(I8d6b3
  • WatchFaceColors は一部のシステムではサポートされていないため、試験運用版としてマークされました。(I6d75d
  • DisconnectReasons を公開 API で公開し、IntDef で使用できるようにしました。(I791f8

バグの修正

  • SysUI が停止した場合は、ウォッチ エディタで開いている画面が閉じるようになりました。SysUI が停止してもウォッチフェイス エディタが閉じないと、ユーザーによるスタイルの変更を保持するためにシステムが SysUI に依存した状態になり、ウォッチフェイスが一貫性のない状態のままになる可能性があります。(ba762a
  • ComplicationDataSourceInfoRetriever のメモリリーク(Kotlin コルーチンが継続することで gc root として機能し、エディタのアクティビティが保持されてしまう)を修正しました。(33ee06

バージョン 1.2.0-alpha02

2022 年 9 月 21 日

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

新機能

  • ウォッチフェイスには、視覚的に影響を及ぼす UserStyle 以外の設定もあります(背景写真の選択など)。Renderer.sendPreviewImageNeedsUpdateRequest を追加し、ウォッチフェイスは更新されたプレビュー画像をリクエストできるようになりました。この機能を利用するには対応するシステムのアップデートが必要です。

  • また、ウォッチフェイスの色をシステムに公開するための API も追加し、これに基づいてカラーパレットを選択できるようになりました。これはパッチ適用後の試験運用版ですので注意してください

  • ほぼすべてのタイプの ComplicationDataSmallImages をサポートするようになりました。

API の変更

  • 壁紙マネージャーは、エンジンから切り離され、別のエンジンを作成することがあります。DisconnectReason int def を追加し、DisconnectReason を含む新しいメソッドで ClientDisconnectListener を拡張しました。これによってリスナーはエンジンのデタッチを監視できます。(I45cce
  • nameResourceIdscreenReaderResourceId の 2 つのオプションのパラメータを ComplicationSlotOverlay コンストラクタに追加しました(I157e8
  • PreviewImageUpdateRequestedListener を持つ getOrCreateInteractiveWatchFaceClient の新しいオーバーロード用の guava ラッパーを追加しました。(Ic31f0
  • Renderer.sendPreviewImageNeedsUpdateRequest を追加しました。これは、外観に影響を与える UserStyleSchema 以外の状態を持つウォッチフェイス(選択可能な背景画像を持つウォッチフェイスなど)に役立ちます。クライアント側では、これらのリクエストを監視するためのオプションのパラメータとして PreviewImageUpdateRequestedListenergetOrCreateInteractiveWatchFaceClient に追加しました。(Iff44a
  • WatchFaceColors を公開するための API を簡略化し、レンダラにウォッチフェイスが設定できる watchFaceColors というシンプルなプロパティを追加しました。これはスタイルの変更に応じて、必要であれば更新する必要があります。WallpaperManager を使用して色の変化を監視する代わりに、OnWatchFaceColorsListenerInteractiveWatchFaceClient に追加しました。(I490bc
  • ウォッチフェイスの視認性の高い 3 色を保持する WatchFaceColors クラスを追加し、レンダラにオープン メソッド watchfaceColorsnotifyWatchFaceColorsChanged を追加しました。これにより、システムは WallpaperManager.getWallpaperColors を介してウォッチフェイスの色を取得できます。(I3d611
  • ShortTextComplicationDataRangedValueComplicationDataNoPermissionComplicationData(および試験運用版の DiscreteRangedValueComplicationDataGoalProgressComplicationDataWeightedElementsComplicationData)はすべて SmallImages をサポートするようになりました。ウォッチフェイスが複数の色を使用して追加機能を表示する場合、これまではモノクロ画像を使用する必要がありましたが、マルチカラー SmallImage を使用できるようになりました。(I257df
  • 代わりに PreviewImageUpdateRequestedListenerConsumer<> にリファクタリングします。(Ia875d
  • カスタムの単一抽象メソッド(SAM)タイプの OnWatchfaceColorsListener を汎用の Java SAM タイプ(Consumer)に置き換えます。(I0c489
  • PreviewImageUpdateRequestedListener を指定していない古い getOrCreateInteractiveWatchFaceClient メソッドと listenableGetOrCreateInteractiveWatchFaceClient メソッドのサポートは終了しました。(Iec502

バグの修正

  • DisconnectReason.BINDER_DIED の名前が DisconnectReason.ENGINE_DIED に変更されました。(I4eb0e

バージョン 1.2.0-alpha01

2022 年 8 月 10 日

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

新機能

  • さまざまな新しいウォッチフェイスの追加機能の形式に対して、試験運用サポートを追加しました。これは現在も開発中の分野です。この新しい形式は、予告なく変更される可能性があり、現在のところ CanvasComplicationDrawable によるレンダラのサポートはありません。
  • ウォッチフェイスの追加機能用スロットにオプションでマージンを追加して、小さいウォッチフェイスの追加機能でもタップしやすくしました。

API の変更

  • 試験運用版の BoundingArc クラスを変更できなくなりました。(If624a
  • 小さいウォッチフェイスの追加機能は、タップするのが難しいことがあります。これに対処するために、レンダリングに影響を与えずにタップ可能な領域を増やすマージンのサポートを導入しました。コードまたは XML によって指定しない限り、ComplciationSlots のマージンはゼロです。(I14089
  • null 以外のファクトリ インスタンスを返すように getComplicationSlotInflationFactory(CurrentUserStyleRepository) 署名を変更しました。null を返すのは以前から誤りでしたが、この変更により、API コントラクトが明確になりました。(I0fcc0
  • createComplicationSlotsManager との整合性を保つために、WatchFaceService.getComplicationSlotInflationFactory メソッドに currentUserStyleRepository 引数を追加しました。(I2ddd2
  • UserStyleFlavors は試験運用機能ではなくなりました。(I69cdc
  • RangedValueComplicationData から試験運用版の ValueType を削除し、代わりに整数の範囲と値を除いて RangedValueComplicationData と同様の試験運用版の DiscreteRangedValueComplicationData を導入しました。また、試験運用版の GoalProgressComplicationData を導入しました。これは RangedValueComplicationData に似ていますが、目標の達成度を表すため、最小値が暗黙的にゼロであり、targetValue より大きい値を許容する点が異なります。すべての RangedValue バリアントでは、monochromeImage、テキスト、タイトルのうち少なくとも 1 つを指定する必要があります。(I9590c
  • システム ソフトウェアにはユースケースがないため、ComplicationSlotState から boundsWithMargins を削除しました。(I42e26
  • WeightedElementsComplicationData の試験運用版のサポートを追加しました。これは、要素の配列(太さと色のペア)とオプションのテキスト / タイトル / 画像で構成されます。これは円グラフとして表示されることがありますが、通常はラベルをレンダリングするスペースがウォッチフェイスの追加機能にないため、コンテキストに応じて色の意味がわかるようにする必要があります。(I87eea
  • 試験運用版の ColorRamps(オプションで RangedValueComplicationDataGoalProgressComplicationData によって使用される)では、最大 7 つの色のシーケンスと、色を滑らかにトゥイーンするか、またはサイズが均等な単色の連続を段階的にレンダリングするかを示すフラグを指定できるようになりました。(I9f5bf
  • RangedValueComplicationData.drawSegmentedvalueType に変更されました。これは対応する ValueType IntDef を持つ int として、範囲値に意味論的意味を与えるもので、ウォッチフェイスの追加機能のレンダラが使用することで、スタイリングに影響を与えることができます。(I0616b
  • オプションの ColorRanges の試験運用版サポートを RangedValueComplicationData に追加しました。通常、ウォッチフェイスの追加機能は、ウォッチフェイスが選択した色でレンダリングされますが、ComplicationDataSource は特定の意味論的意味がある場合などに色を設定するのに適しています(温度に応じて赤色から青色に変化するなど)。(I5153a
  • RangedValueComplicationData に試験運用版の drawSegmented ヒントを追加しました。これにより、レンダラにセグメント付きの範囲値インジケーターを描画するように指示します(1 セグメント = 1 ユニット)。(I7d7c1

バグの修正

  • 事前定義された画面座標系を基準に ComplicationSlotBounds を定義する機能を追加しました。(I0985d

バージョン 1.1

バージョン 1.1.1

2022 年 8 月 10 日

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

  • これはバグ修正のリリースであり、バージョン 1.1.0 を使用中のユーザーはアップグレードすることを強くおすすめします。

バグの修正

  • ウォッチフェイスの初期化は非同期で行われます。ウォッチフェイスの準備が整う前にウォッチフェイスの追加機能を受け取った場合は、pendingInitialComplications リストに追加され、後で適用されます。pendingInitialComplications の適用が早すぎたため、ウォッチフェイスの初期化の最中に、ウォッチフェイスの追加機能が pendingInitialComplications に追加されたまま無視される時間帯がありました。この問題は修正されています。さらにこのパッチによって、ComplicationRenderer が誤ってプレースホルダの非同期読み込みを試行することで、コンパイル グラフィックが更新されなかったバグが修正されました。また、このパッチにより、複数の pendingInitialComplications をマージする必要がある理論的なバグと思われるものも修正されました。(0d03ba3

  • getExistingInstanceOrSetPendingWallpaperInteractiveWatchFaceInstance が不必要に長くロックを保持することによる InteractiveInstanceManager のデッドロックの可能性がなくなるように修正しました。通常、engine.setUserStyle は高速であるはずですが、なんらかの理由で高速でない場合は、デッドロック / ANR が発生する可能性があります。このパッチにより、不要な操作がロックから排除され、デッドロックが発生する可能性がなくなります。(5a2adca

  • WatchFaceService を保持していたいくつかの問題を修正しました。WakeLock は WatchFaceService を保持する場合がありますが、release() 呼び出しを追加することでこの問題を修正できます。また StateFlows は、基盤となる CoroutineScopes をキャンセルすることで問題を修正し、WatchFaceService を保持できます。(fd48138

  • awaitDeferredWatchFace* にタイムアウトを追加し、watchfaceOverlayStyle NullPointerException を修正しました。新規インストール後や、CPU 負荷が高い DirectBoot シナリオなど、通常の状況ではタイムアウトしません。close() の後に getWatchfaceOverlayStyle が呼び出された場合の NPE も修正しました。(a4c3a5a

バージョン 1.1.0

2022 年 6 月 15 日

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

1.0.0 以降の重要な変更

編集機能の改善:

  • 階層型スキーマのサポートが追加され、エディタ UI でスタイルの階層を記述できるようになりました。ウォッチフェイス エディタとコンパニオン エディタで使用する別々のアイコンを指定できるようになりました。
  • ウォッチフェイスの複数のインスタンスのオプトイン サポートにより、各インスタンスにすべての API サーフェスで利用できる一意の ID が割り当てられるようになりました。
  • ComplicationSlots に、エディタで使用するための人が読める形式の名前を指定できるようになりました。
  • コンパニオン エディタから表示される厳選されたスタイル セレクションである、「フレーバー」スタイルの試験運用版サポートが追加されました。
  • ウォッチフェイスの 2 つのインスタンスの編集の読み込み時に、ウォッチフェイス インスタンスがリソースを共有し、メモリを節約できるようになりました。
  • ウォッチフェイス エディタでウォッチフェイスの追加機能を選択するときに、現在のプロバイダが事前に選択されるようになりました。

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

  • プライマリ データソースとセカンダリ データソースに ComplicationType を指定できるようになり、デベロッパーは初期状態での柔軟性が向上するようになりました。
  • ComplicationDataTimeline を追加しました。これにより、ウォッチフェイスに配信される時間ゲート付きのデータのシーケンス(キャッシュして自動的に更新することが可能)を提供してウォッチフェイスに配信することができます。たとえば、さまざまな時間帯における当日の天気予報や、カレンダーの複数の予定を表示するなどです。
  • ウォッチフェイスの追加機能のプロバイダの ComponentNameComplicationData の一部です。
  • ウォッチフェイスの追加機能がキャッシュされるようになりました。これにより、ウォッチフェイスを切り替える際のエクスペリエンスが向上します。

その他の変更点:

  • UserStyleSchemaComplicationSlots を XML で定義できるようになりました。これにより、ウォッチフェイスの構築が簡素化され、システムからのメタデータ クエリが高速になります。
  • ウォッチフェイスが、システム オーバーレイのレンダリングに使用する色に影響を与えられるようになりました。

バージョン 1.1.0-rc01

2022 年 5 月 18 日

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

新機能

  • ウォッチフェイス XML のサポートのユーザービリティについて一部変更し、ComplicationSlotBounds や補助参照を簡単に指定できるようにしました。エッジのウォッチフェイスの追加機能 BoundingArc の試験は drawHighlight まで継続されますが、その使用は現時点では推奨されません。

API の変更

  • BoundingArc パラメータを受け入れる試験運用版のオーバーロード drawHighlight を追加しました。(I705f8
  • ウォッチフェイスの XML でリソース参照がサポートされるようになりました。XML とコードの両方で同じ定数を使用できます。(I3ef61
  • ComplicationSlotBoundscenter_xcenter_ysize_xsize_y の形式で定義する機能が追加されました。また、リソース参照を使用して異なる単位(dp)を使用できるようになりました。(Iace98

バグの修正

  • 間違ったコンテキストでタスクを実行していた runBlockingWithTracing を修正しました。(4f595fe
  • BaseEditorSession.close を同期にしました。BaseEditorSession.close が非同期であることによる問題とは、ComplicationDataSourceInfoRetriever のリリースが遅すぎて logcat で警告スパムが発生することです。これは無害と思われますが、logcat のスパムは業務の邪魔になるもので、避ける必要があります。(35a5308

バージョン 1.1.0-beta02

2022 年 5 月 11 日

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

新機能

  • 新しい ComplicationData タイプの試験運用サポートを追加しました。これはまだご利用いただけませんが、今後の情報をお待ちください。

API の変更

  • BoundingArc を追加しました。これはウォッチフェイスの追加機能用スロットのジオメトリを記述する試験運用版クラスです。これは ComplicationSlot に追加され、ComplicationSlotStateWatchFaceMetadataClient に組み込まれました。(I61a40
  • UserStyleSetting XML で設定を継承する機能を追加しました。これにより、詳細度が低くなり、ウォッチフェイス間で設定を共有できます。(Ief841
  • ComplicationData の新しい試験運用タイプとして、ListComplicationDataProtoLayoutComplicationData の 2 つを追加しました。現在、これらのタイプのレンダリングはサポートされていないため、WearOS は ComplicationDataSource's マニフェストにこれらのタイプが追加されても認識しません。(I1811c

バグの修正

  • TimeLineEntry 型のシリアル化を修正しました。TimeLineEntry 型をシリアル化していなかったため、NoData 型のキャッシュされた TimeLineEntries が親ウォッチフェイスの追加機能の型を持っていると誤って解釈され、存在しない必須フィールドへのアクセス時に NPE が発生することがありました。(55ffdf5
  • setComplicationData がタイムライン フィールドをドロップするバグを修正しました(fb392f5
  • runBlockingWithTracing が原因で NPE が発生することがあるバグを修正しました(12ca62e
  • ウォッチフェイスの追加機能の受信時に ClassNotFoundException: android.support.wearable.complications.ComplicationText が発生することがあるバグを修正しました(217942d9
  • EGL14.eglCreateContext が呼び出されたときにのみ onBackgroundThreadGlContextCreated を呼び出す GlesRenderer.backgroundThreadInitInternal のバグを修正しました。スクリーンショットに verticalFlip が原因の視覚的な不具合があった別のバグを修正しました(c674ad2
  • WatchFaceService XML バージョン チェックで、間違ったパッケージから読み込んでいたバグを修正しました(dfa06f3
  • プレースホルダ転送形式で内部バンドルが使用されるようになりました。非表示の内部 a.s.w.c.ComplicationData を使用する可能性がある既存のウォッチフェイスを、プレースホルダで壊すことがないようにする必要があります。以前は、NoDataComplication データの転送形式により、通常のフィールドにプレースホルダが保存されていましたが(古いウォッチフェイスでは、意図しないプレースホルダ文字列がレンダリングされるため問題がありました)、現在は内部バンドルを使用してこれを完全に分離しています。(d5e7bd2

バージョン 1.1.0-beta01

2022 年 4 月 20 日

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

API の変更

  • WatchFaceMetadataClient メソッド(getUserStyleSchemagetComplicationSlotMetadataMapgetUserStyleFlavors)と HeadlessWatchFaceClient.getUserStyleFlavors が、WatchFaceException ではなく、未確認の RuntimeException をスローするようになりました。(I0718a
  • WatchFaceMetadataClient.WatchFaceException をクラスから移動し、再利用できるようにしました。(I4e869

バグの修正

  • ComplicationSlotBounds を一部送信したときに WatchFaceMetadataClient がクラッシュすることがなくなりました。(Iaafd

バージョン 1.1.0-alpha05

2022 年 4 月 6 日

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

新機能

  • ComplicationData.dataSource を調べることにより、どのデータソースが ComplicationData を送信したかを確認できるようになりました。一部のウォッチフェイスでは、これを利用してウォッチフェイスの追加機能の表示をカスタマイズできます。(I44a73

API の変更

  • Renderer.CanvasRendererRenderer.GlesRenderer が非推奨になり、Renderer.CanvasRenderer2Renderer.GlesRenderer2 に置き換えられました。これらはレンダリング メソッドに渡される SharedAssets をサポートします。Java の相互運用のために ListenableCanvasRenderer2ListenableGlesRenderer2 を導入しました。(I31ffa
  • フレーバー(スタイル設定されたウォッチフェイスの事前構成済みリスト)を定義する @WatchFaceFlavorsExperimental アビリティを追加しました。(I04dd0
  • Renderer.sharedAssets が StateFlow になり、使用されていない Renderer.SharedAssetsFactory が削除されました。(I12ac5
  • UserStyleSchema.userStyleSettings が非推奨ではなくなりました。(Iba7e3
  • HeadlessWatchFaceClient.getUserStyleSchemaDigestHash を追加しました。これにより、HeadlessWatchFaceClient は、ダイジェスト ハッシュを計算する前に AIDL でスキーマを渡す際の比較的低いオーバーヘッドを回避できます。(I33597
  • isUserStyleSchemaStaticWatchFaceMetadataClient に追加しました。これは、ウォッチフェイス APK が更新されない限り UserStyleSchema は変化しないと信頼できる場合にのみ、true になります。(I45a3f
  • スキーマのダイジェスト ハッシュを計算する getDigestHashUserStyleSchema に追加しました。これにより、UserStyleSchema が変化したかどうかを効率的に判断できます。(I2063d
  • METADATA_KEY_DATA_SOURCE_DEFAULT_CONFIGURATION_SUPPORTED の名前が METADATA_KEY_DATA_SOURCE_DEFAULT_CONFIG_SUPPORTED に変更されました。(I9ba5d
  • UserStyleSetting.OnWatchEditorData の名前が UserStyleSetting.WatchFaceEditorData に変更されました。これには、ウォッチフェイス上のエディタでのみ使用されるデータが格納されます。(If3afb

バージョン 1.1.0-alpha04

2022 年 3 月 9 日

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

API の変更

  • 最新の ComplicationData が常に使用できるとは限らない(キャッシュ内の ComplicationData の有効期限切れなど)ため、オプションのプレースホルダ ComplicationData で NoDataComplication を拡張し、ComplicationText.PLACEHOLDERMonochromaticImage.PLACEHOLDERSmallImage.PLACEHOLDERPhotoImage.PLACEHOLDER を追加しました。これらの使用は、NoDataComplicationData プレースホルダのコンテキスト内でのみ許可されます。選択する場合は、これらのプレースホルダをグレーのボックス / アーチでレンダリングすることをおすすめします。(I6285d
  • ウォッチフェイスの追加機能のいずれかの項目が変更される可能性があるリファレンス Instant の後の次の Instant をお知らせする ComplicationData.getNextChangeInstant を追加しました。これは、ウォッチフェイスの追加機能の更新のフレームをスケジュール設定するために内部で使用するものです。たとえば、ウォッチフェイスが通常 1 分間に 1 回更新される場合、ストップ ウォッチのウォッチフェイスの追加機能を設定すると、更新は 1 秒間に 1 回になります。(I7ceb2
  • EditorSession.watchFaceId がすべての API レベルで使用できるようになりました。さらに、その値は常に WatchState.watchFaceInstanceId と一致するようになりました。(I323b9
  • 根本的な問題がフレームワークで修正されたため、getPendingIntentForTouchEvent API は不要となり、関連する API をすべて削除しました。ホームボタンが押された場合でも、PendingIntents を呼び出すためにウォッチフェイスで何か特別な操作を行う必要はありません。(I1f2e8
  • レンダリングがスクリーンショットの場合に true になる RendererParameters.isForScreenShot を追加しました。アニメーションがある一部のウォッチフェイスは、最適な表示を実現するよう調整するためにこの変更点を把握する必要があります。(I96d99
  • エラーの発生に対するコンテキストを提供するため WatchFaceExceptionWatchFaceExceptionReason を追加しました。(I01d15
  • ComplicationDataSourceService.onImmediateComplicationRequest を削除し、代わりに ComplicationRequest.immediateResponseRequired を追加して、プロバイダがすぐに(100 ms 未満推奨)対応する必要があることを伝えるようにしました。この機能は、特権的な com.google.android.wearable.permission.USE_IMMEDIATE_COMPLICATION_UPDATE 権限で保護されています。(Ie6b23
  • Tiramisu DP2 と一致するよう core と appcompat の null 可能性を更新しました。(I0cbb7

バグの修正

  • ウォッチフェイス アプリは、スキーマ検証に不合格だった場合に例外を出してクラッシュするようになりました。(Ia400f

バージョン 1.1.0-alpha03

2022 年 2 月 9 日

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

API の変更

  • 階層型スタイル スキーマの試験運用版サポートを追加しました。androidx.wear.watchface.style.UserStyleSetting.Option に新しいプロパティ childSettings を追加しました(初期段階では ListOption での使用のみ可能)。これにより、スタイルの階層を記述して Editor UI で使用できるようになります。基となる UserStyle は変更されず、Map<String, ByteArray> のままです。(Iaf6f4
  • WatchFace.OverlayStyle を追加しました。これにより、システム ステータスのオーバーレイのレンダリングをウォッチフェイスで設定できるようになります。(I8520d
  • CanvasRenderer の新しいオプションのコンストラクタ パラメータ clearWithBackgroundTintBeforeRenderingHighlightLayer を追加しました。デフォルト値は false です。true に設定すると、キャンバスが背景色の色合いで消去されます。(Ie01e5
  • androidx.watchface.complications.datasource.DEFAULT_CONFIGURATION_SUPPORTED メタデータキーを追加しました。これにより、ウォッチフェイスの追加機能のデータソースが設定なしでデフォルト値を提供できることを示せるようになります。(Icc0d4
  • ウォッチフェイスを編集するとき、一般的にはインタラクティブ インスタンスとヘッドレス インスタンスの両方が存在します。メモリを節約するために Renderer.SharedAssets を導入し、ウォッチフェイスのレンダラがインスタンス間で不変のデータ(テクスチャやシェーダーなど)を共有できるようにしました。GlesRenderer.setEglConfigGlesRenderer.setEglDisplay はサポートが終了しており、設定可能にすることは意図されていません(未定義の動作が発生する可能性があります)。(I0d9e7
  • setNameResourceIdsetScreenReaderNameResourceId(文字列リソースを参照)を ComplicationSlot.Builder に追加し、対応するゲッターを androidx.wear.watchface.client.ComplicationSlotState に追加しました。これにより、システムで ComplicationSlot の名前を取得し、システムがエディタとスクリーン リーダーで使用できるようになります。(If6c6a
  • WatchfaceMetadataClient.getUserStyleSchemagetComplicationSlotMetadataMapRemoteException ではなく WatchFaceException をスローするようになりました。(I86f11
  • onSynchronousComplicationRequest と、関連する ComplicationDataSourceService の関数の名前が onImmediateComplicationRequest などに変更されました。(I87ba0
  • ウォッチフェイス エディタはコンパニオン エディタに比べて画面のスペースがかなり小さいため、ウォッチフェイス エディタ用に異なるアイコンをサポートすることが推奨されます。このパッチにより、すべての UserStyleSettings(および必要に応じて Option クラス)に、OnWatchEditorData が追加されます(現在のところアイコンのみを含む)。(If1886
  • Java の相互運用性を向上させるために、ListenableGlesRenderer のコンストラクタに @JvmOverloads を追加しました。(I2974a

バグの修正

  • ListenableGlesRenderer のコンストラクタが @Throws(GlesException::class) として正しくマークされるようになり、Java でこのクラスを拡張できるようになりました。(Iac6d0
  • PhotoImageComplicationData tapAction が正しく処理されないバグを修正しました。(I1cc30

バージョン 1.1.0-alpha02

2022 年 1 月 12 日

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

新機能

  • デバッグとテストを補助するため、ComplicationData と関連サブクラスで、hashCode メソッド、equals メソッド、toString メソッドがオーバーライドされ、簡単に連携できるようになりました。

API の変更

  • WatchfaceMetadataClient メソッドが必要に応じて再度 RemoteExceptions をスローするようになりました。これにより、クライアント コードでウォッチフェイスからエラーを簡単にキャッチできるようになります。(I78785
  • ComplicationData とサブクラスに、hashCode、equals、toString が追加されました。(I24bc6

バージョン 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.1

2022 年 2 月 9 日

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

バグの修正

  • PhotoImageComplicationData tapAction が正しく処理されないバグを修正しました。(I1cc30

バージョン 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