Màn hình chính của Android, có trên hầu hết các thiết bị chạy Android, cho phép
tiện ích ứng dụng (hoặc tiện ích) được người dùng nhúng cho
truy cập nhanh vào nội dung. Nếu bạn đang thay màn hình chính hoặc
ứng dụng tương tự, bạn cũng có thể cho phép người dùng nhúng tiện ích bằng cách triển khai
AppWidgetHost
. Đây không phải
việc mà hầu hết các ứng dụng cần làm, nhưng nếu bạn đang tạo máy chủ lưu trữ của riêng mình, đó
bạn cần hiểu rõ các nghĩa vụ theo hợp đồng mà máy chủ lưu trữ ngầm đồng ý.
Trang này tập trung vào các trách nhiệm liên quan đến việc triển khai
AppWidgetHost
. Để xem ví dụ cụ thể về cách triển khai AppWidgetHost
,
xem mã nguồn của màn hình chính của Android
LauncherAppWidgetHost
.
Dưới đây là thông tin tổng quan về các lớp chính và khái niệm liên quan đến việc triển khai một
AppWidgetHost
tuỳ chỉnh:
Máy chủ tiện ích ứng dụng:
AppWidgetHost
cung cấp hoạt động tương tác với Dịch vụ AppWidget dành cho các ứng dụng nhúng tiện ích vào giao diện người dùng.AppWidgetHost
phải có mã nhận dạng duy nhất trong gói riêng của máy chủ. Mã này vẫn tồn tại cho mọi hoạt động sử dụng máy chủ lưu trữ. ID thường là giá trị được cố định giá trị trong mã mà bạn gán trong ứng dụng của bạn.Mã tiện ích ứng dụng: mỗi phiên bản tiện ích được chỉ định một mã nhận dạng duy nhất tại một thời điểm liên kết. Xem
bindAppWidgetIdIfAllowed()
và để biết thêm chi tiết là phần Liên kết tiện ích ngay sau đó. Chiến lược phát hành đĩa đơn máy chủ lưu trữ lấy ID duy nhất bằng cách sử dụngallocateAppWidgetId()
. Mã này sẽ tồn tại trong suốt thời gian hoạt động của tiện ích cho đến khi bị xoá khỏi máy chủ lưu trữ. Bất kỳ trạng thái cụ thể nào của máy chủ lưu trữ, chẳng hạn như kích thước và vị trí của tiện ích con—phải được gói lưu trữ duy trì và được liên kết với mã tiện ích ứng dụng.Chế độ xem máy chủ tiện ích ứng dụng: hãy nghĩ đến
AppWidgetHostView
làm khung để tiện ích được bao bọc bất cứ khi nào cần hiển thị. Một tiện ích là được liên kết vớiAppWidgetHostView
mỗi khi tiện ích này được tăng cường bởi máy chủ lưu trữ.- Theo mặc định, hệ thống sẽ tạo một
AppWidgetHostView
, nhưng máy chủ lưu trữ có thể tạo lớp conAppWidgetHostView
riêng bằng cách mở rộng lớp đó. - Kể từ Android 12 (API cấp 31),
AppWidgetHostView
sẽ ra mắt thời giansetColorResources()
vàresetColorResources()
để xử lý màu bị nạp chồng động. Máy chủ lưu trữ là chịu trách nhiệm cung cấp màu cho các phương thức này.
- Theo mặc định, hệ thống sẽ tạo một
Gói tuỳ chọn:
AppWidgetHost
dùng gói tuỳ chọn để trao đổi thông tin đếnAppWidgetProvider
về cách tiện ích này hiển thị (ví dụ: danh sách khoảng kích thước—và liệu các nằm trên màn hình khoá hoặc màn hình chính. Thông tin này cho phépAppWidgetProvider
điều chỉnh nội dung và giao diện của tiện ích dựa trên cách thức và nơi hiển thị. Bạn có thể sử dụngupdateAppWidgetOptions()
vàupdateAppWidgetSize()
để sửa đổi gói tiện ích. Cả hai phương pháp này đều kích hoạtonAppWidgetOptionsChanged()
lệnh gọi lại đếnAppWidgetProvider
.
Liên kết tiện ích
Khi người dùng thêm một tiện ích vào máy chủ lưu trữ, một quy trình có tên là liên kết sẽ xảy ra. Ràng buộc
đề cập đến việc liên kết một mã tiện ích ứng dụng cụ thể với một máy chủ lưu trữ cụ thể và một
AppWidgetProvider
cụ thể.
API liên kết cũng giúp máy chủ lưu trữ cung cấp giao diện người dùng tuỳ chỉnh cho
ràng buộc. Để sử dụng quy trình này, ứng dụng của bạn phải khai báo
BIND_APPWIDGET
quyền trong tệp kê khai của máy chủ lưu trữ:
<uses-permission android:name="android.permission.BIND_APPWIDGET" />
Nhưng đây mới chỉ là bước đầu tiên. Trong thời gian chạy, người dùng phải cấp quyền rõ ràng
quyền truy cập vào ứng dụng của bạn để cho phép ứng dụng thêm tiện ích vào máy chủ lưu trữ. Để kiểm tra xem
ứng dụng có quyền thêm tiện ích, hãy sử dụng
bindAppWidgetIdIfAllowed()
. Nếu bindAppWidgetIdIfAllowed()
trả về false
, ứng dụng của bạn phải hiển thị một
hộp thoại nhắc người dùng cấp quyền: "cho phép" cho tiện ích hiện tại
thêm hoặc "luôn cho phép" để bao gồm mọi tiện ích bổ sung trong tương lai.
Đoạn mã sau đây cung cấp ví dụ về cách hiển thị hộp thoại:
Kotlin
val intent = Intent(AppWidgetManager.ACTION_APPWIDGET_BIND).apply { putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId) putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName) // This is the options bundle described in the preceding section. putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options) } startActivityForResult(intent, REQUEST_BIND_APPWIDGET)
Java
Intent intent = new Intent(AppWidgetManager.ACTION_APPWIDGET_BIND); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId); intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_PROVIDER, info.componentName); // This is the options bundle described in the preceding section. intent.putExtra(AppWidgetManager.EXTRA_APPWIDGET_OPTIONS, options); startActivityForResult(intent, REQUEST_BIND_APPWIDGET);
Máy chủ lưu trữ phải kiểm tra xem tiện ích mà người dùng thêm có cần cấu hình hay không. Cho để biết thêm thông tin, hãy xem Cho phép người dùng định cấu hình ứng dụng các tiện ích.
Trách nhiệm của người tổ chức
Bạn có thể chỉ định một số cài đặt cấu hình cho tiện ích bằng cách sử dụng
Siêu dữ liệu AppWidgetProviderInfo
.
Bạn có thể truy xuất các tuỳ chọn cấu hình này, được đề cập chi tiết hơn trong
các phần sau, từ phần
AppWidgetProviderInfo
đối tượng liên kết với nhà cung cấp tiện ích.
Bất kể bạn đang nhắm đến phiên bản Android nào, tất cả máy chủ lưu trữ đều có những trách nhiệm sau:
Khi thêm tiện ích, hãy phân bổ ID tiện ích như được mô tả trước đó. Khi một tiện ích đã bị xoá khỏi máy chủ, hãy gọi
deleteAppWidgetId()
để phân bổ ID tiện ích.Khi thêm tiện ích, hãy kiểm tra xem hoạt động định cấu hình có cần được đã phát hành. Thông thường, máy chủ lưu trữ cần khởi chạy cấu hình của tiện ích nếu hoạt động đó tồn tại và không được đánh dấu là không bắt buộc bằng cách chỉ định cả Cờ
configuration_optional
vàreconfigurable
. Xem Cập nhật tiện ích trong hoạt động định cấu hình để biết thông tin chi tiết. Đây là bước cần thiết cho nhiều tiện ích trước khi chúng có thể hiển thị.Các tiện ích sẽ chỉ định chiều rộng và chiều cao mặc định trong
AppWidgetProviderInfo
siêu dữ liệu. Các giá trị này được xác định trong các ô — bắt đầu từ Android 12, nếutargetCellWidth
vàtargetCellHeight
là được chỉ định, hoặc dps nếu chỉminWidth
vàminHeight
được chỉ định. Xem Thuộc tính đặt kích thước tiện ích.Đảm bảo tiện ích được bố trí có dp tối thiểu là này. Cho ví dụ: nhiều máy chủ căn chỉnh biểu tượng và tiện ích trong một lưới. Trong trường hợp này, bằng cách Theo mặc định, máy chủ lưu trữ sẽ thêm tiện ích bằng cách sử dụng số lượng ô tối thiểu đáp ứng các điều kiện ràng buộc
minWidth
vàminHeight
.
Ngoài các yêu cầu được liệt kê trong phần trước, việc đáp ứng các yêu cầu cụ thể các phiên bản nền tảng giới thiệu các tính năng đặt ra những trách nhiệm mới trên máy chủ lưu trữ.
Xác định phương pháp tiếp cận của bạn dựa trên phiên bản Android được nhắm đến
Android 12
Android 12 (API cấp 31) gói thêm một List<SizeF>
có chứa danh sách
kích thước có thể dùng tính theo dps mà một thực thể tiện ích có thể nhận được trong gói tuỳ chọn.
Số lượng kích thước được cung cấp tuỳ thuộc vào cách triển khai máy chủ lưu trữ. Người tổ chức thường có
cung cấp hai kích thước cho điện thoại là dọc và ngang và 4 kích thước
cho thiết bị có thể gập lại.
Có giới hạn là MAX_INIT_VIEW_COUNT
(16) cho số lượng khác nhau
RemoteViews
mà AppWidgetProvider
có thể cung cấp
RemoteViews
.
Do các đối tượng AppWidgetProvider
ánh xạ một đối tượng RemoteViews
với từng kích thước trong
List<SizeF>
, không cung cấp nhiều hơn MAX_INIT_VIEW_COUNT
kích thước.
Android 12 cũng ra mắt
maxResizeWidth
và
maxResizeHeight
tính theo dps. Bạn nên sử dụng tiện ích sử dụng ít nhất một trong
thuộc tính không vượt quá kích thước do thuộc tính chỉ định.
Tài nguyên khác
- Hãy xem tài liệu tham khảo về
Glance
.