ซิงค์รายการข้อมูลกับ Data Layer API

DataItem กำหนดอินเทอร์เฟซที่ระบบใช้เพื่อซิงค์ข้อมูลระหว่างอุปกรณ์พกพาและ อุปกรณ์ที่สวมใส่ได้ โดยทั่วไปแล้ว DataItem จะประกอบด้วยคอมโพเนนต์ต่อไปนี้

• เพย์โหลด: อาร์เรย์ไบต์ที่คุณตั้งค่าด้วยข้อมูลได้ ซึ่งช่วยให้คุณทำการซีเรียลไลซ์และ ดีซีเรียลไลซ์ออบเจ็กต์ได้ด้วยตนเอง ขนาดของเพย์โหลดจำกัดไว้ที่ 100 KB
• เส้นทาง: สตริงที่ไม่ซ้ำกันซึ่งต้องขึ้นต้นด้วยเครื่องหมายทับ เช่น "/path/to/data"

หมายเหตุ: Data Layer API สามารถส่งข้อความและซิงค์ข้อมูลกับโทรศัพท์ Android หรือนาฬิกา Wear OS เท่านั้น หากอุปกรณ์ Wear OS จับคู่กับอุปกรณ์ iOS อยู่ Data Layer API จะไม่ทำงาน

ด้วยเหตุนี้ โปรดอย่าใช้ Data Layer API เป็นวิธีหลักในการสื่อสารกับเครือข่าย แต่ให้ทำตาม รูปแบบเดียวกับแอปบนอุปกรณ์เคลื่อนที่ โดยมีข้อแตกต่างเล็กน้อย

โดยปกติแล้วคุณจะไม่ใช้ DataItem โดยตรง แต่ให้ทำดังนี้แทน

1. สร้างออบเจ็กต์ PutDataRequest โดยระบุเส้นทางสตริงเพื่อระบุรายการอย่างไม่ซ้ำกัน
2. เรียกใช้ setData() เพื่อตั้งค่าเพย์โหลด
3. หากการซิงค์ที่ล่าช้าจะส่งผลเสียต่อประสบการณ์ของผู้ใช้ ให้โทรหา setUrgent()
4. ใช้เมธอด putDataItem ของคลาส DataClient เพื่อขอให้ระบบสร้างรายการข้อมูล

เมื่อขอรายการข้อมูล ระบบจะแสดงออบเจ็กต์ที่ใช้ DataItem อย่างถูกต้อง อย่างไรก็ตาม แทนที่จะทำงานกับไบต์ดิบโดยใช้ setData() เราขอแนะนำให้คุณใช้แผนที่ข้อมูล ซึ่งแสดงรายการข้อมูลด้วยอินเทอร์เฟซที่คล้ายกับ Bundle

ดูข้อมูลเพิ่มเติมได้ที่แอป ตัวอย่าง DataLayer

ซิงค์ข้อมูลกับแผนที่ข้อมูล

หากเป็นไปได้ ให้ใช้คลาส DataMap แนวทางนี้ช่วยให้คุณทำงานกับรายการข้อมูลในรูปแบบของ Bundle ใน Android ระบบจึงทำการซีเรียลไลซ์และดีซีเรียลไลซ์ออบเจ็กต์ให้คุณ และคุณสามารถจัดการข้อมูล ด้วยคู่คีย์-ค่า

วิธีใช้แผนที่ข้อมูล

1. สร้างออบเจ็กต์ PutDataMapRequest โดยตั้งค่าเส้นทางของรายการข้อมูล

   หมายเหตุ: สตริงเส้นทางคือตัวระบุที่ไม่ซ้ำกันสำหรับรายการข้อมูล ที่ช่วยให้คุณเข้าถึงได้จากทั้ง 2 ด้านของการเชื่อมต่อ เส้นทาง ต้องขึ้นต้นด้วยเครื่องหมายทับ หากคุณใช้ข้อมูลแบบลำดับชั้นในแอป ให้สร้างรูปแบบเส้นทางที่ตรงกับโครงสร้างของข้อมูล

