開始使用資訊方塊

如果想為應用程式提供資訊方塊，請把下列依附元件加入應用程式的 build.gradle 檔案內。

Groovy

dependencies {
    // Use to implement support for wear tiles
    implementation "androidx.wear.tiles:tiles:1.4.1"

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

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

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

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

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

Kotlin

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

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

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

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

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

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

核心概念

資訊方塊的建構方式與 Android 應用程式不同，且採用不同的概念：

  • 版面配置範本：定義螢幕上視覺元素的整體排列方式。資訊方塊會使用 EdgeContentLayout 版面配置範本，其中包含螢幕邊緣周圍的進度指標，或是 PrimaryLayout，後者不會顯示這項指標。
  • 版面配置元素：代表個別的圖形元素，例如 Button 或 Chip，或是使用 Column、MultiButtonLayout、MultiSlotLayout 或類似元素將多個此類元素分組在一起。這些元素會嵌入版面配置範本中。
  • 資源： ResourceBuilders.Resources 物件包含一個地圖，其中包含繪製版面配置所需的 Android 資源 (圖片) 鍵/值組合，以及版本。
  • 時間軸：TimelineBuilders.Timeline 物件是一或多個版面配置物件的清單。您可以提供各種機制和運算式，指出轉譯器應在何時從一個版面配置物件切換至另一個版面配置物件，例如在特定時間停止顯示版面配置。
  • 狀態：在資訊方塊和應用程式之間傳遞的 StateBuilders.State 類型資料結構，可讓這兩個元件相互通訊。舉例來說，如果使用者輕觸資訊方塊上的按鈕，狀態會保留按鈕的 ID。您也可以使用對應表來交換資料類型。
  • 圖塊：代表圖塊的 TileBuilders.Tile 物件，包含時間軸、資源版本 ID、新鮮度間隔和狀態。
  • Protolayout：這個字詞會出現在各種與資訊方塊相關的類別名稱中，並指的是 Wear OS Protolayout 程式庫，這是在各種 Wear OS 途徑中使用的圖形程式庫。

建立資訊方塊

如要從應用程式提供資訊方塊，請實作 TileService 類型的服務，並在資訊清單中註冊該服務。因此，系統會在呼叫 onTileRequest() 時要求必要的資訊方塊，以及在呼叫 onTileResourcesRequest() 時要求資源。

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

權限和意圖篩選器會將此服務註冊為資訊方塊提供者。

當使用者透過手機或手錶設定資訊方塊時，可看到圖示、標籤、說明和預覽資源。

部署應用程式，並將資訊方塊新增至資訊方塊輪轉介面 (開發人員還有其他更方便預覽資訊方塊的方式，但目前請先手動操作)。

圖 1. 「Hello World」資訊方塊。

如需完整範例，請參閱 GitHub 上的程式碼範例或程式碼研究室。

建立資訊方塊 UI

資訊方塊的版面配置是以建構工具模式編寫。資訊方塊的版面配置在建構時採用樹狀結構，由版面配置容器和基礎版面配置元素組成。每個版面配置元素都有屬性，您可以透過各種 setter 方法進行設定。

基本的版面配置元素

系統支援 protolayout 程式庫的下列視覺元素和 Material 元件：

  • Text：轉譯字串，可選擇是否要換行。
  • Image：算繪圖片。
  • Spacer：提供元素之間的間距，或可在設定背景顏色時充當分隔線。

Material 元件

除了基礎元素之外，protolayout-material 程式庫還有提供其他元件，可確保資訊方塊設計方式符合 Material Design 使用者介面的建議事項。

  • Button：可在其中放置圖示的可按式圓形元件。

  • Chip：可在其中放置最多兩行文字，並可選擇加入圖示的可按式體育場形元件。

  • 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(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 版面配置

除了基礎版面配置之外，protolayout-material 程式庫還有提供幾種可以保持一貫不變的版面配置，以便把元素固定在特定的「位置」上。

  • PrimaryLayout：把單一主要操作 CompactChip 放置於底部，並在上方置中顯示內容。

  • MultiSlotLayout：放置主要和次要標籤，並在兩個標籤之間放置選用內容，另可視需要在底部放置 CompactChip。

  • MultiButtonLayout：放置根據 Material Design 指南排列的一組按鈕。

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

Spannable

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