داده ها را در معرض عوارض قرار دهید

منابع داده‌ی پیچیدگی، اطلاعات را در اختیار پیچیدگی‌های صفحه ساعت قرار می‌دهند و متن، تصاویر و اعدادی را که صفحه ساعت می‌تواند نمایش دهد، ارائه می‌دهند.

یک سرویس منبع داده، SuspendingComplicationDataSourceService را بسط می‌دهد تا اطلاعات مفید را مستقیماً به صفحه ساعت ارائه دهد.

شروع به کار

وابستگی زیر را به ماژول برنامه خود اضافه کنید:

dependencies {
  implementiation("androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1")
}

ایجاد سرویس منبع داده

وقتی به داده‌های پیچیدگی نیاز باشد، سیستم Wear OS درخواست‌های به‌روزرسانی را به منبع داده شما ارسال می‌کند. برای پاسخ به درخواست‌های به‌روزرسانی، منبع داده شما باید متد onComplicationRequest() را از کلاس SuspendingComplicationDataSourceService پیاده‌سازی کند.

سیستم Wear OS زمانی که به داده‌های منبع شما نیاز دارد، onComplicationRequest() را فراخوانی می‌کند - برای مثال، زمانی که یک تابع با استفاده از منبع داده شما فعال می‌شود یا زمانی که مدت زمان مشخصی می‌گذرد.

نکته: وقتی منبع داده شما داده‌ها را ارائه می‌دهد، صفحه ساعت مقادیر خام را دریافت می‌کند. صفحه ساعت مسئول قالب‌بندی داده‌ها برای نمایش است.

قطعه کد زیر یک نمونه پیاده‌سازی را نشان می‌دهد: 

class MyComplicationDataSourceService : SuspendingComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationData? {
        // Retrieve the latest info for inclusion in the data.
        val text = getLatestData()
        return shortTextComplicationData(text)
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, and title.
            .build()

    // ...
}

اعلان‌ها و مجوزهای آشکار

منابع داده باید شامل اعلان‌های خاصی در مانیفست برنامه خود باشند تا توسط سیستم اندروید به عنوان منبع داده در نظر گرفته شوند. این بخش تنظیمات مورد نیاز برای منابع داده را توضیح می‌دهد.

در مانیفست برنامه خود، سرویس را تعریف کنید و یک فیلتر درخواست به‌روزرسانی برای اکشن اینتنت اضافه کنید. مانیفست همچنین باید با اضافه کردن مجوز BIND_COMPLICATION_PROVIDER از سرویس محافظت کند تا اطمینان حاصل شود که فقط سیستم Wear OS می‌تواند به سرویس‌های ارائه‌دهنده متصل شود.

همچنین، یک ویژگی android:icon در عنصر service قرار دهید که یک آیکون سفید تک رنگ ارائه می‌دهد. ما برای آیکون‌ها، vector drawables را توصیه می‌کنیم. آیکون، منبع داده را نشان می‌دهد و در Completion Picker نمایش داده می‌شود.

در اینجا یک مثال آورده شده است:

<service
    android:name=".snippets.complication.MyComplicationDataSourceService"
    android:exported="true"
    android:label="@string/my_complication_service_label"
    android:icon="@drawable/complication_icon"
    android:permission="com.google.android.wearable.permission.BIND_COMPLICATION_PROVIDER">
    <intent-filter>
        <action android:name="android.support.wearable.complications.ACTION_COMPLICATION_UPDATE_REQUEST" />
    </intent-filter>

    <!-- Supported types should be comma-separated, for example: "SHORT_TEXT,SMALL_IMAGE" -->
    <meta-data
        android:name="android.support.wearable.complications.SUPPORTED_TYPES"
        android:value="SHORT_TEXT" />
    <meta-data
        android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS"
        android:value="300" />

    <!-- Optionally, specify a configuration activity, where the user can configure your complication. -->
    <meta-data
        android:name="android.support.wearable.complications.PROVIDER_CONFIG_ACTION"
        android:value="MY_CONFIG_ACTION" />

</service>

عناصر فراداده

در فایل مانیفست خود، به عناصر فراداده زیر توجه کنید:

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES" : انواع داده‌های عارضه‌ای را که منبع داده پشتیبانی می‌کند، مشخص می‌کند.
  • android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS" : مشخص می‌کند که سیستم هر چند وقت یکبار باید به‌روزرسانی‌های داده‌ها را بررسی کند.

