Erste Schritte mit Kacheln

Wenn Sie Kacheln über Ihre App bereitstellen möchten, fügen Sie der build.gradle-Datei Ihrer App die folgenden Abhängigkeiten hinzu.

Groovy

dependencies {
    // Use to implement support for wear tiles
    implementation "androidx.wear.tiles:tiles:1.5.0-alpha04"

    // Use to utilize standard components and layouts in your tiles
    implementation "androidx.wear.protolayout:protolayout:1.3.0-alpha04"

    // Use to utilize components and layouts with Material Design in your tiles
    implementation "androidx.wear.protolayout:protolayout-material:1.3.0-alpha04"

    // Use to include dynamic expressions in your tiles
    implementation "androidx.wear.protolayout:protolayout-expression:1.3.0-alpha04"

    // Use to preview wear tiles in your own app
    debugImplementation "androidx.wear.tiles:tiles-renderer:1.5.0-alpha04"

    // Use to fetch tiles from a tile provider in your tests
    testImplementation "androidx.wear.tiles:tiles-testing:1.5.0-alpha04"
}

Kotlin

dependencies {
    // Use to implement support for wear tiles
    implementation("androidx.wear.tiles:tiles:1.5.0-alpha04")

    // Use to utilize standard components and layouts in your tiles
    implementation("androidx.wear.protolayout:protolayout:1.3.0-alpha04")

    // Use to utilize components and layouts with Material Design in your tiles
    implementation("androidx.wear.protolayout:protolayout-material:1.3.0-alpha04")

    // Use to include dynamic expressions in your tiles
    implementation("androidx.wear.protolayout:protolayout-expression:1.3.0-alpha04")

    // Use to preview wear tiles in your own app
    debugImplementation("androidx.wear.tiles:tiles-renderer:1.5.0-alpha04")

    // Use to fetch tiles from a tile provider in your tests
    testImplementation("androidx.wear.tiles:tiles-testing:1.5.0-alpha04")
}

Schlüsselkonzepte

Ansichten werden nicht wie Android-Apps erstellt und nutzen andere Konzepte:

  • Layoutvorlagen: Hiermit wird die Gesamtanordnung der visuellen Elemente auf dem Display definiert. Für eine Kachel wird entweder eine EdgeContentLayout-Layoutvorlage verwendet, die einen Fortschrittsbalken am Rand des Displays enthält, oder eine PrimaryLayout, die diesen Balken nicht anzeigt.
  • Layoutelemente: Stellt ein einzelnes grafische Element dar, z. B. Button oder Chip, oder mehrere solche Elemente, die mithilfe von Column, MultiButtonLayout, MultiSlotLayout oder ähnlichen Elementen gruppiert sind. Sie sind in einer Layoutvorlage eingebettet.
  • Ressourcen: ResourceBuilders.Resources-Objekte bestehen aus einer Zuordnung von Schlüssel/Wert-Paaren der Android-Ressourcen (Bilder), die zum Rendern eines Layouts erforderlich sind, und einer Version.
  • Zeitachse:Ein TimelineBuilders.Timeline-Objekt ist eine Liste mit einer oder mehreren Instanzen eines Layoutobjekts. Sie können verschiedene Mechanismen und Ausdrücke angeben, um anzugeben, wann der Renderer von einem Layoutobjekt zu einem anderen wechseln soll, z. B. um ein Layout zu einer bestimmten Zeit nicht mehr anzuzeigen.
  • Status: Eine Datenstruktur vom Typ StateBuilders.State, die zwischen Kachel und App übergeben wird, damit die beiden Komponenten miteinander kommunizieren können. Wenn beispielsweise auf eine Schaltfläche auf der Kachel getippt wird, enthält der Status die ID der Schaltfläche. Sie können Datentypen auch mithilfe einer Zuordnungstabelle austauschen.
  • Kachel: Ein TileBuilders.Tile-Objekt, das eine Kachel darstellt und aus einer Zeitachse, einer Ressourcenversions-ID, einem Aktualitätsintervall und einem Status besteht.
  • Protolayout:Dieser Begriff wird im Namen verschiedener Kacheln betreffender Klassen verwendet und bezieht sich auf die Wear OS Protolayout-Bibliothek, eine Grafikbibliothek, die auf verschiedenen Wear OS-Oberflächen verwendet wird.

Kachel erstellen

Wenn Sie eine Kachel aus Ihrer App bereitstellen möchten, implementieren Sie einen Dienst vom Typ TileService und registrieren Sie ihn in Ihrem Manifest. Daraufhin fordert das System die erforderlichen Kacheln bei Aufrufen von onTileRequest() und die erforderlichen Ressourcen bei Aufrufen von onTileResourcesRequest() an.