2. เรียกใช้ PutDataMapRequest.getDataMap() เพื่อรับแผนที่ข้อมูลที่คุณ ตั้งค่าได้
3. ตั้งค่าสำหรับแผนที่ข้อมูลโดยใช้วิธีการ put...() เช่น putString()
4. หากการซิงค์ที่ล่าช้าจะส่งผลเสียต่อประสบการณ์ของผู้ใช้ ให้โทรหา setUrgent()
5. เรียกใช้ PutDataMapRequest.asPutDataRequest() เพื่อรับออบเจ็กต์ PutDataRequest
6. ใช้เมธอด putDataItem ของคลาส DataClient เพื่อขอให้ระบบสร้างรายการข้อมูล

   หมายเหตุ: หากโทรศัพท์มือถือและอุปกรณ์ที่สวมใส่ได้ไม่ได้เชื่อมต่อกัน ระบบจะบัฟเฟอร์ข้อมูลและซิงค์เมื่อเชื่อมต่ออีกครั้ง

เมธอด increaseCounter() ในตัวอย่างต่อไปนี้แสดงวิธีสร้าง แผนที่ข้อมูลและใส่ข้อมูลลงในแผนที่

Kotlin

private const val COUNT_KEY = "com.example.key.count"

class MainActivity : Activity() {

    private lateinit var dataClient: DataClient
    private var count = 0
    ...
    // Create a data map and put data in it
    private fun increaseCounter() {
        val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
            dataMap.putInt(COUNT_KEY, count++)
            asPutDataRequest()
        }
        val putDataTask: Task<DataItem> = dataClient.putDataItem(putDataReq)
    }
    ...
}

Java

public class MainActivity extends Activity {
    private static final String COUNT_KEY = "com.example.key.count";
    private DataClient dataClient;
    private int count = 0;
    ...
    // Create a data map and put data in it
    private void increaseCounter() {
        PutDataMapRequest putDataMapReq = PutDataMapRequest.create("/count");
        putDataMapReq.getDataMap().putInt(COUNT_KEY, count++);
        PutDataRequest putDataReq = putDataMapReq.asPutDataRequest();
        Task<DataItem> putDataTask = dataClient.putDataItem(putDataReq);
    }
  ...
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดการ Tasks ได้ที่ เอกสารอ้างอิง

ข้อควรระวัง: ก่อนใช้ Wearable Data Layer API ให้ตรวจสอบว่า API นี้พร้อมใช้งานใน อุปกรณ์หรือไม่ มิฉะนั้นจะเกิดข้อยกเว้น ใช้คลาส GoogleApiAvailability ตามที่ใช้ใน Horologist

ตั้งค่าลำดับความสำคัญของ DataItem

DataClient API อนุญาตให้ส่งคำขอเร่งด่วนสำหรับการซิงค์ออบเจ็กต์ DataItem โดยปกติแล้ว ระบบจะหน่วงเวลาการส่งรายการข้อมูล ไปยังเครือข่าย Wear OS เพื่อยืดอายุการใช้งานแบตเตอรี่ของอุปกรณ์ผู้ใช้ แต่ หากการหน่วงเวลาในการซิงค์รายการข้อมูลส่งผลเสียต่อประสบการณ์ของผู้ใช้ คุณสามารถทำเครื่องหมาย รายการข้อมูลเหล่านั้นเป็นด่วนได้ เช่น ในแอปรีโมตคอนโทรลที่ผู้ใช้คาดหวังว่าระบบจะแสดงผลการดำเนินการในทันที คุณสามารถให้ระบบซิงค์รายการข้อมูลในทันทีได้โดยการเรียกใช้ setUrgent()

หากคุณไม่เรียกใช้ setUrgent() ระบบอาจหน่วงเวลาสูงสุด 30 นาทีก่อนที่จะซิงค์รายการข้อมูลที่ไม่เร่งด่วน แม้ว่าโดยปกติแล้วคุณจะคาดหวังได้ว่าการหน่วงเวลาจะเกิดขึ้นเพียงไม่กี่นาที ความเร่งด่วนเริ่มต้นคือไม่เร่งด่วน ดังนั้นคุณต้องใช้ setUrgent() หากต้องการคงลักษณะการทำงานของการซิงค์ทันทีจาก Wear OS API เวอร์ชันก่อนหน้า

รอรับเหตุการณ์ของรายการข้อมูล

หากการเชื่อมต่อชั้นข้อมูลด้านหนึ่งเปลี่ยนแปลงรายการข้อมูล ให้แจ้ง ผู้ใช้เกี่ยวกับการเปลี่ยนแปลงที่เกิดขึ้นในการเชื่อมต่ออีกด้าน ซึ่งทำได้โดยการติดตั้งใช้งาน Listener สำหรับเหตุการณ์ของรายการข้อมูล

ข้อมูลโค้ดในตัวอย่างต่อไปนี้จะแจ้งให้แอปทราบเมื่อค่าของ เคาน์เตอร์ที่กำหนดไว้ในตัวอย่างก่อนหน้ามีการเปลี่ยนแปลง

Kotlin

private const val COUNT_KEY = "com.example.key.count"

class MainActivity : Activity(), DataClient.OnDataChangedListener {

