เปิดเผยข้อมูลต่อข้อมูลแทรก

แหล่งข้อมูลแทรกจะแสดงข้อมูลต่อภาวะแทรกซ้อนของหน้าปัด โดยให้ข้อความ รูปภาพ และตัวเลขที่หน้าปัดแสดงได้

บริการแหล่งข้อมูลจะขยาย SuspendingComplicationDataSourceService เพื่อส่งข้อมูลที่เป็นประโยชน์ ไปยังหน้าปัดโดยตรง

เริ่มต้นใช้งาน

เพิ่มทรัพยากร Dependency ต่อไปนี้ลงในโมดูลแอป

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()

    // ...
}

การประกาศและสิทธิ์ในไฟล์ Manifest

แหล่งข้อมูลต้องมีการประกาศที่เฉพาะเจาะจงในไฟล์ Manifest ของแอปเพื่อให้ระบบ Android ถือเป็นแหล่งข้อมูล ส่วนนี้จะอธิบายการตั้งค่าที่จำเป็นสำหรับแหล่งข้อมูล

ประกาศบริการและเพิ่มตัวกรอง Intent การดำเนินการคำขออัปเดตในไฟล์ Manifest ของแอป นอกจากนี้ Manifest ต้องปกป้องบริการโดยการเพิ่มสิทธิ์ BIND_COMPLICATION_PROVIDER เพื่อให้มั่นใจว่ามีเพียงระบบ Wear OS เท่านั้นที่เชื่อมโยงกับบริการของผู้ให้บริการได้

นอกจากนี้ ให้ใส่แอตทริบิวต์ android:icon ในองค์ประกอบ service ซึ่งมีไอคอนสีขาวสีเดียว เราขอแนะนำให้ใช้ Vector Drawable สำหรับไอคอน ไอคอนแสดงถึงแหล่งข้อมูลและจะปรากฏในเครื่องมือเลือกข้อมูลแทรก

ตัวอย่างเช่น

<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>

องค์ประกอบข้อมูลเมตา

ในไฟล์ Manifest ให้สังเกตองค์ประกอบข้อมูลเมตาต่อไปนี้

• 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 นาที) ซึ่งเป็น ระยะเวลาการอัปเดตขั้นต่ำที่ระบบบังคับใช้ เพื่อรักษา อายุการใช้งานแบตเตอรี่ของอุปกรณ์ นอกจากนี้ โปรดทราบว่าคำขออัปเดต จะเกิดขึ้นน้อยลงเมื่ออุปกรณ์อยู่ในโหมดแอมเบียนท์หรือไม่ได้สวมใส่

เพิ่มกิจกรรมการกำหนดค่า

หากจำเป็น แหล่งข้อมูลอาจมีกิจกรรมการกำหนดค่าที่ แสดงต่อผู้ใช้เมื่อผู้ใช้เลือกแหล่งข้อมูลนั้นจาก เครื่องมือเลือกข้อมูลแทรก ตัวอย่างเช่น แหล่งข้อมูลนาฬิกาทั่วโลกอาจมีการกำหนดค่า กิจกรรมที่อนุญาตให้ผู้ใช้เลือกเมืองหรือเขตเวลาที่จะแสดง

ไฟล์ Manifest ตัวอย่างมีองค์ประกอบ meta-data ที่มีคีย์ PROVIDER_CONFIG_ACTION ค่าขององค์ประกอบนี้คือการดำเนินการที่ใช้ เพื่อเปิดกิจกรรมการกำหนดค่า

สร้างกิจกรรมการกำหนดค่า และเพิ่มตัวกรอง Intent ที่ตรงกับการดำเนินการสำหรับกิจกรรมนั้นใน ไฟล์ Manifest

<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 เพื่อเริ่มการอัปเดตแบบไดนามิกแทนการระบุช่วงเวลาการอัปเดตในไฟล์ Manifest ของแอป หากต้องการขอรับการอัปเดต โปรดโทรไปที่ requestUpdate()

ข้อควรระวัง: เพื่อประหยัดอายุการใช้งานแบตเตอรี่ของอุปกรณ์ อย่าเรียกใช้ requestUpdate() จากอินสแตนซ์ของ ComplicationDataSourceUpdateRequester บ่อยกว่าทุกๆ 5 นาทีโดยเฉลี่ย

ระบุค่าที่ขึ้นอยู่กับเวลา

หน้าปัดบางแบบต้องแสดงค่าที่เกี่ยวข้องกับเวลาปัจจุบัน ตัวอย่างเช่น วันที่ปัจจุบัน เวลาจนกว่าจะถึงการประชุมครั้งถัดไป หรือเวลาในเขตเวลาอื่น

อย่าอัปเดตภาวะแทรกซ้อนทุก วินาทีหรือนาทีเพื่อให้ค่าเหล่านั้นเป็นข้อมูลล่าสุด ให้ระบุค่าเป็นค่าที่สัมพันธ์กับวันที่หรือเวลาปัจจุบันโดยใช้ข้อความที่ขึ้นอยู่กับเวลาแทน คลาสต่อไปนี้ ช่วยให้คุณสร้างค่าที่ขึ้นอยู่กับเวลาเหล่านี้ได้

• 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

ในบางกรณี แพลตฟอร์มจะประเมินค่าแบบไดนามิกไม่ได้

• บางครั้งค่าแบบไดนามิกอาจไม่พร้อมใช้งาน: กรณีนี้จะเกิดขึ้น เช่น เมื่อ อุปกรณ์ไม่ได้อยู่บนข้อมือ ในกรณีเหล่านี้ แพลตฟอร์มจะใช้ค่าของ NoDataComplicationDataNoDataComplicationDataแทนในNoDataComplicationDataNoDataComplicationData
• ค่าแบบไดนามิกไม่พร้อมใช้งาน: ปัญหานี้เกิดขึ้นในอุปกรณ์ที่ใช้ Wear OS 4 เวอร์ชันเก่ากว่า ในกรณีนี้ แพลตฟอร์มจะใช้ฟิลด์สำรองของโฆษณาที่แสดงร่วม เช่น getFallbackValue()

แหล่งข้อมูลที่เกี่ยวข้อง