مزامنة عناصر البيانات مع Data Layer API

تحدّد السمة DataItem الواجهة التي يستخدمها النظام لمزامنة البيانات بين الأجهزة المحمولة والأجهزة القابلة للارتداء. تتكوّن السمة DataItem بشكل عام من المكوّنات التالية:

• حمولة البيانات: مصفوفة بايت يمكنك ضبطها باستخدام البيانات، ما يتيح لك تنفيذ تسلسل العناصر وإلغاء التسلسل. ويجب ألّا يتجاوز حجم الحمولة 100 كيلوبايت.
• المسار: سلسلة فريدة يجب أن تبدأ بشرطة مائلة للأمام، مثل "/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. استدعِ 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، يمكنك الاطّلاع على المستندات المرجعية.

ضبط أولوية عنصر البيانات

تسمح واجهة برمجة تطبيقات DataClient بإرسال طلبات عاجلة لمزامنة عناصر DataItem. عادةً ما يؤخّر النظام تسليم عناصر البيانات إلى شبكة Wear OS لتحسين عمر البطارية على أجهزة المستخدمين، ولكن إذا كان التأخير في مزامنة عناصر البيانات يؤثر سلبًا في تجربة المستخدم، يمكنك وضع علامة عليها باعتبارها عاجلة. على سبيل المثال، في تطبيق للتحكّم عن بُعد حيث يتوقع المستخدم ظهور إجراءاته فورًا، يمكنك أن تطلب من النظام مزامنة عناصر البيانات على الفور عن طريق استدعاء setUrgent().

إذا لم يتم الاتصال بـ setUrgent()، قد يتأخر النظام لمدة تصل إلى 30 دقيقة قبل مزامنة عناصر البيانات غير العاجلة، على الرغم من أنه من المحتمل عادةً أن يصل التأخير إلى بضع دقائق فقط. إنّ القيمة التلقائية للإلحاح ليست عاجلة، لذا عليك استخدام setUrgent() إذا كنت بحاجة إلى الاحتفاظ بسلوك المزامنة الفورية من الإصدارات السابقة من Wear OS API.

الاستماع إلى أحداث عناصر البيانات

إذا غيَّر أحد جانبي اتصال طبقة البيانات عنصرًا من عناصر البيانات، أبلِغ المستخدم بأي تغييرات على الجانب الآخر من الاتصال. ويمكنك إجراء ذلك من خلال تنفيذ أداة معالجة لأحداث عناصر البيانات.

يُعلم مقتطف الرمز في المثال التالي التطبيق عندما تتغير قيمة العدّاد المحدد في المثال السابق:

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.

يمكنك أيضًا تنفيذ المستمع كخدمة. ولمزيد من المعلومات، يُرجى الاطّلاع على الاستماع إلى أحداث طبقة البيانات.