Đưa dữ liệu vào chức năng

Các nguồn dữ liệu chức năng hiển thị thông tin cho chức năng của mặt đồng hồ, cung cấp văn bản, hình ảnh và số mà mặt đồng hồ có thể hiển thị.

Dịch vụ nguồn dữ liệu mở rộng SuspendingComplicationDataSourceService để cung cấp thông tin hữu ích trực tiếp trên mặt đồng hồ.

Bắt đầu

Thêm phần phụ thuộc sau vào mô-đun ứng dụng: 

dependencies {
  implementiation("androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1")
}

Tạo dịch vụ nguồn dữ liệu

Khi cần dữ liệu chức năng, hệ thống Wear OS sẽ gửi yêu cầu cập nhật đến nguồn dữ liệu của bạn. Để phản hồi các yêu cầu cập nhật, nguồn dữ liệu của bạn phải triển khai phương thức onComplicationRequest() của lớp SuspendingComplicationDataSourceService.

Hệ thống Wear OS gọi onComplicationRequest() khi cần dữ liệu của nguồn, chẳng hạn như khi một chức năng cần sử dụng dữ liệu của nguồn để có thể hoạt động hoặc khi một khoảng thời gian cố định trôi qua.

Lưu ý: Khi nguồn dữ liệu cung cấp dữ liệu, mặt đồng hồ sẽ nhận được các giá trị thô. Mặt đồng hồ chịu trách nhiệm định dạng dữ liệu để hiển thị.

Đoạn mã sau đây cho thấy một quy trình triển khai mẫu:

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

    // ...
}

Quyền và nội dung khai báo trong tệp kê khai

Nguồn dữ liệu phải bao gồm các nội dung khai báo cụ thể trong tệp kê khai ứng dụng để được hệ thống Android coi là một nguồn dữ liệu. Phần này giải thích các chế độ cài đặt bắt buộc cho nguồn dữ liệu.

Trong tệp kê khai của ứng dụng, hãy khai báo dịch vụ và thêm bộ lọc ý định hành động yêu cầu cập nhật. Tệp kê khai cũng phải bảo vệ dịch vụ bằng cách thêm quyền BIND_COMPLICATION_PROVIDER để đảm bảo chỉ hệ thống Wear OS mới có thể liên kết với các dịch vụ của ứng dụng nhà cung cấp dữ liệu.

Ngoài ra, hãy đưa thuộc tính android:icon vào phần tử service cung cấp biểu tượng màu trắng đơn sắc. Bạn nên sử dụng các vectơ vẽ được cho các biểu tượng. Biểu tượng này đại diện cho nguồn dữ liệu và xuất hiện trong trình chọn chức năng.

Ví dụ: 

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

Phần tử siêu dữ liệu

Trong tệp kê khai, hãy lưu ý các phần tử siêu dữ liệu sau:

  • android:name="android.support.wearable.complications.SUPPORTED_TYPES": Chỉ định các loại dữ liệu chức năng mà nguồn dữ liệu hỗ trợ.
  • android:name="android.support.wearable.complications.UPDATE_PERIOD_SECONDS": Chỉ định tần suất hệ thống nên kiểm tra các bản cập nhật dữ liệu.

Khi nguồn dữ liệu bổ sung của bạn đang hoạt động, UPDATE_PERIOD_SECONDS sẽ chỉ định tần suất bạn muốn hệ thống kiểm tra các bản cập nhật dữ liệu. Nếu thông tin hiện trong chức năng không cần cập nhật theo lịch định kỳ, chẳng hạn như khi bạn sử dụng bản cập nhật dạng đẩy, hãy đặt giá trị này thành 0.

Nếu không đặt UPDATE_PERIOD_SECONDS thành 0 thì bạn phải sử dụng giá trị tối thiểu là 300 (5 phút). Đây là thời gian cập nhật tối thiểu mà hệ thống thực thi để duy trì tuổi thọ pin của thiết bị. Ngoài ra, hãy lưu ý rằng yêu cầu cập nhật có thể ít thường xuyên hơn khi thiết bị ở chế độ môi trường xung quanh hoặc đang không được đeo.

Thêm hoạt động cấu hình

Nếu cần, nguồn dữ liệu có thể đưa vào hoạt động cấu hình được hiện cho người dùng khi người dùng chọn nguồn dữ liệu cụ thể đó trong bộ chọn chức năng. Ví dụ: nguồn dữ liệu đồng hồ thế giới có thể có một hoạt động cấu hình cho phép người dùng chọn thành phố hoặc múi giờ để hiển thị.

