نمایش دادن داده‌ها در عملکردهای اضافی

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

سرویس منبع داده 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()

    // ...
}
MyComplicationDataSourceService.kt

اظهارنامه‌ها و اجازه‌های مانیفست

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

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

همچنین، یک مشخصه android:icon در عنصر service اضافه کنید که نماد سفید تک‌رنگ ارائه دهد. توصیه می‌کنیم برای نمادها از ترسیمی‌های بُرداری استفاده کنید. این نماد نشان‌دهنده منبع داده است و در انتخابگر پیچیدگی نشان داده می‌شود.

مثالی در اینجا ارائه شده است:

<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>
AndroidManifest.xml

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

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

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

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

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

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

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

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

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

<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>
AndroidManifest.xml

فعالیت می‌تواند جزئیات جایگاه عملکرد اضافی را که درحال پیکربندی آن است از هدف درون روش 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)
ConfigurationActivity.kt

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

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()
ConfigurationActivity.kt

استفاده از به‌روزرسانی‌های لحظه‌ای

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

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

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

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

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

• TimeFormatComplicationText - مقدار تاریخ یا زمان را قالب‌بندی می‌کند.
• TimeDifferenceComplicationText - تا زمان مشخصی به‌صورت صعودی یا نزولی شمارش می‌کند.

داده‌های «خط زمان»

برای منابع داده پیچیدگی که دنباله‌ای از مقادیر را در زمان‌های ازپیش‌تعریف‌شده ارائه می‌دهند، از 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()

    // ...
}
MyTimelineComplicationDataSourceService.kt

رفتار SuspendingTimelineComplicationDataSourceService به‌صورت زیر است:

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

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

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

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

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

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

منابع مربوط

• انواع و فیلدها

• مخزن نمونه‌های Wear OS