Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

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

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

บริการแหล่งข้อมูลจะขยาย 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()

    // ...
}MyComplicationDataSourceService.kt

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

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

ในไฟล์ Manifest ของแอป ให้ประกาศบริการและเพิ่มตัวกรอง Intent สำหรับการดำเนินการตามคำขออัปเดต ไฟล์ 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>AndroidManifest.xml

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

ในไฟล์ 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>AndroidManifest.xml

กิจกรรมจะได้รับรายละเอียดของช่องสำหรับข้อมูลแทรกที่กำลังกำหนดค่าจาก 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)ConfigurationActivity.kt

กิจกรรมการกำหนดค่าต้องอยู่ในแพ็กเกจเดียวกับผู้ให้บริการ กิจกรรมการกำหนดค่าต้องแสดงผล RESULT_OK หรือ RESULT_CANCELED เพื่อแจ้งให้ระบบทราบว่าควรตั้งค่าแหล่งข้อมูลหรือไม่ ดังนี้

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

ใช้การอัปเดตแบบพุช

คุณสามารถใช้อินสแตนซ์ของ ComplicationDataSourceUpdateRequester เพื่อเริ่มการอัปเดตแบบไดนามิกแทนการระบุช่วงเวลาอัปเดตในไฟล์ Manifest ของแอปได้ หากต้องการขออัปเดต โปรดโทรหา requestUpdate()

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

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

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

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

TimeFormatComplicationText - จัดรูปแบบค่าวันที่หรือเวลา
TimeDifferenceComplicationText - นับขึ้นหรือนับถอยหลังไปยังเวลาที่ระบุ

ข้อมูลไทม์ไลน์

สำหรับแหล่งข้อมูลกลไกหน้าปัดที่ให้ลำดับค่าตามเวลาที่กำหนดไว้ล่วงหน้า ให้ใช้ SuspendingTimelineComplicationDataSourceService

ตัวอย่างเช่น แหล่งข้อมูล "กิจกรรมถัดไป" จากแอปปฏิทิน: แทนที่ระบบจะต้องสุ่มสำรวจแหล่งข้อมูลเป็นประจำสำหรับกิจกรรมถัดไป แหล่งข้อมูลสามารถระบุไทม์ไลน์ของกิจกรรมได้ 1 ครั้ง จากนั้นแหล่งข้อมูลจะเริ่มอัปเดตได้หากปฏิทินมีการเปลี่ยนแปลง ซึ่งจะช่วยลดภาระของระบบและช่วยให้คอมพลิเคชันแสดงกิจกรรมที่ถูกต้องได้ทันท่วงที

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