Bản xem trước tiện ích được tạo cho phép bạn tạo bản xem trước linh động, được cá nhân hoá cho tiện ích của mình, phản ánh chính xác cách tiện ích sẽ xuất hiện trên màn hình chính của người dùng. Các bản xem trước này được cung cấp thông qua một API đẩy, 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 mà không cần nhận yêu cầu rõ ràng 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 bộ chọn tiện ích trong ứng dụng cho các tiện ích Glance, hãy cung cấp bản xem trước tiện ích được tạo bằng GlanceAppWidget.providePreview trên các thiết bị Android 15 trở lên và chỉ định previewImage cho các phiên bản thấp hơn, đồng thời 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 đượ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 cho bản xem trước tiện ích được tạo
Để hiển thị bản xem trước tiện ích được 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 để bật bản xem trước được tạo trong bộ chọn tiện ích.
Sau đó, các ứng dụng có thể sử dụng setWidgetPreview trong GlanceAppWidgetManager. Để ngăn chặn hành vi sai trái và giảm thiểu các vấn đề về tình trạng hệ thống, setWidgetPreview là một API có giới hạn số lượng yêu cầu. Hạn mức mặc định là khoảng hai lệnh gọi mỗi giờ.
Tạo bản xem trước mới nhất 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. Tương tự 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.
Hệ thống không có lệnh gọi lại để 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 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 tần suất đã 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, Android đặt previewSizeMode thành SizeMode.Single theo mặc định. Thành phần này sử dụng android:minHeight và android:minWidth trong XML thông tin của 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 rồi đặt thành SizeMode.Responsive, cung cấp một tập hợp các giá trị DpSize. Điều này cho Android biết tất cả kích thước bố cục cần hiển thị cho 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 kiểu dáng thiết bị 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à theo các điểm ngắt của tiện ích. Chỉ định ít nhất một previewImage để hỗ trợ các phiên bản Android thấp hơn. Bạn có thể tìm thấy các giá trị DP tối thiểu thích hợp cho nhiều kích thước lưới trong hướng dẫn thiết kế tiện ích.
Hỗ trợ các phiên bản Android thấp hơn
Để hiện bản xem trước tiện ích trên các thiết bị chạy Android 14 trở xuống hoặc khi không có 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.