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

Tiện ích ứng dụng có thể được định cấu hình. 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 tiện ích định cấu hình Activity. Hoạt động này sẽ tự động được máy chủ tiện ích ứng dụng chạy khi tiện ích được tạo hoặc sau đó, tuỳ thuộc vào các lựa chọn định 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 bình thường trong tệp kê khai Android. Máy chủ tiện ích ứng dụng chạy hoạt động 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 định 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 định 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 định cấu hình

Bạn cần nhớ 2 điểm quan trọng khi triển khai hoạt động này:

  • Máy chủ tiện ích ứng dụng gọi hoạt động định cấu hình và hoạt động định cấu hình phải luôn trả về kết quả. Kết quả phải bao gồm Mã tiện ích ứng dụng ID do ý định chạy hoạt động chuyển qua – được lưu trong các 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 định cấu hình được chạy, tức là hệ thống không gọi phương thức onUpdate() khi tiện ích được tạo. Hoạt động định cấu hình có trách nhiệm yêu cầu cập nhật từ AppWidgetManager khi tạo tiện ích lần đầu tiên. Tuy nhiên, onUpdate() được gọi cho các lần cập nhật tiếp theo – chỉ bỏ qua lần đầu tiên.

Hãy xem các đoạn mã trong phần sau đây để 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.

Cập nhật tiện ích từ hoạt động định 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 yêu cầu cập nhật trực tiếp từ AppWidgetManager.

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

  1. Lấy Mã tiện ích ứng dụng từ ý định chạy hoạt động:

    Kotlin

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

    Java

    Intent intent = getIntent();
Bundle extras = intent.getExtras();
int appWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
if (extras != null) {
    appWidgetId = extras.getInt(
            AppWidgetManager.EXTRA_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 máy chủ tiện ích ứng dụng rằng quá trình định cấu hình đã bị huỷ và máy chủ không thêm tiện ích:

    Kotlin

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

    Java

    int resultValue = new 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.

  4. Khi quá trình định cấu hình hoàn tất, hãy lấy một thực thể của AppWidgetManager bằng cách gọi getInstance(Context):

    Kotlin

    val appWidgetManager = AppWidgetManager.getInstance(context)

    Java

    AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);

  5. Cập nhật tiện ích bằng bố cục RemoteViews bằng cách gọi updateAppWidget(int,RemoteViews):

    Kotlin

    val views = RemoteViews(context.packageName, R.layout.example_appwidget)
appWidgetManager.updateAppWidget(appWidgetId, views)

    Java

    RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.example_appwidget);
appWidgetManager.updateAppWidget(appWidgetId, views);

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

    Kotlin

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

    Java

    Intent resultValue = new Intent().putExtra(AppWidgetManager.EXTRA_APPWIDGET_ID, appWidgetId);
setResult(RESULT_OK, resultValue);
finish();

Hãy xem lớp mẫu trên GitHub để biết ví dụ.ListWidgetConfigureActivity.kt

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

Theo mặc định, máy chủ tiện ích ứng dụng 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 quá trình định 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. Hãy xem hướng dẫn khai báo tệp AppWidgetProviderInfo.xml để biết thêm thông tin. 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 chạm và giữ tiện ích, sau đó nhấn vào nút Định cấu hình lại (được gắn nhãn 1 trong hình 1).

Nút xuất hiện ở góc dưới cùng bên phải
Hình 1. Nút Định cấu hình lại tiện ích.

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 tiện ích liền mạch hơn bằng cách cho phép người dùng bỏ qua bước định cấu hình ban đầu. Để thực hiện 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 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 đó, người dùng vẫn có thể định cấu hình lại tiện ích sau đó. Ví dụ: tiện ích đồng hồ có thể bỏ qua quá trình định 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>