وقتی منبع داده‌ی پیچیدگی شما فعال است، UPDATE_PERIOD_SECONDS مشخص می‌کند که سیستم چند وقت یکبار می‌خواهد به‌روزرسانی‌های داده‌ها را بررسی کند. اگر اطلاعات نشان داده شده در پیچیدگی نیازی به به‌روزرسانی منظم در یک برنامه‌ی زمانی ندارد، مانند زمانی که از به‌روزرسانی‌های push استفاده می‌کنید ، این مقدار را روی 0 تنظیم کنید.

اگر UPDATE_PERIOD_SECONDS روی 0 تنظیم نکنید، باید از مقداری حداقل 300 (۵ دقیقه) استفاده کنید که حداقل دوره به‌روزرسانی است که سیستم اعمال می‌کند تا عمر باتری دستگاه حفظ شود. علاوه بر این، به خاطر داشته باشید که وقتی دستگاه در حالت محیطی است یا استفاده نمی‌شود، درخواست‌های به‌روزرسانی کمتر ارسال می‌شوند.

افزودن فعالیت پیکربندی

در صورت نیاز، یک منبع داده می‌تواند شامل یک فعالیت پیکربندی باشد که هنگام انتخاب منبع داده خاص از انتخابگر عارضه، به کاربر نشان داده می‌شود. به عنوان مثال، یک منبع داده ساعت جهانی ممکن است یک فعالیت پیکربندی داشته باشد که به کاربر اجازه می‌دهد شهر یا منطقه زمانی را برای نمایش انتخاب کند.

مانیفست نمونه شامل یک عنصر meta-data با کلید PROVIDER_CONFIG_ACTION است. مقدار این عنصر، عملی است که برای راه‌اندازی فعالیت پیکربندی استفاده می‌شود.

فعالیت پیکربندی را ایجاد کنید و یک فیلتر intent که با اکشن مربوط به آن در فایل مانیفست شما مطابقت دارد، اضافه کنید.

<intent-filter>
    <action android:name="MY_CONFIG_ACTION" />
    <category android:name="android.support.wearable.complications.category.PROVIDER_CONFIG" />
    <category android:name="android.intent.category.DEFAULT" />
</intent-filter>

اکتیویتی می‌تواند جزئیات اسلات پیچیدگی که در حال پیکربندی آن است را از intent درون متد onCreate() اکتیویتی دریافت کند: 

// Keys defined on ComplicationDataSourceService
val id = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_ID, -1)
val type = intent.getIntExtra(EXTRA_CONFIG_COMPLICATION_TYPE, -1)
val source = intent.getStringExtra(EXTRA_CONFIG_DATA_SOURCE_COMPONENT)

فعالیت پیکربندی باید در همان بسته‌ای باشد که ارائه‌دهنده قرار دارد. فعالیت پیکربندی باید RESULT_OK یا RESULT_CANCELED برگرداند تا به سیستم بگوید که آیا منبع داده باید تنظیم شود یا خیر: 

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()

از به‌روزرسانی‌های فوری استفاده کنید

به عنوان جایگزینی برای مشخص کردن فاصله زمانی به‌روزرسانی در مانیفست برنامه، می‌توانید از نمونه‌ای از ComplicationDataSourceUpdateRequester برای شروع به‌روزرسانی‌ها به صورت پویا استفاده کنید. برای درخواست به‌روزرسانی، requestUpdate() را فراخوانی کنید.

احتیاط: برای حفظ عمر باتری دستگاه، تابع requestUpdate() از نمونه‌ی ComplicationDataSourceUpdateRequester خود، به طور متوسط، بیش از هر 5 دقیقه یکبار فراخوانی نکنید.

ارائه مقادیر وابسته به زمان

برخی از پیچیدگی‌ها نیاز دارند مقداری را نمایش دهند که مربوط به زمان فعلی باشد. برای مثال می‌توان به تاریخ فعلی، زمان تا جلسه بعدی یا زمان در منطقه زمانی دیگر اشاره کرد.

برای به‌روز نگه داشتن مقادیر، هر ثانیه یا دقیقه یک کامپوننت را به‌روزرسانی نکنید. در عوض، مقادیر را نسبت به تاریخ یا زمان فعلی با استفاده از متن وابسته به زمان مشخص کنید. کلاس‌های زیر به شما امکان می‌دهند این مقادیر وابسته به زمان را ایجاد کنید:

داده‌های جدول زمانی

