開始使用資訊方塊

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

Groovy

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

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

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

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

Kotlin

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

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

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

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

建立設定方塊

如果想從應用程式提供設定方塊，請建立可以擴充 TileService 的類別並實作方法，如以下程式碼範例所示：

Kotlin

private val RESOURCES_VERSION = "1"
class MyTileService : TileService() {
    override fun onTileRequest(requestParams: RequestBuilders.TileRequest) =
        Futures.immediateFuture(Tile.Builder()
            .setResourcesVersion(RESOURCES_VERSION)
            .setTimeline(Timeline.Builder().addTimelineEntry(
                TimelineEntry.Builder().setLayout(
                    Layout.Builder().setRoot(
                        Text.Builder().setText("Hello world!").setFontStyle(
                            FontStyle.Builder().setColor(argb(0xFF000000)).build()
                        ).build()
                    ).build()
                ).build()
            ).build()
        ).build())

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

Java

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)
            .setTimeline(new Timeline.Builder()
                .addTimelineEntry(new TimelineEntry.Builder()
                    .setLayout(new Layout.Builder()
                        .setRoot(new Text.Builder()
                            .setText("Hello world!")
                            .setFontStyle(new FontStyle.Builder()
                                .setColor(argb(0xFF000000)).build()
                            ).build()
                        ).build()
                    ).build()
                ).build()
            ).build()
        );
   }

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

接下來，請在 AndroidManifest.xml 檔案的 <application> 標記中新增服務。

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

權限和意圖篩選器會把此服務註冊為設定方塊提供者。

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

透過手機設定資訊方塊時，請用預覽中繼資料標記顯示資訊方塊的預覽畫面。

建立設定方塊的使用者介面

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

基礎版面配置元素

系統支援以下幾種視覺元素：

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

質感元件

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

  • Button：可在其中放置圖示的可按式圓形元件。
  • Chip：可在其中放置最多兩行文字，並可選擇加入圖示的可按式體育場形元件。
  • CompactChip：可在其中放置單行文字的可按式體育場形元件。
  • TitleChip：和 Chip 用途類似的可點選體育場形元件，但是高度更高，可以容納標題文字。
  • CircularProgressIndicator：可放置在 ProgressIndicatorLayout 當中的圓形進度指標，以便在螢幕邊緣顯示進度。

版面配置容器

系統支援以下容器：

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

質感版面配置

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

  • PrimaryLayout：把單一主要操作 CompactChip 放置於底部，並在上方置中顯示內容。
  • MultiSlotLayout：放置主要和次要標籤，並在之間放置選用內容，並可選擇在底部顯示 CompactChip。
  • ProgressIndicatorLayout：將 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 版面配置元素，並期望可以成功解析。您應該改為覆寫 onResourcesRequest() 方法，並手動提供所有資源。

您可以透過以下兩種方式在 onResourcesRequest() 方法中提供圖片：

Kotlin

override fun onResourcesRequest(
    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> onResourcesRequest(
       @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()
);
}