‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

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

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

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

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

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

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

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

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

نمایش دادن داده‌ها در عملکردهای اضافی با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.