برای منابع داده‌ی پیچیدگی که توالی از مقادیر را در زمان‌های از پیش تعریف‌شده ارائه می‌دهند، از SuspendingTimelineComplicationDataSourceService استفاده کنید.

یک مثال از این می‌تواند یک منبع داده "رویداد بعدی" از یک برنامه تقویم باشد: به جای اینکه سیستم مجبور باشد به طور منظم برای رویداد بعدی از منبع داده نظرسنجی کند، منبع داده می‌تواند یک بار جدول زمانی رویدادها را ارائه دهد و سپس منبع داده می‌تواند در صورت تغییر تقویم، به‌روزرسانی‌ها را آغاز کند. این کار بار سیستم را به حداقل می‌رساند و به پیچیدگی اجازه می‌دهد تا رویداد صحیح را به موقع نشان دهد: 

class MyTimelineComplicationDataSourceService : SuspendingTimelineComplicationDataSourceService() {
    override suspend fun onComplicationRequest(request: ComplicationRequest): ComplicationDataTimeline? {
        if (request.complicationType != ComplicationType.SHORT_TEXT) {
            return ComplicationDataTimeline(
                defaultComplicationData = NoDataComplicationData(),
                timelineEntries = emptyList()
            )
        }
        // Retrieve list of events from your own datasource / database.
        val events = getCalendarEvents()
        return ComplicationDataTimeline(
            defaultComplicationData = shortTextComplicationData("No event"),
            timelineEntries = events.map {
                TimelineEntry(
                    validity = TimeInterval(it.start, it.end),
                    complicationData = shortTextComplicationData(it.name)
                )
            }
        )
    }

    override fun getPreviewData(type: ComplicationType): ComplicationData? {
        return shortTextComplicationData("Event 1")
    }

    private fun shortTextComplicationData(text: String) =
        ShortTextComplicationData.Builder(
            text = PlainComplicationText.Builder(text).build(),
            contentDescription = PlainComplicationText.Builder(text).build()
        )
            // Add further optional details here such as icon, tap action, title etc
            .build()

    // ...
}

رفتار SuspendingTimelineComplicationDataSourceService به شرح زیر است:

  • وقتی زمان فعلی در بازه زمانی شروع و پایان یک ورودی در جدول زمانی قرار می‌گیرد، صفحه ساعت از آن مقدار استفاده می‌کند.
  • وقتی زمان فعلی در هیچ ورودی در جدول زمانی قرار نمی‌گیرد، از مقدار پیش‌فرض استفاده می‌شود. برای مثال، در برنامه تقویم، این می‌تواند «بدون رویداد» باشد.
  • اگر زمان فعلی در چندین رویداد قرار گیرد، از کوتاه‌ترین رویداد استفاده می‌شود.

ارائه مقادیر پویا

با شروع از Wear OS 4، برخی از Complexityها می‌توانند مقادیری را نمایش دهند که بر اساس مقادیری که مستقیماً در پلتفرم در دسترس هستند، مرتباً به‌روزرسانی می‌شوند. برای ارائه این قابلیت در Complexityهای خود، از فیلدهای ComplicationData که مقادیر پویا را می‌پذیرند استفاده کنید. پلتفرم این مقادیر را مرتباً ارزیابی و به‌روزرسانی می‌کند، بدون اینکه نیازی به اجرای ارائه‌دهنده Complexity باشد.

فیلدهای نمونه شامل فیلد مقدار پویای GoalProgressComplicationData و DynamicComplicationText هستند که می‌توانند در هر فیلد ComplicationText استفاده شوند. این مقادیر پویا بر اساس کتابخانه androidx.wear.protolayout.expression هستند.

در شرایط خاص، پلتفرم نمی‌تواند مقادیر پویا را ارزیابی کند:

  • گاهی اوقات مقدار پویا در دسترس نیست: این اتفاق می‌افتد، برای مثال، زمانی که دستگاه از مچ دست خارج می‌شود. در این شرایط، پلتفرم به جای آن از مقدار فیلد جایگزین ابطال مقدار پویا ، در یک فیلد جای‌گزین NoDataComplicationData استفاده می‌کند.
  • مقدار پویا هرگز در دسترس نیست: این اتفاق در دستگاهی رخ می‌دهد که نسخه قدیمی‌تر Wear OS 4 را اجرا می‌کند. در این شرایط، پلتفرم از یک فیلد جایگزین همراه، مانند getFallbackValue () استفاده می‌کند.