このページは Cloud Translation API によって翻訳されました。

Watch Face Format のセットアップ

注: このページでは、ウォッチフェイスの構成を手動で管理するプロセスの一環として、WYSIWYG（見たまま編集）スタイルのツールを使用してウォッチフェイスをデザインする場合は、まずウォッチフェイススタジオのガイドをご覧ください。

このガイドでは、Watch Face Format を使用してウォッチフェイスを構成するのに必要なツールの手順、プロジェクト構造に関する推奨事項、その構造を作成するツールを適用するための手順ガイドを示します。

Android Studio を使ってみる

ウォッチフェイスの手動開発を始めるには、Android Studio を使用するのが最も簡単な方法です。ウォッチフェイスのサポートはカナリアチャンネルでご利用いただけます。

[File] > [New Project] をクリックします。
[Wear OS] で [基本のウォッチフェイス] を選択します。

これにより、完全に機能するウォッチフェイスに必要な構造が作成されます。

プロジェクトの構造

Watch Face Format を使用するカスタムウォッチフェイスを作成する場合、カスタムウォッチフェイスファイルを含む Android App Bundle は、Wear OS アプリのロジックを含む Android App Bundle から完全に分離する必要があります。Google Play を含む一部のアプリストアでは、Wear OS ロジックとカスタムウォッチフェイスの両方が含まれる Android App Bundle はアップロードできません。

Watch Face Format のバージョンを宣言する

新しいアプリのマニフェストファイル（AndroidManifest.xml）で、Watch Face Format の使用を示すアプリプロパティを調べます。

ウォッチフェイスフォーマットの一部の機能は、新しいバージョンでのみ利用できます。デバイスの互換性を最大限に高めるため、必要な機能をサポートする最小値にこのプロパティを設定し、minSdkVersion も一致するように設定します。アプリのバージョンを設定する方法について詳しくは、こちらをご覧ください。

<manifest ...>
    <!--
        Use SDK version 33 to support Watch Face Format (WFF) version 1 and
        higher, SDK version 34 to support WFF version 2 and higher, and so on.
    -->
    <uses-sdk
        android:minSdkVersion="34"
        android:targetSdkVersion="34" />

    <!--
        WFF is a resource-only format, so the hasCode attribute should be set to
        false to reflect this.
    -->
    <application
        android:label="@string/watch_face_name"
        android:hasCode="false"
        ...>
        <meta-data android:name="com.google.android.wearable.standalone"
            android:value="true" />
        <property
            android:name="com.google.wear.watchface.format.version"
            android:value="2" />
    </application>
</manifest>

ウォッチフェイスのメタデータを宣言する

アプリの res/xml リソースディレクトリに watch_face_info.xml というファイルがあります。ここでは、ウォッチフェイスのメタデータを定義します。

<?xml version="1.0" encoding="utf-8"?>
<WatchFaceInfo>

    <Preview value="@drawable/watch_face_preview" />
    <Category value="CATEGORY_EMPTY" />
    <AvailableInRetail value="true" />
    <MultipleInstancesAllowed value="true" />
    <Editable value="true" />
</WatchFaceInfo>

このファイルのフィールドは、次の詳細を表しています。

Preview

ウォッチフェイスのプレビュー画像を含むドローアブルを参照します。

Category

ウォッチフェイスのカテゴリを定義します。文字列か、@string/ref_name などの文字列への参照を指定する必要があります。各デバイスメーカーは、それぞれ独自のウォッチフェイスカテゴリのセットを定義できます。

デフォルト値: empty_category_meta。ウォッチフェイス選択ツールビューの一番下に、このウォッチフェイスを他の「空のカテゴリ」のウォッチフェイスと一緒にグループ化します。

AvailableInRetail

デバイスの販売店デモモードでウォッチフェイスを使用できるかどうか。ブール値、または @bool/watch_face_available_in_retail などのブール値への参照である必要があります。

デフォルト値: false

MultipleInstancesAllowed

ウォッチフェイスに複数のお気に入りを登録できるかどうか。ブール値、または @bool/watch_face_multiple_instances_allowed などのブール値への参照である必要があります。

デフォルト値: false

Editable

ウォッチフェイスが編集可能かどうか（つまり、ウォッチフェイスの設定や固定されていないウォッチフェイスの追加機能が 1 つ以上あるかどうか）。これは、お気に入りリストにあるウォッチフェイスの [編集] ボタンを表示または非表示にするために使用されます。

デフォルト値: false

ウォッチフェイス名を宣言する

アプリのマニフェストファイル（AndroidManifest.xml）では、android:label 属性をウォッチフェイスの名前に設定します。

<application android:label="@string/watch_face_name" >

ウォッチフェイスの詳細を宣言する

基本的な WFF ウォッチフェイスドキュメントの構造は次のとおりです。

<WatchFace width="450" height="450">
  <Scene>
    <!-- Content to be rendered -->
  </Scene>
</WatchFace>

