Xây dựng máy chủ tiện ích

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 một AppWidgetHost tuỳ chỉnh. Để biết ví dụ cụ thể về cách triển khai AppWidgetHost, hãy xem mã nguồn cho 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 cho các ứng dụng nhúng tiện ích trong giao diện người dùng. AppWidgetHost phải có mã nhận dạng duy nhất trong gói của máy chủ lưu trữ. Mã này vẫn tồn tại cho mọi hoạt động sử dụng máy chủ lưu trữ. Mã nhận dạng thường là một giá trị được mã hoá cứng mà bạn chỉ định trong ứng dụng.

• Mã tiện ích ứng dụng: mỗi thực thể tiện ích được chỉ định một mã nhận dạng duy nhất tại 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ụng allocateAppWidgetId(). Mã nhận dạng 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.

• Khung hiển thị lưu trữ tiện ích ứng dụng: hãy coi AppWidgetHostView là một khung mà tiện ích được gói trong đó mỗi khi cần hiển thị. Một tiện ích được liên kết với AppWidgetHostView mỗi khi tiện ích được máy chủ tăng cường.

  • 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 con AppWidgetHostView 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 gian setColorResources() và resetColorResources() để xử lý màu bị nạp chồng động. Máy chủ lưu trữ chịu trách nhiệm cung cấp màu sắc cho các phương thức này.

• Gói tuỳ chọn: AppWidgetHost sử dụng gói tuỳ chọn để truyền thông tin đến AppWidgetProvider về cách hiển thị tiện ích (ví dụ: danh sách các dải kích thước) và liệu tiện ích có nằm trên màn hình khoá hay màn hình chính hay không. Thông tin này cho phép AppWidgetProvider đ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ụng updateAppWidgetOptions() và updateAppWidgetSize() để sửa đổi gói tiện ích. Cả hai phương thức này đều kích hoạt lệnh gọi lại onAppWidgetOptionsChanged() đến AppWidgetProvider.

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. Liên kết (binding) đề cập đến việc liên kết một mã nhận dạng tiện ích ứng dụng cụ thể với một máy chủ 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ị hộp thoại nhắc người dùng cấp quyền: "cho phép" để thêm tiện ích hiện tại hoặc "luôn cho phép" để áp dụng cho tất cả các tiện ích được thêm trong tương lai.

Đoạn mã này đưa ra ví dụ về cách hiển thị hộp thoại:

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)

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. Để biết thêm thông tin, hãy xem phần Cho phép người dùng định cấu hình tiện ích ứng dụng.

Trách nhiệm của máy chủ lưu trữ

Bạn có thể chỉ định một số chế độ 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ừ đối tượng AppWidgetProviderInfo liên kết với một trì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ổ mã nhận dạng tiện ích như mô tả ở trên. Khi một tiện ích bị xoá khỏi máy chủ, hãy gọi deleteAppWidgetId() để giải phóng mã nhận dạng 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 đối với nhiều tiện ích trước khi chúng có thể hiển thị.

• Tiện ích chỉ định chiều rộng và chiều cao mặc định trong siêu dữ liệu AppWidgetProviderInfo. Các giá trị này được xác định trong các ô — bắt đầu từ Android 12, nếu targetCellWidth 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. Ví dụ: nhiều máy chủ lưu trữ căn chỉnh các biểu tượng và tiện ích trong một lưới. Trong trường hợp này, theo mặc định, máy chủ lưu trữ sẽ thêm một tiện ích bằng cách sử dụng số lượng ô tối thiểu đáp ứng các quy tắc 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 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 dựa trên phiên bản Android được nhắm đến

Android 12

Android 12 (API cấp 31) thêm một List<SizeF> chứa danh sách các kích thước có thể có theo dps mà một thực thể tiện ích có thể lấy 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ữ. Máy chủ lưu trữ thường cung cấp hai kích thước cho điện thoại (dọc và ngang) và bốn 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 giới thiệu các thuộc tính maxResizeWidth và maxResizeHeight theo dps. Bạn nên sử dụng một tiện ích sử dụng ít nhất một trong các thuộc tính này và không vượt quá kích thước do các thuộc tính chỉ định.

Tài nguyên khác

• Hãy xem tài liệu tham khảo về Glance.