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ề. Lưu ý rằng các trường không bắt buộc không đảm bảo sẽ xuất hiện.
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 Mô tả nội dung |
Chỉ một biểu tượng hoặc tiêu đề ngắn xuất hiện nếu bạn cung cấp một trong hai hoặc cả hai trường. |
MONOCHROMATIC_IMAGE
|
Hình ảnh đơn sắc |
Biểu tượng bảo vệ chống pixel bị hỏng Mô tả nội dung |
Đượ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 |
Hình ảnh đơn sắc Biểu tượng bảo vệ chống pixel bị hỏng Văn bản ngắn Tiêu đề ngắn Đoạn dốc màu Giá trị động Mô tả nội dung |
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.
|
GOAL_PROGRESS
|
Giá trị Giá trị mục tiêu |
Hình ảnh đơn sắc Biểu tượng bảo vệ chống pixel bị hỏng Văn bản ngắn Tiêu đề ngắn Đoạn dốc màu Giá trị động Mô tả nội dung |
GOAL_PROGRESS được dành cho những trường như số bước khi Giá trị bắt đầu từ 0 và được phép vượt quá Giá trị mục tiêu. |
LONG_TEXT
|
Văn bản dài |
Tiêu đề dài Hình ảnh đơn sắc Biểu tượng bảo vệ chống pixel bị hỏng Hình ảnh nhỏ Mô tả nội dung |
Tiêu đề dài xuất hiện, nếu có. |
SMALL_IMAGE
|
Hình ảnh nhỏ |
Mô tả nội dung |
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 |
Mô tả nội dung |
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.
|
WEIGHTED_ELEMENTS
|
Danh sách phần tử |
Hình ảnh đơn sắc Biểu tượng bảo vệ chống pixel bị hỏng Văn bản ngắn Tiêu đề ngắn Mô tả nội dung |
Mỗi phần tử bao gồm một màu và một trọng số (lớn hơn 0). Kích thước của phần tử khi được kết xuất phải tương ứng với trọng số của phần tử đó. Không bắt buộc có trọng số để tính tổng vào bất kỳ giá trị cụ thể nào. Lưu ý rằng mặt đồng hồ được phép đổi màu WEIGHTED_ELEMENTS. |
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.
Đề xuất cho bạn
- Lưu ý: văn bản có đường liên kết sẽ hiện khi JavaScript tắt
- DefaultProviderPolicy
- ComplicationSlot
- Complication