DataItem
定義的介面可供系統用來同步處理手持裝置和穿戴式裝置間的資料。DataItem
通常包含下列元件:
- 酬載:可用資料設定的位元組陣列,用來執行專屬的物件序列化和去序列化作業。酬載大小上限為 100 KB。
-
路徑:必須以正斜線開頭的專用字串,例如
"/path/to/data"
。
注意:Data Layer API 只能傳送訊息並與 Android 手機或 Wear OS 手錶同步處理資料。如果 Wear OS 裝置與 iOS 裝置配對,Data Layer API 將無法運作。
因此,請不要使用 Data Layer API 做為與網路通訊的主要方式,而是改用與行動應用程式的模式相同,但有些微差異的方式。
開發人員通常不會直接實作 DataItem
,而是會:
-
建立
PutDataRequest
物件,指定可以專門識別該項目的字串路徑。 -
呼叫
setData()
來設定酬載。 -
如果同步處理的延遲情況會對使用者體驗造成負面影響,請呼叫
setUrgent()
。 -
使用
DataClient
類別的putDataItem
方法要求系統建立資料項目。
系統要求資料項目時,會傳回能夠正確實作 DataItem
介面的物件。不過比起使用 setData()
處理原始位元組,我們建議使用資料對應,以類似 Bundle
的介面顯示資料項目。
詳情請參閱 DataLayer 範例應用程式。
使用資料對應同步處理資料
請盡可能使用 DataMap
類別。這麼做就能以 Android Bundle
的形式處理資料項目,讓系統為您進行物件序列化和去序列化,您也可以透過鍵/值組合操控資料。
如何使用資料對應:
-
建立
PutDataMapRequest
物件,設定資料項目的路徑。注意:路徑字串是資料項目的唯一識別碼,可用來從連線的任一端進行存取。路徑必須以正斜線開頭。如果應用程式內使用了階層式資料,請建立符合資料結構的路徑配置。
-
呼叫
PutDataMapRequest.getDataMap()
,取得可供設定值的資料對應。 -
使用
put...()
方法設定資料對應的值,例如putString()
。 -
如果同步處理出現延遲會影響使用者體驗,請呼叫
setUrgent()
。 -
呼叫
PutDataMapRequest.asPutDataRequest()
,取得PutDataRequest
物件。 -
使用
DataClient
類別的putDataItem
方法要求系統建立資料項目。注意:如果手機和穿戴式裝置連線中斷,系統會在連線恢復後緩衝並同步處理資料。
以下範例中的 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); } ... }
設定 DataItem 的優先順序
DataClient
API 可用於緊急要求同步處理 DataItem
物件。一般而言,系統會延遲資料項目提交到 Wear OS 網路的時間,藉此提升使用者裝置的電池續航力,但如果延遲同步處理資料項目會對使用者體驗造成負面影響,您可以標示為緊急項目。舉例來說,如果某個遙控應用程式的使用者期望操作立即見效,您可以呼叫 setUrgent()
,讓系統立即同步處理資料項目。
如果未呼叫 setUrgent()
,系統最長可能會延遲 30 分鐘才同步處理非緊急的資料項目,不過通常都只會延遲幾分鐘。系統預設值為非緊急狀況,因此如果需要保留舊版 Wear OS API 的立即同步處理行為,必須使用 setUrgent()
。
監聽資料項目事件
如果資料層連線有一端變更了資料項目,請通知使用者連線另一端所有的任何變動。只要實作資料項目事件的事件監聽器即可達到此效果。
以下範例程式碼片段會在上述範例定義的計數值有變動時,向應用程式發出通知:
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
介面。活動會將本身加入 onResume()
方法做為資料項目事件的事件監聽器,並移除 onPause()
方法內的事件監聽器。想使用圖片、檢視模型及
請參閱 DataLayer 範例
應用程式。
您也可以把事件監聽器實作為服務。詳情請參閱「監聽資料層事件」。