Bạn có thể định cấu hình các tiện ích ứng dụng. Ví dụ: tiện ích đồng hồ có thể cho phép người dùng định cấu hình múi giờ để hiển thị.
Nếu bạn muốn cho phép người dùng định cấu hình các chế độ cài đặt của tiện ích, hãy tạo một tiện ích
cấu hình Activity
. Hoạt động này
được máy chủ tiện ích ứng dụng khởi chạy tự động khi tiện ích được tạo
trở lên, tuỳ thuộc vào tuỳ 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 cấu hình như một hoạt động bình thường trong tệp kê khai Android
. Máy chủ tiện ích ứng dụng khởi chạy ứng dụng bằng
ACTION_APPWIDGET_CONFIGURE
nên hoạt động 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 phần tử
Thuộc tính android:configure
. Xem thêm thông tin về
khai báo tệp này. Sau đâ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 được khai báo bằng không gian tên đủ điều kiện vì trình chạy tham chiếu tệp đó 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 cấu hình
Có 2 điểm quan trọng cần nhớ khi bạn triển khai hoạt động:
- Máy chủ tiện ích ứng dụng gọi hoạt động định cấu hình và cấu hình
phải luôn trả về một kết quả. Kết quả phải bao gồm Tiện ích ứng dụng
Mã nhận dạng được truyền bởi ý định chạy hoạt động (được lưu trong ý định)
phần bổ sung dưới dạng
EXTRA_APPWIDGET_ID
. - Hệ thống sẽ không gửi
ACTION_APPWIDGET_UPDATE
truyền tin khi một hoạt động cấu hình được chạy, có nghĩa là hoạt động này sẽ không gọi phương thứconUpdate()
khi tạo tiện ích. 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 — lệnh này chỉ bị bỏ qua lần đầu tiên.
Hãy xem các đoạn mã trong phần sau để biết ví dụ về cách trả về một kết quả từ cấu hình và cập nhật tiện ích.
Cập nhật tiện ích trong hoạt động định cấu hình
Khi một tiện ích sử dụng hoạt động cấu hình, bạn có trách nhiệm
hoạt động để cập nhật tiện ích khi quá trình định cấu hình hoàn tất. Bạn có thể làm như vậy
bằng cách yêu cầu cập nhật trực tiếp từ
AppWidgetManager
.
Sau đây là phần tóm tắt về quy trình để cập nhật tiện ích đúng cách và đóng hoạt động định cấu hình:
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); }
Đặt kết quả hoạt động thành
RESULT_CANCELED
.Bằng cách này, nếu người dùng quay lại hoạt động trước khi đến cuối trang, hệ thống thông báo cho máy chủ tiện ích ứng dụng rằng cấu hình đã bị huỷ và máy chủ lưu trữ 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);
Định cấu hình tiện ích theo các lựa chọn ưu tiên của người dùng.
Khi quá trình định cấu hình hoàn tất, hãy lấy một phiên bản của
AppWidgetManager
bằng cách gọigetInstance(Context)
:Kotlin
val appWidgetManager = AppWidgetManager.getInstance(context)
Java
AppWidgetManager appWidgetManager = AppWidgetManager.getInstance(context);
Cập nhật tiện ích bằng một Bố cục
RemoteViews
bằng cách gọiupdateAppWidget(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);
Tạo ý định trả về, đặt ý định này cùng với kết quả hoạt động và hoàn tất hoạt động này:
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();
Xem
ListWidgetConfigureActivity.kt
lớp mẫu trên GitHub để làm ví dụ.
Tuỳ chọn 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 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 tuỳ 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 một 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 được đặ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
reconfigurable
gắn cờ trong
widgetFeatures
của appwidget-provider
. Hãy xem hướng dẫn để khai báo
AppWidgetProviderInfo.xml
tệp để xem thêm
của bạn. 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 của mình bằng cách chạm & giữ tiện ích rồi nhấn nút Định cấu hình lại, nút này đượ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 lại 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ả hai
configuration_optional
và reconfigurable
trong trường widgetFeatures
. Chế độ này bỏ qua
khởi chạy hoạt động 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 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 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>