class MyTileService : TileService() {

    override fun onTileRequest(requestParams: RequestBuilders.TileRequest) =
        Futures.immediateFuture(
            Tile.Builder()
                .setResourcesVersion(RESOURCES_VERSION)
                .setTileTimeline(
                    Timeline.fromLayoutElement(
                        Text.Builder(this, "Hello World!")
                            .setTypography(Typography.TYPOGRAPHY_BODY1)
                            .setColor(argb(0xFFFFFFFF.toInt()))
                            .build()
                    )
                )
                .build()
        )

    override fun onTileResourcesRequest(requestParams: ResourcesRequest) =
        Futures.immediateFuture(
            Resources.Builder()
                .setVersion(RESOURCES_VERSION)
                .build()
        )
}
Tile.kt

Fügen Sie als Nächstes einen Dienst im <application>-Tag Ihrer AndroidManifest.xml-Datei hinzu.

<service
    android:name=".snippets.tile.MyTileService"
    android:label="@string/tile_label"
    android:description="@string/tile_description"
    android:icon="@mipmap/ic_launcher"
    android:exported="true"
    android:permission="com.google.android.wearable.permission.BIND_TILE_PROVIDER">
    <intent-filter>
        <action android:name="androidx.wear.tiles.action.BIND_TILE_PROVIDER" />
    </intent-filter>

    <meta-data android:name="androidx.wear.tiles.PREVIEW"
        android:resource="@drawable/tile_preview" />
</service>
AndroidManifest.xml

Der Berechtigungs- und Intent-Filter registriert diesen Dienst als Ansichtsanbieter.

Das Symbol, das Label, die Beschreibung und die Vorschau werden dem Nutzer angezeigt, wenn er Kacheln auf seinem Smartphone oder seiner Smartwatch konfiguriert.

Stellen Sie Ihre App bereit und fügen Sie die Kachel dem Ansichtenkarussell hinzu. Es gibt auch eine entwicklerfreundlichere Möglichkeit, eine Kachel in der Vorschau anzusehen, aber fürs Erste gehen Sie einfach manuell vor.

Abbildung 1: Kachel „Hallo Welt“

Ein vollständiges Beispiel finden Sie im Codebeispiel auf GitHub oder im Codelab.

Benutzeroberfläche für Kacheln erstellen

Das Layout einer Kachel wird mit einem Builder-Muster geschrieben. Das Layout einer Kachel ist wie ein Baum aufgebaut, der aus Layoutcontainern und grundlegenden Layoutelementen besteht. Jedes Layoutelement hat Eigenschaften, die Sie über verschiedene Setzermethoden festlegen können.

Grundlegende Layoutelemente

Neben Materialkomponenten werden die folgenden visuellen Elemente aus der protolayout-Bibliothek unterstützt:

  • Text: Rendert einen Textstring, optional mit Umbruch.
  • Image: Rendert ein Bild.
  • Spacer: Sorgt für einen Abstand zwischen Elementen oder kann als Trennlinie dienen, wenn Sie die Hintergrundfarbe festlegen.

Materialkomponenten

Neben den grundlegenden Elementen bietet die protolayout-material-Bibliothek Komponenten, die für ein Kachelndesign sorgen, das den Empfehlungen für die Material Design-Benutzeroberfläche entspricht.

  • Button: Klickbare kreisförmige Komponente, die ein Symbol enthalten soll.

  • Chip: Klickbare, stadionförmige Komponente, die bis zu zwei Textzeilen und ein optionales Symbol enthalten kann.

  • CompactChip: Klickbare, stadionförmige Komponente, die eine Textzeile enthält.

  • TitleChip: Klickbare, stadionförmige Komponente, ähnlich wie Chip, aber mit einer größeren Höhe, um Titeltext aufzunehmen.

  • CircularProgressIndicator: Kreisförmige Fortschrittsanzeige, die in einem EdgeContentLayout platziert werden kann, um den Fortschritt am Bildschirmrand anzuzeigen.

Layoutcontainer

Die folgenden Container werden zusammen mit Material-Layouts unterstützt:

  • Row: Hier werden untergeordnete Elemente horizontal nacheinander angeordnet.
  • Column: Hier werden untergeordnete Elemente vertikal nacheinander angeordnet.
  • Box: Überlagert untergeordnete Elemente.
  • Arc: Die untergeordneten Elemente werden in einem Kreis angeordnet.
  • Spannable: Hier werden Textabschnitten bestimmte FontStyles-Effekte hinzugefügt und Text und Bilder werden übereinander gelegt. Weitere Informationen finden Sie unter Spannbare Elemente.

