Bản xem trước tiện ích được tạo cho phép bạn tạo bản xem trước động, phù hợp với từng cá nhân cho các tiện ích của mình, phản ánh chính xác cách các tiện ích đó sẽ xuất hiện trên màn hình chính của người dùng. Các thông tin này được cung cấp thông qua một API truyền dữ liệu, tức là ứng dụng của bạn cung cấp bản xem trước tại bất kỳ thời điểm nào trong vòng đời của ứng dụng mà không nhận được yêu cầu rõ ràng nào từ máy chủ lưu trữ tiện ích.
Hướng dẫn này trình bày cách cung cấp bản xem trước cho các tiện ích dựa trên Glance. Nếu tiện ích của bạn được triển khai bằng RemoteViews, hãy xem phần Thêm bản xem trước vào bộ chọn tiện ích.
Để cải thiện trải nghiệm của trình chọn tiện ích cho tiện ích Glance trong ứng dụng, hãy cung cấp bản xem trước tiện ích đã tạo bằng GlanceAppWidget.providePreview trên Android 15 trở lên, đồng thời chỉ định previewImage cho các phiên bản trước đó và làm phương án dự phòng trên Android 15 trở lên nếu không có bản xem trước đã tạo.
Để biết thêm thông tin, hãy xem video Làm phong phú ứng dụng bằng thông tin cập nhật trực tiếp và tiện ích trên YouTube.
Thiết lập ứng dụng để xem trước tiện ích được tạo
Để hiển thị Bản xem trước của tiện ích đã tạo trên thiết bị Android 15 trở lên, trước tiên, hãy đặt giá trị compileSdk thành 35 trở lên trong tệp build.gradle của mô-đun để có thể cung cấp RemoteViews cho bộ chọn tiện ích
Sau đó, các ứng dụng có thể dùng setWidgetPreview trong GlanceAppWidgetManager. Để ngăn chặn hành vi sai trái và giảm bớt các vấn đề về tình trạng hệ thống, setWidgetPreview là một API bị giới hạn tốc độ. Hạn mức mặc định là khoảng 2 cuộc gọi mỗi giờ.
Tạo bản xem trước mới bằng Jetpack Glance
Đối với các tiện ích được tạo bằng Jetpack Glance, hãy làm như sau:
Ghi đè hàm
GlanceAppWidget.providePreviewđể cung cấp nội dung có khả năng kết hợp cho bản xem trước. Như trongprovideGlance, hãy tải dữ liệu của ứng dụng và truyền dữ liệu đó đến thành phần kết hợp nội dung của tiện ích để bản xem trước hiển thị dữ liệu chính xác. Không giống nhưprovideGlance, đây là một thành phần duy nhất, không có thành phần kết hợp lại hoặc hiệu ứng.Gọi
GlanceAppWidgetManager.setWidgetPreviewsđể tạo và xuất bản bản xem trước.
Không có lệnh gọi lại từ hệ thống để cung cấp bản xem trước, vì vậy, ứng dụng của bạn phải quyết định thời điểm gọi setWidgetPreviews. Chiến lược cập nhật phụ thuộc vào trường hợp sử dụng của tiện ích:
- Nếu tiện ích có thông tin tĩnh hoặc là một thao tác nhanh, hãy đặt bản xem trước khi ứng dụng được khởi chạy lần đầu.
- Bạn có thể đặt bản xem trước sau khi ứng dụng có dữ liệu; ví dụ: sau khi người dùng đăng nhập hoặc thiết lập ban đầu.
- Bạn có thể thiết lập một tác vụ định kỳ để cập nhật bản xem trước theo nhịp độ đã chọn.
Khắc phục sự cố về bản xem trước được tạo
Một vấn đề thường gặp là sau khi bạn tạo bản xem trước, hình ảnh, biểu tượng hoặc các thành phần kết hợp khác có thể bị thiếu trong hình ảnh xem trước, so với kích thước thả của tiện ích. Kích thước thả này được xác định bằng targetCellWidth và targetCellHeight (nếu được chỉ định) hoặc bằng minWidth và minHeight trong tệp thông tin của nhà cung cấp tiện ích ứng dụng.
Điều này xảy ra vì theo mặc định, Android chỉ kết xuất các thành phần kết hợp hiển thị ở kích thước tối thiểu của tiện ích. Nói cách khác, theo mặc định, Android sẽ đặt previewSizeMode thành SizeMode.Single. Thao tác này sử dụng android:minHeight và android:minWidth trong XML thông tin về trình cung cấp tiện ích ứng dụng để xác định thành phần kết hợp nào cần vẽ.
Để khắc phục vấn đề này, hãy ghi đè previewSizeMode trong GlanceAppWidget và đặt thành SizeMode.Responsive, cung cấp một tập hợp các giá trị DpSize. Thao tác này cho Android biết tất cả các kích thước bố cục cần thiết để hiển thị bản xem trước, đảm bảo tất cả các phần tử đều hiển thị chính xác.
Tối ưu hoá cho các hệ số hình dạng cụ thể. Cung cấp một hoặc hai kích thước bắt đầu từ kích thước tối thiểu và tuân theo các điểm ngắt của tiện ích. Chỉ định ít nhất một previewImage để tương thích ngược. Bạn có thể tìm thấy các giá trị DP tối thiểu phù hợp cho nhiều kích thước lưới trong hướng dẫn thiết kế tiện ích.
Khả năng tương thích ngược với bản xem trước tiện ích
Để cho phép bộ chọn tiện ích trên các thiết bị chạy phiên bản thấp hơn Android 15 hiển thị bản xem trước tiện ích của bạn hoặc làm phương án dự phòng cho Bản xem trước được tạo trên Android 15 trở lên, hãy chỉ định thuộc tính previewImage.
Nếu bạn thay đổi giao diện của tiện ích, hãy cập nhật hình ảnh xem trước.