การกำหนดเวอร์ชันของการ์ด

ในอุปกรณ์ Wear OS ไทล์จะแสดงผลโดยคอมโพเนนต์หลัก 2 รายการที่มีเวอร์ชันแยกกัน คุณต้องเข้าใจสถาปัตยกรรมพื้นฐานนี้เพื่อให้การ์ดแอปทำงานได้อย่างถูกต้องในอุปกรณ์ทุกเครื่อง

  • ไลบรารีที่เกี่ยวข้องกับการ์ดของ Jetpack: ไลบรารีเหล่านี้ (รวมถึงการ์ด Wear และ Wear ProtoLayout) จะฝังอยู่ในแอปของคุณ และในฐานะนักพัฒนาแอป คุณจะควบคุมเวอร์ชันของไลบรารีได้ แอปของคุณใช้ไลบรารีเหล่านี้เพื่อสร้างออบเจ็กต์ TileBuilder.Tile (โครงสร้างข้อมูลที่แสดงการ์ด) เพื่อตอบสนองต่อการเรียกใช้ onTileRequest() ของระบบ
  • โปรแกรมแสดงผล ProtoLayout: คอมโพเนนต์ของระบบนี้มีหน้าที่แสดงผลออบเจ็กต์ Tile บนจอแสดงผลและจัดการการโต้ตอบของผู้ใช้ นักพัฒนาแอปไม่สามารถควบคุมเวอร์ชันของโปรแกรมแสดงผลได้ และเวอร์ชันดังกล่าวอาจแตกต่างกันไปตามอุปกรณ์ต่างๆ แม้ว่าอุปกรณ์เหล่านั้นจะใช้ฮาร์ดแวร์เดียวกันก็ตาม

ลักษณะที่ปรากฏหรือลักษณะการทํางานของการ์ดอาจแตกต่างกันไปตามทั้งเวอร์ชันไลบรารี Jetpack Tiles ของแอปและเวอร์ชันโปรแกรมแสดงผล ProtoLayout ในอุปกรณ์ของผู้ใช้ เช่น อุปกรณ์หนึ่งอาจรองรับการหมุนหรือการแสดงข้อมูลอัตราการเต้นของหัวใจ แต่อุปกรณ์อีกเครื่องหนึ่งอาจไม่รองรับ

เอกสารนี้จะอธิบายวิธีตรวจสอบว่าแอปของคุณเข้ากันได้กับไลบรารี Tiles และโปรแกรมแสดงผล ProtoLayout เวอร์ชันต่างๆ รวมถึงวิธีย้ายข้อมูลไปยังไลบรารี Jetpack เวอร์ชันที่ใหม่กว่า

พิจารณาความเข้ากันได้

หากต้องการสร้างการ์ดที่ทํางานได้อย่างถูกต้องในอุปกรณ์ต่างๆ คุณควรพิจารณาสิ่งต่อไปนี้

ตรวจหาเวอร์ชันโปรแกรมแสดงผล

  • ใช้เมธอด getRendererSchemaVersion() ของออบเจ็กต์ DeviceParameters ที่ส่งไปยังเมธอด onTileRequest() เมธอดนี้จะแสดงหมายเลขเวอร์ชันหลักและรองของ ProtoLayout Renderer ในอุปกรณ์
  • จากนั้นคุณก็ใช้ตรรกะแบบมีเงื่อนไขในonTileRequest()การติดตั้งใช้งานเพื่อปรับการออกแบบหรือลักษณะการทํางานของการ์ดตามเวอร์ชันโปรแกรมแสดงผลที่ตรวจพบได้
    • เช่น หากระบบไม่รองรับภาพเคลื่อนไหวบางรายการ คุณอาจแสดงภาพนิ่งแทนได้