Jeder Container kann ein oder mehrere untergeordnete Elemente enthalten, die selbst auch Container sein können. Ein Column kann beispielsweise mehrere Row-Elemente als untergeordnete Elemente enthalten, was zu einem gitterartigen Layout führt.

Eine Kachel mit einem Containerlayout und zwei untergeordneten Layoutelementen könnte beispielsweise so aussehen:

Kotlin

private fun myLayout(): LayoutElement =
    Row.Builder()
        .setWidth(wrap())
        .setHeight(expand())
        .setVerticalAlignment(VERTICAL_ALIGN_BOTTOM)
        .addContent(Text.Builder()
            .setText("Hello world")
            .build()
        )
        .addContent(Image.Builder()
            .setResourceId("image_id")
            .setWidth(dp(24f))
            .setHeight(dp(24f))
            .build()
        ).build()

Java

private LayoutElement myLayout() {
    return new Row.Builder()
        .setWidth(wrap())
        .setHeight(expand())
        .setVerticalAlignment(VALIGN_BOTTOM)
        .addContent(new Text.Builder()
            .setText("Hello world")
            .build()
        )
        .addContent(new Image.Builder()
            .setResourceId("image_id")
            .setWidth(dp(24f))
            .setHeight(dp(24f))
            .build()
        ).build();
}

Material-Layouts

Zusätzlich zu den einfachen Layouts bietet die protolayout-material-Bibliothek einige vordefinierte Layouts, die Elemente in bestimmten „Slots“ aufnehmen.

  • PrimaryLayout: Positioniert eine einzelne primäre Aktion CompactChip unten und den Inhalt darüber zentriert.

  • MultiSlotLayout: Hier werden primäre und sekundäre Labels mit optionalen Inhalten dazwischen und einem optionalen CompactChip unten platziert.

  • MultiButtonLayout: Hiermit werden eine Reihe von Schaltflächen positioniert, die gemäß den Material Design-Richtlinien angeordnet sind.

  • EdgeContentLayout: Positioniert Inhalte am Bildschirmrand, z. B. ein CircularProgressIndicator. Bei Verwendung dieses Layouts werden die entsprechenden Ränder und Abstände automatisch auf den Inhalt angewendet.

Bögen

Die folgenden untergeordneten Elemente von Arc-Containern werden unterstützt:

  • ArcLine: Damit wird eine gebogene Linie um den Bogen gerendert.
  • ArcText: Hiermit wird geschwungener Text im Bogen gerendert.
  • ArcAdapter: Hiermit wird ein einfaches Layoutelement im Bogen gerendert, das tangential zum Bogen gezeichnet wird.

Weitere Informationen finden Sie in der Referenzdokumentation zu den einzelnen Elementtypen.

Modifikatoren

Auf jedes verfügbare Layoutelement können optional Modifikatoren angewendet werden. Verwenden Sie diese Modifikatoren für die folgenden Zwecke:

  • Ändern Sie das Erscheinungsbild des Layouts. Fügen Sie dem Layoutelement beispielsweise einen Hintergrund, einen Rahmen oder einen Abstand hinzu.
  • Fügen Sie Metadaten zum Layout hinzu. Fügen Sie Ihrem Layoutelement beispielsweise einen semantischen Modifikator für die Verwendung mit Screenreadern hinzu.
  • Funktionen hinzufügen. Fügen Sie Ihrem Layoutelement beispielsweise einen anklickbaren Modifier hinzu, um die Kachel interaktiv zu machen. Weitere Informationen finden Sie unter Mit Kacheln interagieren.

So können wir beispielsweise das Standard-Aussehen und die Metadaten eines Image anpassen, wie im folgenden Codebeispiel gezeigt:

Kotlin

private fun myImage(): LayoutElement =
    Image.Builder()
        .setWidth(dp(24f))
        .setHeight(dp(24f))
        .setResourceId("image_id")
        .setModifiers(Modifiers.Builder()
            .setBackground(Background.Builder().setColor(argb(0xFFFF0000)).build())
            .setPadding(Padding.Builder().setStart(dp(12f)).build())
            .setSemantics(Semantics.builder()
                .setContentDescription("Image description")
                .build()
            ).build()
        ).build()

Java