    private var count = 0

    override fun onResume() {
        super.onResume()
        Wearable.getDataClient(this).addListener(this)
    }

    override fun onPause() {
        super.onPause()
        Wearable.getDataClient(this).removeListener(this)
    }

    override fun onDataChanged(dataEvents: DataEventBuffer) {
        dataEvents.forEach { event ->
            // DataItem changed
            if (event.type == DataEvent.TYPE_CHANGED) {
                event.dataItem.also { item ->
                    if (item.uri.path.compareTo("/count") == 0) {
                        DataMapItem.fromDataItem(item).dataMap.apply {
                            updateCount(getInt(COUNT_KEY))
                        }
                    }
                }
            } else if (event.type == DataEvent.TYPE_DELETED) {
                // DataItem deleted
            }
        }
    }

    // Method to update the count
    private fun updateCount(int: Int) { ... }
    ...
}

Java

public class MainActivity extends Activity implements DataClient.OnDataChangedListener {
    private static final String COUNT_KEY = "com.example.key.count";
    private int count = 0;

    @Override
    protected void onResume() {
        super.onResume();
        Wearable.getDataClient(this).addListener(this);
    }

    @Override
    protected void onPause() {
        super.onPause();
        Wearable.getDataClient(this).removeListener(this);
    }

    @Override
    public void onDataChanged(DataEventBuffer dataEvents) {
        for (DataEvent event : dataEvents) {
            if (event.getType() == DataEvent.TYPE_CHANGED) {
                // DataItem changed
                DataItem item = event.getDataItem();
                if (item.getUri().getPath().compareTo("/count") == 0) {
                    DataMap dataMap = DataMapItem.fromDataItem(item).getDataMap();
                    updateCount(dataMap.getInt(COUNT_KEY));
                }
            } else if (event.getType() == DataEvent.TYPE_DELETED) {
                // DataItem deleted
            }
        }
    }

    // Method to update the count
    private void updateCount(int c) { ... }
    ...
}

กิจกรรมนี้ใช้ DataClient.OnDataChangedListener อินเทอร์เฟซ กิจกรรมจะเพิ่มตัวเอง เป็น Listener สำหรับเหตุการณ์ Data Item ภายใน เมธอด onResume() และนำ Listener ออกใน เมธอด onPause() หากต้องการดูการติดตั้งใช้งานโดยใช้รูปภาพ โมเดล และ บริการ โปรดดูแอปตัวอย่าง DataLayer

นอกจากนี้ คุณยังติดตั้งใช้งาน Listener เป็นบริการได้ด้วย ดูข้อมูลเพิ่มเติมได้ที่ฟังเหตุการณ์ Data Layer