Pembuatan versi kartu

Di perangkat Wear OS, kartu dirender oleh dua komponen utama dengan versi independen. Untuk memastikan kartu aplikasi Anda berfungsi dengan benar di semua perangkat, penting untuk memahami arsitektur yang mendasarinya.

  • Library terkait kartu Jetpack: Library ini (termasuk Kartu Wear dan ProtoLayout Wear) disematkan dalam aplikasi Anda, dan Anda, sebagai developer, mengontrol versinya. Aplikasi Anda menggunakan library ini untuk membuat objek TileBuilder.Tile (struktur data yang mewakili Kartu Anda) sebagai respons terhadap panggilan onTileRequest() sistem.
  • ProtoLayout Renderer: Komponen sistem ini bertanggung jawab untuk merender objek Tile di layar dan menangani interaksi pengguna. Versi renderer tidak dikontrol oleh developer aplikasi dan dapat bervariasi di perangkat, bahkan perangkat dengan hardware yang identik.

Tampilan atau perilaku Kartu dapat bervariasi berdasarkan versi library Jetpack Tiles aplikasi Anda dan versi ProtoLayout Renderer di perangkat pengguna. Misalnya, satu perangkat mungkin mendukung rotasi atau tampilan data detak jantung, dan perangkat lainnya mungkin tidak.

Dokumen ini menjelaskan cara memastikan aplikasi Anda kompatibel dengan berbagai versi library Kartu dan Renderer ProtoLayout, serta cara bermigrasi ke versi library Jetpack yang lebih tinggi.

Pertimbangkan kompatibilitas

Untuk membuat Kartu yang berfungsi dengan benar di berbagai perangkat, Anda harus mempertimbangkan hal berikut.

Mendeteksi versi perender

  • Gunakan metode getRendererSchemaVersion() dari objek DeviceParameters yang diteruskan ke metode onTileRequest(). Metode ini menampilkan nomor versi utama dan minor Renderer ProtoLayout di perangkat.
  • Kemudian, Anda dapat menggunakan logika kondisional dalam penerapan onTileRequest() untuk menyesuaikan desain atau perilaku Kartu berdasarkan versi perender yang terdeteksi.
    • Misalnya, jika animasi tertentu tidak didukung, Anda dapat menampilkan gambar statis.

Anotasi @RequiresSchemaVersion

  • Anotasi @RequiresSchemaVersion pada metode ProtoLayout menunjukkan versi skema perender minimum yang diperlukan agar metode tersebut berperilaku seperti yang didokumentasikan (contoh).
    • Meskipun memanggil metode yang memerlukan versi perender yang lebih tinggi daripada yang tersedia di perangkat tidak akan menyebabkan aplikasi Anda error, hal ini dapat menyebabkan konten tidak ditampilkan atau fitur diabaikan.

Contoh

override fun onTileRequest(
    requestParams: TileService.TileRequest
): ListenableFuture<Tile> {
    val rendererVersion =
        requestParams.deviceConfiguration.rendererSchemaVersion
    val tile = Tile.Builder()

    if (
        rendererVersion.major > 1 ||
            (rendererVersion.major == 1 && rendererVersion.minor >= 300)
    ) {
        // Use a feature supported in renderer version 1.300 or later
        tile.setTileTimeline(/* ... */ )
    } else {
        // Provide fallback content for older renderers
        tile.setTileTimeline(/* ... */ )
    }

    return Futures.immediateFuture(tile.build())
}

Menguji dengan versi perender yang berbeda

Untuk menguji kartu Anda terhadap versi perender yang berbeda, deploy ke versi emulator Wear OS yang berbeda. (Di perangkat fisik, update ProtoLayout Renderer dikirimkan oleh Play Store atau update sistem. Anda tidak dapat memaksa penginstalan versi perender tertentu.)

Fitur Pratinjau Kartu Android Studio menggunakan perender yang disematkan dalam library Jetpack ProtoLayout yang menjadi dependensi kode Anda, sehingga pendekatan lainnya adalah bergantung pada versi library Jetpack yang berbeda saat menguji kartu.

Mengupgrade library Jetpack

Update library Jetpack Tile untuk memanfaatkan peningkatan terbaru, termasuk perubahan UI agar Kartu Anda terintegrasi dengan lancar dengan sistem.

Bermigrasi ke Tiles 1.2 / ProtoLayout 1.0

Mulai versi 1.2, sebagian besar API tata letak Kartu berada di namespace androidx.wear.protolayout. Untuk menggunakan API terbaru, selesaikan langkah-langkah migrasi berikut dalam kode Anda.

Memperbarui dependensi

Dalam file build modul aplikasi Anda, buat perubahan berikut:

Groovy

  // Remove
  implementation 'androidx.wear.tiles:tiles-material:version'

  // Include additional dependencies
  implementation "androidx.wear.protolayout:protolayout:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-material:1.2.1"
  implementation "androidx.wear.protolayout:protolayout-expression:1.2.1"

  // Update
  implementation "androidx.wear.tiles:tiles:1.4.1"

Kotlin

  // Remove
  implementation("androidx.wear.tiles:tiles-material:version")

  // Include additional dependencies
  implementation("androidx.wear.protolayout:protolayout:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-material:1.2.1")
  implementation("androidx.wear.protolayout:protolayout-expression:1.2.1")

  // Update
  implementation("androidx.wear.tiles:tiles:1.4.1")

Memperbarui namespace

Di file kode berbasis Kotlin dan Java aplikasi Anda, lakukan pembaruan berikut. Bisa juga dengan mengeksekusi skrip penggantian nama namespace ini.

  1. Ganti semua impor androidx.wear.tiles.material.* dengan androidx.wear.protolayout.material.*. Selesaikan juga langkah ini untuk library androidx.wear.tiles.material.layouts.

  2. Ganti sebagian besar impor androidx.wear.tiles.* lainnya dengan androidx.wear.protolayout.*.

    Impor untuk androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders, dan androidx.wear.tiles.TileService harus tetap sama.

  3. Ganti nama beberapa metode yang tidak digunakan lagi dari class TileService dan TileBuilder:

    1. TileBuilders: getTimeline() ke getTileTimeline(), dan setTimeline() ke setTileTimeline()
    2. TileService: onResourcesRequest() ke onTileResourcesRequest()
    3. RequestBuilders.TileRequest: getDeviceParameters() ke getDeviceConfiguration(), setDeviceParameters() ke setDeviceConfiguration(), getState() ke getCurrentState(), dan setState() ke setCurrentState()