private LayoutElement myImage() {
   return new Image.Builder()
           .setWidth(dp(24f))
           .setHeight(dp(24f))
           .setResourceId("image_id")
           .setModifiers(new Modifiers.Builder()
                   .setBackground(new Background.Builder().setColor(argb(0xFFFF0000)).build())
                   .setPadding(new Padding.Builder().setStart(dp(12f)).build())
                   .setSemantics(new Semantics.Builder()
                           .setContentDescription("Image description")
                           .build()
                   ).build()
           ).build();
}

Expandable-Anzeigen

Ein Spannable ist ein spezieller Containertyp, in dem Elemente ähnlich wie Text angeordnet werden. Das ist nützlich, wenn Sie nur einem Teilstring in einem größeren Textblock einen anderen Stil zuweisen möchten. Das ist mit dem Element Text nicht möglich.

Ein Spannable-Container ist mit Span Kindern gefüllt. Andere untergeordnete Elemente oder verschachtelte Spannable-Instanzen sind nicht zulässig.

Es gibt zwei Arten von Span-Unterelementen:

  • SpanText: Damit wird Text in einem bestimmten Stil gerendert.
  • SpanImage: ein Bild wird inline mit dem Text gerendert.

Sie können beispielsweise „Welt“ in einer Kachel „Hallo Welt“ kursiv formatieren und ein Bild zwischen die Wörter einfügen, wie im folgenden Codebeispiel gezeigt:

Kotlin

private fun mySpannable(): LayoutElement =
    Spannable.Builder()
        .addSpan(SpanText.Builder()
            .setText("Hello ")
            .build()
        )
        .addSpan(SpanImage.Builder()
            .setWidth(dp(24f))
            .setHeight(dp(24f))
            .setResourceId("image_id")
            .build()
        )
        .addSpan(SpanText.Builder()
            .setText("world")
            .setFontStyle(FontStyle.Builder()
                .setItalic(true)
                .build())
            .build()
        ).build()

Java

private LayoutElement mySpannable() {
   return new Spannable.Builder()
        .addSpan(new SpanText.Builder()
            .setText("Hello ")
            .build()
        )
        .addSpan(new SpanImage.Builder()
            .setWidth(dp(24f))
            .setHeight(dp(24f))
            .setResourceId("image_id")
            .build()
        )
        .addSpan(new SpanText.Builder()
            .setText("world")
            .setFontStyle(newFontStyle.Builder()
                .setItalic(true)
                .build())
            .build()
        ).build();
}

Mit Ressourcen arbeiten

Ansichten haben keinen Zugriff auf die Ressourcen Ihrer App. Das bedeutet, dass Sie einer Image-Layout-Komponente keine Android-Bild-ID übergeben können und erwarten können, dass sie aufgelöst wird. Überschreiben Sie stattdessen die Methode onTileResourcesRequest() und stellen Sie alle Ressourcen manuell bereit.

Es gibt zwei Möglichkeiten, Bilder in der onTileResourcesRequest()-Methode anzugeben:

Kotlin

override fun onTileResourcesRequest(
    requestParams: ResourcesRequest
) = Futures.immediateFuture(
Resources.Builder()
    .setVersion("1")
    .addIdToImageMapping("image_from_resource", ImageResource.Builder()
        .setAndroidResourceByResId(AndroidImageResourceByResId.Builder()
            .setResourceId(R.drawable.image_id)
            .build()
        ).build()
    )
    .addIdToImageMapping("image_inline", ImageResource.Builder()
        .setInlineResource(InlineImageResource.Builder()
            .setData(imageAsByteArray)
            .setWidthPx(48)
            .setHeightPx(48)
            .setFormat(ResourceBuilders.IMAGE_FORMAT_RGB_565)
            .build()
        ).build()
    ).build()
)

Java

@Override
protected ListenableFuture<Resources> onTileResourcesRequest(
       @NonNull ResourcesRequest requestParams
) {
return Futures.immediateFuture(
    new Resources.Builder()
        .setVersion("1")
        .addIdToImageMapping("image_from_resource", new ImageResource.Builder()
            .setAndroidResourceByResId(new AndroidImageResourceByResId.Builder()
                .setResourceId(R.drawable.image_id)
                .build()
            ).build()
        )
        .addIdToImageMapping("image_inline", new ImageResource.Builder()
            .setInlineResource(new InlineImageResource.Builder()
                .setData(imageAsByteArray)
                .setWidthPx(48)
                .setHeightPx(48)
                .setFormat(ResourceBuilders.IMAGE_FORMAT_RGB_565)
                .build()
            ).build()
        ).build()
);
}