Thêm các chức năng vào mặt đồng hồ

Chức năng mặt đồng hồ hiển thị dữ liệu từ một nguồn dữ liệu. Với Complications API (API Chức năng), các mặt đồng hồ có thể chọn nguồn dữ liệu mà chúng muốn sử dụng để lấy dữ liệu cơ bản. API này giúp mặt đồng hồ hiển thị thông tin ngoài thời gian trong ngày mà không cần có mã để nhận dữ liệu.

Sử dụng ComplicationSlotsManager

Để thêm các chức năng vào mặt đồng hồ, hãy dùng ComplicationSlotsManager.

ComplicationSlotsManager xác định số lượng chức năng mà mặt đồng hồ hỗ trợ cũng như vị trí của các chức năng đó trên màn hình. Để hỗ trợ việc thay đổi vị trí hoặc số lượng các chức năng, ComplicationSlotsManager cũng sử dụng CurrentUserStyleRepository như minh hoạ trong ví dụ sau:

 override fun createComplicationSlotsManager(
        currentUserStyleRepository: CurrentUserStyleRepository
    ): ComplicationSlotsManager {
        val defaultCanvasComplicationFactory =
            CanvasComplicationFactory { watchState, listener ->
                // ...
            }

        val leftComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 100,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        val rightComplicationSlot = ComplicationSlot.createRoundRectComplicationSlotBuilder(
            id = 101,
            canvasComplicationFactory = defaultCanvasComplicationFactory,
            // ...
        )
            .setDefaultDataSourceType(ComplicationType.SHORT_TEXT)
            .build()

        return ComplicationSlotsManager(
            listOf(leftComplicationSlot, rightComplicationSlot),
            currentUserStyleRepository
        )
 }

Loại và trường

Bảng sau đây mô tả các loại và trường của đối tượng ComplicationData. Nếu mặt đồng hồ yêu cầu một trường không hợp lệ cho một loại chức năng, thì giá trị mặc định cho trường đó sẽ được trả về. Chẳng hạn như nếu mặt đồng hồ cố gắng truy cập vào trường LONG_TEXT trong loại SHORT_TEXT, thì giá trị mặc định cho trường LONG_TEXT là rỗng sẽ bị trả về.

Loại Trường bắt buộc Trường không bắt buộc Ghi chú
SHORT_TEXT Văn bản ngắn Biểu tượng
Biểu tượng bảo vệ chống pixel bị hỏng
Tiêu đề ngắn 		Chỉ hiển thị một biểu tượng hoặc tiêu đề ngắn nếu bạn cung cấp một trong hai hoặc cả hai.
ICON Biểu tượng Biểu tượng bảo vệ chống pixel bị hỏng Được dùng khi không cần văn bản. Biểu tượng dự kiến sẽ có một màu và có thể được phủ màu theo mặt đồng hồ.
RANGED_VALUE Giá trị
Giá trị tối thiểu
Giá trị tối đa 		Biểu tượng
Biểu tượng bảo vệ chống pixel bị hỏng
Văn bản ngắn
Tiêu đề ngắn 		Các trường không bắt buộc không đảm bảo sẽ được hiển thị. Nếu muốn vẽ thanh tiến trình của riêng mình, bạn có thể sử dụng phương thức isRangedValueProgressHidden() để ẩn thanh tiến trình do lớp ComplicationDrawable cung cấp.
LONG_TEXT Văn bản dài Tiêu đề dài
Biểu tượng
Biểu tượng bảo vệ chống pixel bị hỏng
Hình ảnh nhỏ 		Hiển thị tiêu đề dài nếu có.
SMALL_IMAGE Hình ảnh nhỏ Hình ảnh nhỏ có một trong 2 kiểu: kiểu ảnh hoặc kiểu biểu tượng. Kiểu ảnh có nghĩa là ảnh sẽ lấp đầy không gian và có thể bị cắt. Kiểu biểu tượng có nghĩa là biểu tượng không được cắt bớt và có thể dùng làm khoảng đệm. Sự thay đổi hình ảnh có thể dẫn đến tình trạng hình ảnh không phù hợp để hiển thị ở chế độ môi trường xung quanh trên các thiết bị có tính năng bảo vệ chống pixel bị hỏng hoặc ở chế độ môi trường xung quanh có bit thấp. Khi bật tính năng bảo vệ chống pixel bị hỏng hoặc chế độ môi trường xung quanh có bit thấp, mặt đồng hồ có thể sử dụng hình ảnh nhỏ được bảo vệ chống pixel bị hỏng vì hình ảnh này an toàn. Nếu không, mặt đồng hồ sẽ khó xác định được mức độ phù hợp nên sẽ không hiển thị hình ảnh.
LARGE_IMAGE Hình ảnh lớn Hình ảnh này phải đủ lớn để lấp đầy mặt đồng hồ. Sự thay đổi hình ảnh có thể dẫn đến tình trạng hình ảnh không phù hợp để hiển thị ở chế độ môi trường xung quanh trên các thiết bị có tính năng bảo vệ chống pixel bị hỏng hoặc ở chế độ môi trường xung quanh có bit thấp. Vì mặt đồng hồ khó xác định được mức độ phù hợp để hiển thị hình ảnh, nên mặt đồng hồ sẽ không hiển thị hình ảnh ở chế độ môi trường xung quanh nếu bật tính năng bảo vệ chống pixel bị hỏng hoặc chế độ môi trường xung quanh có bit thấp.

Bảng sau đây mô tả các loại chức năng cho dữ liệu trống có thể được gửi cho bất kỳ khu vực hiển thị chức năng nào. Những loại này không có trường và không cần đưa vào danh sách các loại được hỗ trợ. Những loại này cho phép mặt đồng hồ phân biệt giữa 3 trường hợp sau:

  • Không có nguồn nào được chọn
  • Người dùng đã chọn tuỳ chọn "trống" cho một khu vực
  • Nguồn không có dữ liệu để gửi

Nguồn không gửi được TYPE_EMPTY theo yêu cầu cập nhật. Thay vào đó, hãy gửi TYPE_NO_DATA.

Loại chức năng Nội dung mô tả
TYPE_NOT_CONFIGURED Do hệ thống gửi khi một chức năng được kích hoạt nhưng người dùng chưa chọn nguồn và chưa đặt giá trị mặc định.

Không thể do nguồn gửi.

TYPE_EMPTY Do hệ thống gửi khi một chức năng được kích hoạt và người dùng chọn "trống" thay vì chọn nguồn hoặc khi mặt đồng hồ chọn không có nguồn và chọn loại chức năng này làm loại mặc định.

Không thể do nguồn gửi.

TYPE_NO_DATA Do hệ thống gửi khi một chức năng (có nguồn) được kích hoạt để xoá chức năng đó trước khi nhận được dữ liệu thực tế từ nguồn.

Có thể do nguồn gửi nếu nguồn không có dữ liệu thực để gửi.

Để biết thêm thông tin chi tiết, vui lòng xem mẫu mặt đồng hồ trên GitHub.