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

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

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

    // ...
}

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

منابع داده باید اعلان‌های خاصی را در مانیفست برنامه‌شان لحاظ کنند تا سیستم 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>

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

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

• 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 (5 دقیقه) استفاده کنید، که حداقل دوره به‌روزرسانی است که سیستم اعمال می‌کند، تا عمر باتری دستگاه حفظ شود. علاوه بر این، به خاطر داشته باشید که زمانی که دستگاه در حالت محیطی قرار دارد یا پوشیده نمی شود، درخواست به روز رسانی کمتر انجام می شود.

یک فعالیت پیکربندی اضافه کنید

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

مانیفست مثال شامل یک عنصر 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>

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

احتیاط: برای حفظ عمر باتری دستگاه، به طور میانگین هر 5 دقیقه یکبار 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()

    // ...
}

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

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

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

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

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

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

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

منابع مرتبط