คำอธิบายประกอบ @RequiresSchemaVersion

  • คําอธิบายประกอบ @RequiresSchemaVersion ในเมธอด ProtoLayout จะระบุเวอร์ชันสคีมาของโปรแกรมแสดงผลขั้นต่ำที่จําเป็นสําหรับให้เมธอดทํางานตามที่อธิบายไว้ (ตัวอย่าง)
    • แม้ว่าการเรียกใช้เมธอดที่ต้องใช้โปรแกรมแสดงผลเวอร์ชันสูงกว่าที่พร้อมใช้งานในอุปกรณ์จะไม่ทำให้แอปขัดข้อง แต่อาจส่งผลให้เนื้อหาไม่แสดงหรือระบบละเว้นฟีเจอร์

ตัวอย่าง

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

ทดสอบกับโปรแกรมแสดงผลเวอร์ชันต่างๆ

หากต้องการทดสอบการ์ดกับโปรแกรมแสดงผลเวอร์ชันต่างๆ ให้ติดตั้งใช้งานการ์ดในโปรแกรมจำลอง Wear OS เวอร์ชันต่างๆ (ในอุปกรณ์จริง การอัปเดตโปรแกรมแสดงผล ProtoLayout จะมาจาก Play Store หรือการอัปเดตระบบ คุณไม่สามารถบังคับให้ติดตั้งโปรแกรมแสดงผลเวอร์ชันใดเวอร์ชันหนึ่งได้)

ฟีเจอร์แสดงตัวอย่างการ์ดของ Android Studio ใช้โปรแกรมแสดงผลที่ฝังอยู่ในไลบรารี Jetpack ProtoLayout ที่โค้ดของคุณใช้อยู่ อีกวิธีหนึ่งคือใช้ไลบรารี Jetpack เวอร์ชันอื่นเมื่อทดสอบการ์ด

อัปเกรดไลบรารี Jetpack

อัปเดตไลบรารี Tile ของ Jetpack เพื่อใช้ประโยชน์จากการปรับปรุงล่าสุด ซึ่งรวมถึงการเปลี่ยนแปลง UI เพื่อให้ Tile ผสานรวมกับระบบได้อย่างราบรื่น

ย้ายข้อมูลไปยังการ์ด 1.2 / ProtoLayout 1.0

ตั้งแต่เวอร์ชัน 1.2 เป็นต้นไป Tiles Layout API ส่วนใหญ่จะอยู่ในเนมสเปซ androidx.wear.protolayout หากต้องการใช้ API เวอร์ชันล่าสุด ให้ทําตามขั้นตอนการย้ายข้อมูลต่อไปนี้ในโค้ด

อัปเดตทรัพยากร Dependency

ในไฟล์บิลด์ของโมดูลแอป ให้ทำการเปลี่ยนแปลงต่อไปนี้

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

อัปเดตเนมสเปซ

ทำการอัปเดตต่อไปนี้ในไฟล์โค้ด Kotlin และ Java ของแอป หรือจะเรียกใช้สคริปต์การเปลี่ยนชื่อเนมสเปซนี้ก็ได้

  1. แทนที่การนําเข้า androidx.wear.tiles.material.* ทั้งหมดด้วย androidx.wear.protolayout.material.* ทำขั้นตอนนี้ให้เสร็จสมบูรณ์สำหรับคลัง androidx.wear.tiles.material.layouts ด้วย

  2. แทนที่การนําเข้า androidx.wear.tiles.* อื่นๆ ส่วนใหญ่ด้วย androidx.wear.protolayout.*

    การนําเข้าสําหรับ androidx.wear.tiles.EventBuilders, androidx.wear.tiles.RequestBuilders, androidx.wear.tiles.TileBuilders และ androidx.wear.tiles.TileService ควรเหมือนเดิม

  3. เปลี่ยนชื่อเมธอดที่เลิกใช้งาน 2-3 เมธอดจากคลาส TileService และ TileBuilder

    1. TileBuilders: getTimeline() ถึง getTileTimeline() และ setTimeline() ถึง setTileTimeline()
    2. TileService: จาก onResourcesRequest() เป็น onTileResourcesRequest()
    3. RequestBuilders.TileRequest: getDeviceParameters() ถึง getDeviceConfiguration(), setDeviceParameters() ถึง setDeviceConfiguration(), getState() ถึง getCurrentState() และ setState() ถึง setCurrentState()