Tệp kê khai mẫu có một phần tử meta-data với khoá PROVIDER_CONFIG_ACTION. Giá trị của phần tử này là thao tác được dùng để khởi chạy hoạt động định cấu hình.

Tạo hoạt động cấu hình và thêm một bộ lọc ý định khớp với thao tác cho hoạt động đó trong tệp kê khai. 

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

Hoạt động có thể lấy thông tin chi tiết về khe hở tiện ích mà hoạt động đó đang định cấu hình từ ý định trong phương thức onCreate() của hoạt động: 

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

Hoạt động định cấu hình phải nằm trong cùng một gói với ứng dụng nhà cung cấp. Hoạt động cấu hình phải trả về RESULT_OK hoặc RESULT_CANCELED để cho hệ thống biết có nên đặt nguồn dữ liệu hay không: 

setResult(RESULT_OK) // Or RESULT_CANCELED to cancel configuration
finish()

Sử dụng các bản cập nhật đẩy

Thay vì chỉ định khoảng thời gian giữa những lần cập nhật trong tệp kê khai của ứng dụng, bạn có thể sử dụng một thực thể của ComplicationDataSourceUpdateRequester để bắt đầu các bản cập nhật một cách linh hoạt. Để yêu cầu cập nhật, hãy gọi requestUpdate().

Thận trọng: Để duy trì thời lượng pin của thiết bị, đừng gọi requestUpdate() qua thực thể của ComplicationDataSourceUpdateRequester thường xuyên hơn trung bình 5 phút một lần.

Cung cấp các giá trị phụ thuộc vào thời gian

Một số chức năng cần hiển thị một giá trị liên quan đến thời gian hiện tại. Ví dụ bao gồm ngày hiện tại, thời gian diễn ra cuộc họp tiếp theo hoặc thời gian ở một múi giờ khác.

Đừng cập nhật một chức năng từng giây hoặc phút để duy trì cập nhật các giá trị đó. Thay vào đó, hãy chỉ định các giá trị tương ứng với ngày hoặc giờ hiện tại bằng cách sử dụng giá trị phụ thuộc vào thời gian. Các lớp sau đây cho phép bạn tạo những giá trị phụ thuộc vào thời gian này:

Dữ liệu trên Dòng thời gian

Đối với các nguồn dữ liệu chức năng cung cấp một chuỗi giá trị tại thời điểm xác định trước, hãy sử dụng SuspendingTimelineComplicationDataSourceService.

Ví dụ: nguồn dữ liệu "sự kiện tiếp theo" của một ứng dụng lịch: Thay vì hệ thống phải thường xuyên thăm dò nguồn dữ liệu để tìm sự kiện tiếp theo, nguồn dữ liệu có thể cung cấp một dòng thời gian của các sự kiện một lần, sau đó nguồn dữ liệu có thể bắt đầu cập nhật nếu lịch thay đổi. Điều này giúp giảm thiểu tải cho hệ thống và cho phép mặt đồng hồ hiển thị đúng sự kiện một cách kịp thời: 

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

    // ...
}

Hành vi của SuspendingTimelineComplicationDataSourceService như sau:

  • Khi thời gian hiện tại nằm trong khoảng thời gian bắt đầu và kết thúc của một mục trong dòng thời gian, mặt đồng hồ sẽ sử dụng giá trị đó.
  • Khi thời gian hiện tại không nằm trong bất kỳ mục nào trong dòng thời gian, giá trị mặc định sẽ được sử dụng. Ví dụ: trong ứng dụng lịch, trạng thái này có thể là "Không có sự kiện".
  • Nếu thời gian hiện tại nằm trong nhiều sự kiện, thì sự kiện ngắn nhất sẽ được sử dụng.

Cung cấp các giá trị linh động

Kể từ Wear OS 4, một số chức năng có thể cho thấy các giá trị có tần suất làm mới nhanh hơn dựa trên các giá trị có sẵn truyền trực tiếp đến nền tảng. Để cung cấp chức năng này trong các chức năng của bạn, hãy sử dụng các trường ComplicationData chấp nhận giá trị động. Nền tảng thường xuyên đánh giá và cập nhật các giá trị này mà không cần đến đơn vị cung cấp chức năng.

Các trường ví dụ bao gồm trường giá trị động của GoalProgressComplicationData và DynamicComplicationText. Bạn có thể sử dụng trường này trong mọi trường ComplicationText. Các giá trị động này dựa trên thư viện androidx.wear.protolayout.expression.

Trong một số trường hợp, nền tảng không thể đánh giá các giá trị động: