开始使用磁贴

要开始从您的应用提供磁贴，请在应用的 build.gradle 文件中包含以下依赖项。

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")
}

创建磁贴

要从您的应用提供磁贴，请创建一个扩展 TileService 的类并实现方法，如下面的代码示例所示

Kotlin

// Uses the ProtoLayout namespace for tile timeline objects.
// If you haven't done so already, migrate to the ProtoLayout namespace.
import androidx.wear.protolayout.TimelineBuilders.Timeline
import androidx.wear.protolayout.material.Text
import androidx.wear.tiles.TileBuilders.Tile

private val RESOURCES_VERSION = "1"
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_DISPLAY1)
                        .setColor(argb(0xFF000000.toInt()))
                        .build()))
            .build())

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

Java

// Uses the ProtoLayout namespace for tile timeline objects.
// If you haven't done so already, migrate to the ProtoLayout namespace.
import androidx.wear.protolayout.TimelineBuilders.Timeline;
import androidx.wear.protolayout.material.Text;
import androidx.wear.tiles.TileBuilders.Tile;

public class MyTileService extends TileService {
    private static final String RESOURCES_VERSION = "1";

    @NonNull
    @Override
    protected ListenableFuture<Tile> onTileRequest(
        @NonNull TileRequest requestParams
    ) {
        return Futures.immediateFuture(new Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setTileTimeline(
                Timeline.fromLayoutElement(
                    new Text.Builder(this, "Hello world!")
                        .setTypography(Typography.TYPOGRAPHY_DISPLAY1)
                        .setColor(ColorBuilders.argb(0xFF000000))
                        .build()))
            .build()
        );
   }

   @NonNull
   @Override
   protected ListenableFuture<Resources> onTileResourcesRequest(
       @NonNull ResourcesRequest requestParams
   ) {
       return Futures.immediateFuture(new Resources.Builder()
               .setVersion(RESOURCES_VERSION)
               .build()
       );
   }
}

接下来，在 <application> 标签内添加一个服务AndroidManifest.xml 文件。

<service
   android:name=".MyTileService"
   android:label="@string/tile_label"
   android:description="@string/tile_description"
   android:icon="@drawable/tile_icon_round"
   android:roundIcon="@drawable/tile_icon_round"
   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>

权限和意图过滤器将此服务注册为磁贴提供程序。

当用户在手机或手表上配置磁贴时，会向用户显示图标、标签和说明。

使用预览元数据标签在手机上配置磁贴时显示磁贴的预览。

磁贴服务生命周期概述

在应用清单中创建并声明 TileService 后，您可以响应磁贴服务的状态更改。

TileService 是一个绑定服务。您的应用请求或系统需要与之通信时，就会绑定您的TileService。典型的绑定服务生命周期包含以下四个回调方法：onCreate()、onBind()、onUnbind() 和 onDestroy()。每次服务进入新的生命周期阶段时，系统都会调用这些方法。

除了控制绑定服务生命周期的回调之外，您还可以实现其他特定于TileService生命周期的使用方法。所有磁贴服务都必须实现onTileRequest()和onTileResourcesRequest()来响应系统发出的更新请求。

  • onTileAddEvent()：只有当用户第一次添加您的磁贴时，以及如果用户删除并再次添加您的磁贴时，系统才会调用此方法。这是执行任何一次性初始化的最佳时机。

    onTileAddEvent() 仅在磁贴集重新配置时调用，而不是在系统创建磁贴时调用。例如，当设备重新启动或电源开启时，不会为已添加的磁贴调用onTileAddEvent()。您可以使用getActiveTilesAsync()来获取属于您的哪些磁贴处于活动状态的快照。

  • onTileRemoveEvent()：只有当用户删除您的磁贴时，系统才会调用此方法。

  • onTileEnterEvent()：当此提供程序提供的磁贴出现在屏幕上时，系统会调用此方法。

  • onTileLeaveEvent()：当此提供程序提供的磁贴从屏幕上消失时，系统会调用此方法。

  • onTileRequest()：当系统从此提供程序请求新的时间线时，系统会调用此方法。

  • onTileResourcesRequest()：当系统从此提供程序请求资源包时，系统会调用此方法。这可能发生在第一次加载磁贴时，或者每当资源版本发生更改时。

查询哪些磁贴处于活动状态

