功能块使用入门

如需开始在应用中提供功能块，请在应用的 build.gradle 文件中添加以下依赖项。

Groovy

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

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

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

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

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

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

Kotlin

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

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

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

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

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

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

注意：此 API 是异步的，并且广泛依赖于 ListenableFuture。如需详细了解此概念，请参阅使用 ListenableFuture。

创建功能块

如需在应用中提供功能块，请创建一个扩展 TileService 的类并实现相应方法，如以下代码示例所示：

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

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

<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

权限和 intent 过滤器会将此服务注册为功能块提供程序。

当用户在手机或手表上配置功能块时，系统会向用户显示图标、标签、说明和预览资源。

功能块服务生命周期概览

在应用清单中创建并声明 TileService 后，您就可以响应功能块服务的状态变化。

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

重要提示： 您的 TileService 仍会经历典型的 Service 生命周期。不过，TileService 与大多数其他绑定服务不同，因为它包含您的应用可以响应的 TileService 专用生命周期方法。系统会在两个单独的异步线程中调用 Service 生命周期方法和 TileService 生命周期方法。

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

• onTileAddEvent()：只有在用户首次添加功能块且用户移除并重新添加功能块时，系统才会调用此方法。这是执行任何一次性初始化的最佳时间。

  只有在重新配置一组功能块时，系统才会调用 onTileAddEvent()，而不是在系统每次创建功能块时都调用。例如，当设备重新启动或开机时，系统不会针对已添加的功能块调用 onTileAddEvent()。您可以改用 getActiveTilesAsync() 获取您名下哪些功能块处于活动状态的快照。

• onTileRemoveEvent()：只有在用户移除您的功能块时，系统才会调用此方法。

• onTileEnterEvent()：当此提供程序提供的功能块显示在屏幕上时，系统会调用此方法。

• onTileLeaveEvent()：当此提供程序提供的功能块在屏幕上离开视野时，系统会调用此方法。

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

• onTileResourcesRequest()：当系统从此提供程序请求资源包时，系统会调用此方法。这可能会在首次加载功能块时发生，也可能会在资源版本发生变化时发生。

注意： 请勿要求（或依赖于）相应阶段按任何特定顺序发生。只有在用户添加您的功能块时，才能调用 onTileAddEvent()。onTileEnterEvent() 和 onTileLeaveEvent() 可能会在整个 TileService 生命周期内被多次调用。如果用户不移除功能块，系统将永远不会调用 onTileRemoveEvent()。

查询哪些功能块处于活动状态

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

注意： 结果反映的是发出调用时有效功能块的列表，该列表在收到结果时可能会发生变化。使用 onTileAddEvent() 和 onTileRemoveEvent() 回调来安排在功能块变为活动或非活动状态时需要执行的操作。

为功能块创建界面

功能块的布局是使用构建器模式编写的。功能块布局构建完毕后就像是一棵由布局容器和基本布局元素组成的树。每个布局元素都有其属性，您可以通过各种 setter 方法设置这些属性。

注意：可以在布局中显示的嵌套元素的数量是有限的。如果超出相应限制，系统会忽略布局更新，并显示功能块之前的状态。

基本布局元素

支持 protolayout 库中的以下视觉元素以及 Material 组件：

• Text：渲染文本字符串，可选择是否换行。
• Image：渲染图片。
• Spacer：设置元素之间的内边距，也可在设置背景颜色时用作分隔线。

Material 组件

除了基本元素之外，protolayout-material 库还提供了一些组件，用于确保功能块设计符合 Material Design 界面建议。

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

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

  注意：如果您在 Column 元素内使用 Chip 元素，请将这两个元素的宽度均设置为 expand()。

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

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

• CircularProgressIndicator：可放在 EdgeContentLayout 内的圆形进度指示器，用于围绕屏幕边缘显示进度。

布局容器

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

• Row：一个接一个地水平排列子元素。
• Column：一个接一个地垂直排列子元素。
• Box：将一个子元素叠加在另一个子元素上。
• Arc：沿着环形排列子元素。
• Spannable：将特定的 FontStyles 应用于文本的某些部分以及交错文本和图片。如需了解详情，请参阅 Spannable。

每个容器可以包含一个或多个子元素，这些子元素本身也可以是容器。例如，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 放在底部，内容居中置于其上。

  注意：使用此布局时，您不能调用 expand() 来设置内容的高度。否则，您可能会看到空白功能块。
  
  不过，您可以对内容的宽度调用 expand()，以使用父元素外边距之间的所有空间。

• MultiSlotLayout：放置主标签和次级标签，在两个标签之间放置可选内容，并在底部放置可选的 CompactChip。

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

• EdgeContentLayout：将内容沿着屏幕边缘放置，例如 CircularProgressIndicator。使用此布局时，系统会自动为其中的内容应用适当的外边距和内边距。

弧形

支持以下 Arc 容器子元素：

• ArcLine：沿着弧形渲染一条曲线。
• ArcText：沿着弧形渲染曲线文本。
• ArcAdapter：沿着弧形渲染基本布局元素，在弧线的切线方向上进行绘制。

注意：使用 ArcText 会沿着弧形绘制曲线文本，而在 ArcAdapter 中使用 Text 则会沿着弧线的切线绘制直线文本。

如需了解详情，请参阅每种元素类型的参考文档。

修饰符

对于每种可用的布局元素，您都可以选择对其应用修饰符。这些修饰符有以下用途：

• 更改布局的视觉外观。例如，为布局元素添加背景、边框或内边距。
• 添加有关布局的元数据。例如，为布局元素添加 semantics 修饰符，以便与屏幕阅读器结合使用。
• 添加功能。例如，为布局元素添加 clickable 修饰符，使用户可与功能块互动。如需了解详情，请参阅与功能块互动。

例如，我们可以自定义 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();
}

Spannable

Spannable 是一种特殊的容器，其元素布局方式与文本类似。如果您想仅针对一大段文本中的一个子字符串应用不同样式，使用 Text 元素是不可能实现的，此时 Spannable 就非常有用。

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() 方法中，您可以通过以下两种方式提供图片：

• 使用 setAndroidResourceByResId() 提供可绘制资源。
• 使用 setInlineResource() 以 ByteArray 形式提供动态图片。

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