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. Khi sử dụng Định dạng mặt đồng hồ, bạn có thể chọn nguồn dữ liệu để 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 Định dạng mặt đồng hồ

Phần tử Complication cho phép bạn xác định tối đa 8 chức năng trong một mặt đồng hồ. Phần tử này cũng cho phép bạn xác định vị trí xuất hiện của từng chức năng trên mặt đồng hồ.

Để biết thêm thông tin, hãy xem mẫu WatchFaceFormat trên GitHub.

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ề. Ví dụ: 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.

Trên một số thiết bị, mặt đồng hồ và chức năng phải sử dụng Định dạng mặt đồng hồ

Nếu mặt đồng hồ hiện tại của bạn sử dụng thư viện Mặt đồng hồ Jetpack hoặc Thư viện hỗ trợ thiết bị đeo, thì người dùng sẽ tiếp tục thấy dữ liệu từ tất cả các nguồn dữ liệu trong các chức năng của mặt đồng hồ trên các thiết bị sau:

• Thiết bị chạy Wear OS 4 trở xuống.
• Những thiết bị nhận được bản nâng cấp OTA lên Wear OS 5.

Hơn nữa, nếu mặt đồng hồ hiện tại của bạn sử dụng thư viện Mặt đồng hồ Jetpack hoặc Thư viện hỗ trợ thiết bị đeo và được cài đặt trên một trong các thiết bị này, thì mặt đồng hồ có thể tiếp tục nhận được bản cập nhật.

Tuy nhiên, trên các đồng hồ mới chạy Wear OS 5, mặt đồng hồ phải sử dụng Định dạng mặt đồng hồ. Vì lý do này, bạn nên chuyển sang sử dụng Định dạng mặt đồng hồ.