活动磁贴是指已添加到手表上显示的磁贴。使用TileService的静态方法getActiveTilesAsync()来查询属于您的应用的哪些磁贴处于活动状态。

创建磁贴的UI

磁贴的布局使用构建器模式编写。磁贴的布局构建起来就像一棵树，它由布局容器和基本布局元素组成。每个布局元素都有属性，您可以通过各种设置器方法来设置这些属性。

基本布局元素

支持来自protolayout库的以下可视元素，以及Material 组件

  • Text：渲染文本字符串，可以选择换行。
  • Image：渲染图像。
  • Spacer：在元素之间提供填充，或者当您设置其背景颜色时，可以充当分隔符。

Material 组件

除了基本元素之外，protolayout-material库还提供了一些组件，这些组件可以确保磁贴设计符合 Material Design 用户界面建议。

  • Button：可点击的圆形组件，设计用于包含图标。

  • Chip：可点击的体育场形状组件，设计用于包含最多两行文本和一个可选图标。

  • CompactChip：可点击的体育场形状组件，设计用于包含一行文本。

  • TitleChip：可点击的体育场形状组件，类似于Chip，但高度更大，可以容纳标题文本。

  • CircularProgressIndicator：圆形进度指示器，可以放置在EdgeContentLayout内以在屏幕边缘显示进度。

布局容器

支持以下容器，以及Material 布局

  • Row：将子元素水平排列，一个接一个。
  • Column：将子元素垂直排列，一个接一个。
  • Box：将子元素叠加在一起。
  • Arc：将子元素呈圆形排列。
  • Spannable：将特定的FontStyles应用于文本部分，以及交错文本和图像。有关更多信息，请参阅Spannables。

每个容器可以包含一个或多个子元素，这些子元素本身也可以是容器。例如，Column可以包含多个Row元素作为子元素，从而形成网格状布局。

例如，具有容器布局和两个子布局元素的磁贴可能如下所示

Kotlin

private fun myLayout(): LayoutElement =
    Row.Builder()
        .setWidth(wrap())
        .setHeight(expand())
        .setVerticalAlignment(VALIGN_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 布局

除了基本布局之外，protolayout-material库还提供了一些精心设计的布局，用于将元素放在特定的“插槽”中。

  • PrimaryLayout：在底部放置单个主要操作CompactChip，并将内容居中放置在其上方。

  • MultiSlotLayout：放置主要和次要标签，以及可选内容和底部可选的CompactChip。

  • MultiButtonLayout：放置一组根据 Material 指南排列的按钮。

  • EdgeContentLayout：在屏幕边缘放置内容，例如CircularProgressIndicator。使用此布局时，其中的内容会自动应用适当的边距和填充。

弧形

支持以下Arc容器子元素

  • ArcLine：在弧形周围渲染一条曲线。
  • ArcText：在弧形中渲染曲线文本。
  • ArcAdapter：在弧形中渲染基本布局元素，绘制在弧形的切线上。

有关更多信息，请参阅每个元素类型的参考文档。

修饰符

每个可用的布局元素都可以选择应用修饰符。将这些修饰符用于以下目的

  • 更改布局的视觉外观。例如，为布局元素添加背景、边框或填充。
  • 添加有关布局的元数据。例如，为布局元素添加语义修饰符以与屏幕阅读器一起使用。
  • 添加功能。例如，为布局元素添加可点击修饰符以使您的磁贴具有交互性。有关更多信息，请参阅与磁贴交互。

例如，我们可以自定义Image的默认外观和元数据，如下面的代码示例所示

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();
}

Spannables

Spannable 是一种特殊的容器，其元素布局方式类似于文本。当您希望仅对较长文本块中的一个子字符串应用不同的样式时，这非常有用，而使用Text 元素则无法实现此功能。

Spannable 容器填充了 Span 子元素。不允许使用其他子元素或嵌套的Spannable 实例。

有两种类型的Span 子元素：

  • SpanText：以特定样式呈现文本。
  • SpanImage：在文本内联显示图像。

例如，您可以将“Hello world”磁贴中的“world”斜体化，并在单词之间插入图像，如下面的代码示例所示。

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();
}

使用资源

磁贴无法访问您的应用的任何资源。这意味着您不能将 Android 图片 ID 传递给Image 布局元素并期望它能够解析。相反，您需要重写 onTileResourcesRequest() 方法并手动提供任何资源。

在onTileResourcesRequest() 方法中提供图像有两种方法：

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()
);
}