Cho phép người dùng định cấu hình tiện ích ứng dụng

Thiết kế tiện ích sao cho người dùng có thể định cấu hình các đặc điểm cụ thể. Ví dụ: tiện ích đồng hồ có thể cho phép người dùng định cấu hình múi giờ cần hiển thị.

Nếu bạn muốn cho phép người dùng định cấu hình chế độ cài đặt của tiện ích, hãy tạo một cấu hình tiện ích Activity. Hoạt động này được máy chủ lưu trữ tiện ích ứng dụng tự động khởi chạy khi tiện ích được tạo hoặc sau đó, tuỳ thuộc vào các lựa chọn cấu hình mà bạn chỉ định.

Khai báo hoạt động định cấu hình

Khai báo hoạt động định cấu hình dưới dạng một hoạt động thông thường trong tệp kê khai Android. Ứng dụng lưu trữ tiện ích ứng dụng sẽ khởi chạy tiện ích này bằng thao tác ACTION_APPWIDGET_CONFIGURE, vì vậy, hoạt động này cần chấp nhận ý định này. Ví dụ:

<activity android:name=".ExampleAppWidgetConfigurationActivity">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
    </intent-filter>
</activity>

Khai báo hoạt động trong tệp AppWidgetProviderInfo.xml bằng thuộc tính android:configure. Xem thêm thông tin về cách khai báo tệp này. Dưới đây là ví dụ về cách khai báo hoạt động cấu hình:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    ... >
</appwidget-provider>

Hoạt động này được khai báo bằng một không gian tên đủ điều kiện, vì trình chạy tham chiếu hoạt động này từ bên ngoài phạm vi gói của bạn.

Đó là tất cả những gì bạn cần để bắt đầu một hoạt động cấu hình. Tiếp theo, bạn cần triển khai hoạt động thực tế.

Triển khai hoạt động cấu hình

Có hai điểm quan trọng cần nhớ khi bạn triển khai hoạt động này:

• Máy chủ lưu trữ tiện ích ứng dụng gọi hoạt động cấu hình và hoạt động cấu hình phải luôn trả về một kết quả. Kết quả phải bao gồm mã nhận dạng Tiện ích ứng dụng do ý định chạy hoạt động truyền vào được lưu trong phần bổ sung của ý định dưới dạng EXTRA_APPWIDGET_ID.
  • Hệ thống không gửi thông báo truyền tin ACTION_APPWIDGET_UPDATE khi một hoạt động cấu hình được khởi chạy, tức là hệ thống không gọi các bản cập nhật tiện ích của bạn ban đầu khi tiện ích được tạo. Hoạt động liên quan đến cấu hình có trách nhiệm yêu cầu cập nhật từ GlanceAppWidget khi tạo tiện ích lần đầu tiên. Tuy nhiên, các bản cập nhật sẽ tự động được kích hoạt cho các chu kỳ tiếp theo.

Hãy xem các đoạn mã trong phần sau để biết ví dụ về cách trả về kết quả từ cấu hình và cập nhật tiện ích Glance.

Cập nhật tiện ích từ hoạt động cấu hình

Khi một tiện ích sử dụng hoạt động định cấu hình, hoạt động đó có trách nhiệm cập nhật tiện ích khi quá trình định cấu hình hoàn tất. Bạn có thể thực hiện việc này bằng cách kích hoạt bản cập nhật theo cách thủ công ngay từ phiên bản GlanceAppWidget.

Dưới đây là nội dung tóm tắt quy trình cập nhật tiện ích đúng cách và đóng hoạt động định cấu hình:

1. Nhận mã nhận dạng Tiện ích ứng dụng từ ý định chạy hoạt động:

   val appWidgetId = intent?.extras?.getInt(
           AppWidgetManager.EXTRA_APPWIDGET_ID,
           AppWidgetManager.INVALID_APPWIDGET_ID
   ) ?: AppWidgetManager.INVALID_APPWIDGET_ID
   

2. Đặt kết quả hoạt động thành RESULT_CANCELED.

   Bằng cách này, nếu người dùng thoát khỏi hoạt động trước khi kết thúc, hệ thống sẽ thông báo cho ứng dụng lưu trữ tiện ích rằng cấu hình đã bị huỷ và máy chủ lưu trữ không thêm tiện ích:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_CANCELED, resultValue)
   

3. Định cấu hình tiện ích theo lựa chọn ưu tiên của người dùng, chẳng hạn như ghi các lựa chọn vào DataStore ổn định hoặc cơ sở dữ liệu cục bộ.

4. Khi quá trình định cấu hình hoàn tất, hãy truy xuất GlanceId tương ứng với mã nhận dạng tiện ích nền tảng:

   val glanceAppWidgetManager = GlanceAppWidgetManager(context)
   val glanceId = glanceAppWidgetManager.getGlanceIdBy(appWidgetId)
   

5. Cập nhật nội dung tiện ích bằng cách gọi hàm tạm ngưng update trên phiên bản GlanceAppWidget:

   // Update the GlanceAppWidget directly
   ExampleGlanceWidget().update(context, glanceId)
   

6. Tạo ý định trả về, đặt ý định đó bằng kết quả hoạt động và hoàn tất hoạt động:

   val resultValue = Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId)
   setResult(Activity.RESULT_OK, resultValue)
   finish()
   

Các lựa chọn về cấu hình tiện ích

Theo mặc định, ứng dụng lưu trữ tiện ích chỉ chạy hoạt động định cấu hình một lần, ngay sau khi người dùng thêm tiện ích vào màn hình chính. Tuy nhiên, bạn có thể chỉ định các lựa chọn cho phép người dùng định cấu hình lại các tiện ích hiện có hoặc bỏ qua cấu hình tiện ích ban đầu bằng cách cung cấp cấu hình tiện ích mặc định.

Cho phép người dùng định cấu hình lại các tiện ích đã đặt

Để cho phép người dùng định cấu hình lại các tiện ích hiện có, hãy chỉ định cờ reconfigurable trong thuộc tính widgetFeatures của appwidget-provider. Ví dụ:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable">
</appwidget-provider>

Người dùng có thể định cấu hình lại tiện ích bằng cách nhấn và giữ tiện ích rồi nhấn vào nút Định cấu hình lại (được gắn nhãn 1 trong hình 1).

Sử dụng cấu hình mặc định của tiện ích

Bạn có thể mang đến trải nghiệm liền mạch hơn cho tiện ích bằng cách cho phép người dùng bỏ qua bước định cấu hình ban đầu. Để làm việc này, hãy chỉ định cả cờ configuration_optional và reconfigurable trong trường widgetFeatures. Thao tác này sẽ bỏ qua việc khởi chạy hoạt động định cấu hình sau khi người dùng thêm tiện ích. Như đã đề cập trước đó, sau đó người dùng vẫn có thể định cấu hình lại tiện ích. Ví dụ: một tiện ích đồng hồ có thể bỏ qua cấu hình ban đầu và hiển thị múi giờ của thiết bị theo mặc định.

Dưới đây là ví dụ về cách đánh dấu hoạt động định cấu hình của bạn là có thể định cấu hình lại và không bắt buộc:

<appwidget-provider
    android:configure="com.myapp.ExampleAppWidgetConfigurationActivity"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>