Android Studio テンプレートは、res/raw/watchface.xml に基本的なドキュメントを提供します。さまざまな画面の形状とサイズをサポートするには、複数の形状とサイズのサポートを宣言します。

ルート要素は常に WatchFace です。height と width は、ウォッチフェイスで使用する座標空間の範囲を定義します。ウォッチフェイスは、使用されるデバイスに合わせて拡大縮小されます。height と width は実際のピクセルを表すものではありません。

Watch Face Format は、ウォッチフェイスに関するいくつかの詳細情報を整理します。

メタデータ（ウォッチフェイスのプレビュー画像に表示される時刻や歩数など）。
ユーザー構成。ウォッチフェイスのさまざまなカラーテーマ、ユーザーが切り替え可能な要素、複数の要素から選択できる要素など。Watch Face Format バージョン 2 では、ユーザー構成内に表示されるフレーバーが導入されています。各フレーバーは、プリセットのユーザー構成を指定し、ウォッチフェイスで時刻とともに表示される要素のタイプとスタイルを指定します。これらのプリセットを使用すると、視覚的に魅力的な要素のグループを簡単に作成できます。Wear OS コンパニオンアプリでは、ウォッチフェイスのさまざまなバリエーションがスクロール可能な行に表示されます。
ウォッチフェイスのビジュアル要素を含むシーン。シーンの終わりに近い要素ほど、他の要素の上に表示されます。そのため、一般的な順序は次のようになります。
- アナログ時計の針またはデジタル時計のテキスト
- 曜日やユーザーの歩数など、追加情報を表示する追加機能
- キャンプ場の画像など、文字盤に視覚的なアクセントや装飾を加えるその他のグラフィック
要素のグループ。複数の要素を同時に変更できます。シーン内でこれらのグループのバリエーションを作成できます。これにより、システムが省電力アンビエントモードに入ったときに、コンテンツを選択的に非表示にしたり変更したりできます。

属性は厳密に分類されており、頻度と有効な値に関するガイドラインが用意されているため、ウォッチフェイスを作成するときに起こりうるエラー要因をほぼ回避できます。

ウォッチフェイスの形状に関するサポートを宣言する（省略可）

この手順は、さまざまなサイズの文字盤で異なる動作をサポートする場合にのみ必要です。ウォッチフェイスがスマートウォッチのサイズに合わせて拡大縮小されることを許容する場合は、この手順をスキップできます。

アプリの res/xml リソースディレクトリで、watch_face_shapes.xml でサポートするウォッチフェイスの形状のセットを宣言します。

<WatchFaces>
    <WatchFace shape="CIRCLE" width="300" height="300"
               file="@raw/watchface"/>
    <WatchFace shape="CIRCLE" width="450" height="450"
               file="@raw/watchface_large_circle"/>
<WatchFaces>

次に、ウォッチフェイスの形状ごとにウォッチフェイスの外観と動作を定義します。シェイプファイルを定義していない場合は、watchface.xml という 1 つのファイルのみが必要です。

このセクションの例を使うと、未加工の XML ファイルは次のようになります。

res/raw/watchface.xml
res/raw/watchface_large_circle.xml

ウォッチフェイスのパブリッシャーを特定する（省略可）

必要に応じて、アプリのマニフェストファイルで、ウォッチフェイスのパブリッシャーの特定に使用できる任意の文字列、または使用するツール名とバージョンを宣言します。

<application ...>
    ...
    <property
        android:name="com.google.wear.watchface.format.publisher"
        android:value="<var>{toolName}-{toolVersion}</var>" />
</application>

ウォッチフェイスの正確性とパフォーマンスを確認する

開発中、および Google Play にアップロードする前に、Android Studio の組み込みの Watch Face Format バリデーションを使用して、ウォッチフェイスに構文エラーがないことを確認します。これにより、コード内のエラーが自動的にハイライト表示され、バージョンが認識されます。

また、メモリ使用量ツールを実行して、ウォッチフェイスがメモリ使用量の要件を満たしていることを確認する必要があります。

公開に備えて、メモリ使用量を最適化する方法とメモリ使用量を確認する方法についてご確認ください。
開発サイクルの 1 つとして XML バリデータを使用する方法についてご確認ください。

ウォッチフェイスの App Bundle をビルドする

ウォッチフェイスをビルドしてデプロイする最も簡単な方法は、Android Studio を使用することです。Android Studio には、ウォッチフェイスの実行構成のサポートが組み込まれています。[実行] ボタンをクリックすると、Android Studio はウォッチフェイスをデバイスまたはエミュレータにデプロイし、アクティブなウォッチフェイスとして設定します。

ウォッチフェイスのサンプル

ウォッチフェイス形式のプロジェクトのその他のサンプルは、GitHub で入手できます。

あなたへのおすすめ

注: JavaScript がオフになっている場合はリンクテキストが表示されます
AAPT2
Jetpack Compose の基本
CameraX のスタートガイド