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 ถือว่าเป็น แหล่งข้อมูล ส่วนนี้จะอธิบายการตั้งค่าที่จำเป็นสำหรับ แหล่งข้อมูล

ประกาศบริการและเพิ่มตัวกรอง 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>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.

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

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ช่องค่าแบบไดนามิกของ's และ DynamicComplicationText ซึ่งใช้ได้ใน ComplicationText ช่อง ค่าแบบไดนามิกเหล่านี้อิงตามไลบรารี androidx.wear.protolayout.expression

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

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

ประเภทและช่อง

ที่เก็บตัวอย่าง Wear OS