Tạo tiện ích ứng dụng bằng tính năng Xem nhanh

Các phần sau đây mô tả cách tạo tiện ích cơ bản cho ứng dụng bằng Glance.

Khai báo AppWidget trong tệp kê khai

Sau khi hoàn tất các bước thiết lập, hãy khai báo AppWidget và siêu dữ liệu của tiện ích đó trong ứng dụng của bạn.

1. Mở rộng trình nhận AppWidget từ GlanceAppWidgetReceiver:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
       override val glanceAppWidget: GlanceAppWidget = TODO("Create GlanceAppWidget")
   }
   GlanceSnippets.kt

2. Đăng ký nhà cung cấp tiện ích cho ứng dụng trong tệp AndroidManifest.xml và tệp siêu dữ liệu được liên kết:

       <receiver android:name=".glance.MyReceiver"
       android:exported="true">
       <intent-filter>
           <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
       </intent-filter>
       <meta-data
           android:name="android.appwidget.provider"
           android:resource="@xml/my_app_widget_info" />
   </receiver>
   AndroidManifest.xml
   

Thêm siêu dữ liệu AppWidgetProviderInfo

Tiếp theo, hãy làm theo hướng dẫn Tạo tiện ích để tạo và xác định thông tin về tiện ích cho ứng dụng trong tệp @xml/my_app_widget_info.

Điểm khác biệt duy nhất đối với Glance là không có XML initialLayout, nhưng bạn phải xác định một XML. Bạn có thể sử dụng bố cục tải được xác định trước có trong thư viện:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout">
</appwidget-provider>
my_app_widget_info.xml

Khai báo XML AppWidgetProviderInfo

Đối tượng AppWidgetProviderInfo xác định các đặc điểm thiết yếu của tiện ích. Xác định AppWidgetProviderInfo trong tệp tài nguyên siêu dữ liệu XML (res/xml/my_app_widget_info.xml) bên trong phần tử <appwidget-provider>:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:maxResizeWidth="250dp"
    android:maxResizeHeight="120dp"
    android:updatePeriodMillis="86400000"
    android:description="@string/example_appwidget_description"
    android:previewLayout="@layout/example_appwidget_preview"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:configure="com.example.android.ExampleAppWidgetConfigurationActivity"
    android:resizeMode="horizontal|vertical"
    android:widgetCategory="home_screen"
    android:widgetFeatures="reconfigurable|configuration_optional">
</appwidget-provider>

Thuộc tính kích thước tiện ích

Theo mặc định, màn hình chính sẽ đặt các tiện ích vào cửa sổ dựa trên một lưới ô có chiều cao và chiều rộng đã xác định. Hầu hết màn hình chính chỉ cho phép các tiện ích có kích thước là bội số nguyên của các ô trong lưới, ví dụ: 2 ô theo chiều ngang và 3 ô theo chiều dọc.

Các thuộc tính kích thước tiện ích cho phép bạn chỉ định kích thước mặc định cho tiện ích và cung cấp các giới hạn dưới và trên về kích thước của tiện ích. Trong bối cảnh này, kích thước mặc định của một tiện ích là kích thước mà tiện ích đó có khi được thêm vào màn hình chính lần đầu tiên.

Bảng sau đây mô tả các thuộc tính <appwidget-provider> liên quan đến kích thước tiện ích:

Ví dụ

Để minh hoạ cách các thuộc tính trong bảng trước ảnh hưởng đến kích thước tiện ích, hãy giả sử các thông số kỹ thuật sau:

• Một ô trong lưới có chiều rộng 30 dp và chiều cao 50 dp.
• Thông số kỹ thuật sau đây về thuộc tính được cung cấp:

<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:minWidth="80dp"
    android:minHeight="80dp"
    android:targetCellWidth="2"
    android:targetCellHeight="2"
    android:minResizeWidth="40dp"
    android:minResizeHeight="40dp"
    android:maxResizeWidth="120dp"
    android:maxResizeHeight="120dp"
    android:resizeMode="horizontal|vertical" />

Bắt đầu từ Android 12:

Sử dụng các thuộc tính targetCellWidth và targetCellHeight làm kích thước mặc định của tiện ích.

Theo mặc định, kích thước của tiện ích là 2x2. Bạn có thể đổi kích thước tiện ích xuống còn 2x1 hoặc lên đến 4x3.

Android 11 trở xuống:

Sử dụng các thuộc tính minWidth và minHeight để tính toán kích thước mặc định của tiện ích.

Chiều rộng mặc định = Math.ceil(80 / 30) = 3

Chiều cao mặc định = Math.ceil(80 / 50) = 2

Theo mặc định, kích thước của tiện ích là 3x2. Bạn có thể đổi kích thước tiện ích xuống còn 2x1 hoặc lên đến toàn màn hình.

Thuộc tính bổ sung của tiện ích

Bảng sau đây mô tả các thuộc tính <appwidget-provider> liên quan đến các đặc điểm khác ngoài kích thước tiện ích.

Xác định GlanceAppWidget

1. Tạo một lớp mới mở rộng từ GlanceAppWidget và ghi đè phương thức provideGlance. Đây là phương thức mà bạn có thể tải dữ liệu cần thiết để kết xuất tiện ích:

   class MyAppWidget : GlanceAppWidget() {
   
       override suspend fun provideGlance(context: Context, id: GlanceId) {
   
           // In this method, load data needed to render the AppWidget.
           // Use `withContext` to switch to another thread for long running
           // operations.
   
           provideContent {
               // create your AppWidget here
               Text("Hello World")
           }
       }
   }
   GlanceSnippets.kt

2. Tạo thực thể trong glanceAppWidget trên GlanceAppWidgetReceiver:

   class MyAppWidgetReceiver : GlanceAppWidgetReceiver() {
   
       // Let MyAppWidgetReceiver know which GlanceAppWidget to use
       override val glanceAppWidget: GlanceAppWidget = MyAppWidget()
   }
   GlanceSnippets.kt

Bây giờ, bạn đã định cấu hình AppWidget bằng Glance.

Sử dụng lớp GlanceAppWidgetReceiver để xử lý các lượt truyền tin của tiện ích

GlanceAppWidgetReceiver điều phối các lượt truyền tin của tiện ích và các bản cập nhật trạng thái nền tảng bằng cách mở rộng AppWidgetProvider cơ bản. Lớp này nhận các sự kiện nền tảng khi tiện ích của bạn được cập nhật, xoá, bật hoặc tắt, chuyển các sự kiện đó thành các yêu cầu về vòng đời của Compose.

Khai báo tiện ích trong tệp kê khai

Khai báo lớp con GlanceAppWidgetReceiver làm một bộ nhận tín hiệu truyền tin trong tệp AndroidManifest.xml:

<receiver android:name="ExampleAppWidgetReceiver"
          android:exported="false">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
               android:resource="@xml/my_app_widget_info" />
</receiver>

Phần tử <receiver> yêu cầu thuộc tính android:name, thuộc tính này chỉ định lớp receiver. Receiver phải chấp nhận hành động truyền tin ACTION_APPWIDGET_UPDATE bên trong <intent-filter>.

Phần tử <meta-data> phải xác định tên của phần tử đó là android.appwidget.provider và thuộc tính android:resource phải trỏ đến tài nguyên siêu dữ liệu XML AppWidgetProviderInfo của bạn (@xml/my_app_widget_info).

Triển khai lớp GlanceAppWidgetReceiver

Trong Glance, bạn sẽ mở rộng GlanceAppWidgetReceiver thay vì AppWidgetProvider trực tiếp. Triển khai bằng cách liên kết receiver với thực thể GlanceAppWidget. Các lệnh gọi lại chính có trong GlanceAppWidgetReceiver hoạt động như sau:

• onUpdate(): Tự động bị Glance ghi đè để thực thi các bản cập nhật thành phần. Nếu bạn ghi đè onUpdate theo cách thủ công, bạn phải gọi super.onUpdate để cho phép Glance chạy các luồng thành phần thành công.
• onAppWidgetOptionsChanged(): Được gọi khi tiện ích được đặt hoặc đổi kích thước lần đầu tiên. Glance đọc các mục trong gói tuỳ chọn ở chế độ nền để bố cục của bạn điều chỉnh liền mạch dựa trên kích thước thời gian chạy.
• onDeleted(Context, IntArray): Được gọi bất cứ khi nào người dùng xoá một thực thể tiện ích cụ thể.
• onEnabled(Context): Được kích hoạt khi thực thể đầu tiên của tiện ích được tạo thành công. Tuyệt vời để chạy các hoạt động di chuyển toàn cầu.
• onDisabled(Context): Được gọi khi thực thể hoạt động cuối cùng của nhà cung cấp bị xoá.
• onReceive(Context, Intent): Chặn mọi lượt truyền tin của nền tảng trước các phương thức gọi lại cụ thể. Bạn phải đảm bảo rằng mọi logic receiver tuỳ chỉnh mà bạn viết đều gọi super.onReceive(context, intent) và không bao giờ được gọi goAsync vì Glance tự động định tuyến công việc một cách không đồng bộ.

Nhận ý định truyền tin của tiện ích

Ở chế độ nền, GlanceAppWidgetReceiver sẽ lọc và xử lý các ý định truyền tin cơ bản sau đây của tiện ích nền tảng:

• ACTION_APPWIDGET_UPDATE
• ACTION_APPWIDGET_DELETED
• ACTION_APPWIDGET_ENABLED
• ACTION_APPWIDGET_DISABLED
• ACTION_APPWIDGET_OPTIONS_CHANGED

Tạo giao diện người dùng

Đoạn mã sau đây minh hoạ cách tạo giao diện người dùng:

/* Import Glance Composables
 In the event there is a name clash with the Compose classes of the same name,
 you may rename the imports per https://kotlinlang.org/docs/packages.html#imports
 using the `as` keyword.

import androidx.glance.Button
import androidx.glance.layout.Column
import androidx.glance.layout.Row
import androidx.glance.text.Text
*/
class MyAppWidget : GlanceAppWidget() {

    override suspend fun provideGlance(context: Context, id: GlanceId) {
        // Load data needed to render the AppWidget.
        // Use `withContext` to switch to another thread for long running
        // operations.

        provideContent {
            // create your AppWidget here
            MyContent()
        }
    }

    @Composable
    private fun MyContent() {
        Column(
            modifier = GlanceModifier.fillMaxSize(),
            verticalAlignment = Alignment.Top,
            horizontalAlignment = Alignment.CenterHorizontally
        ) {
            Text(text = "Where to?", modifier = GlanceModifier.padding(12.dp))
            Row(horizontalAlignment = Alignment.CenterHorizontally) {
                Button(
                    text = "Home",
                    onClick = actionStartActivity<MyActivity>()
                )
                Button(
                    text = "Work",
                    onClick = actionStartActivity<MyActivity>()
                )
            }
        }
    }
}
GlanceSnippets.kt

Mã mẫu trước đó thực hiện những việc sau:

• Ở cấp cao nhất Column, các mục được đặt theo chiều dọc lần lượt.
• Column mở rộng kích thước để khớp với không gian có sẵn (thông qua GlanceModifier và căn chỉnh nội dung của cột đó lên trên (verticalAlignment) và căn giữa theo chiều ngang (horizontalAlignment).
• Nội dung của Column được xác định bằng cách sử dụng lambda. Thứ tự rất quan trọng.
  • Mục đầu tiên trong Column là thành phần Text có phần đệm 12.dp.
  • Mục thứ hai là Row, trong đó các mục được đặt theo chiều ngang lần lượt, với 2 Buttons được căn giữa theo chiều ngang (horizontalAlignment). Màn hình cuối cùng phụ thuộc vào không gian có sẵn. Hình ảnh sau đây là ví dụ về giao diện có thể có:

Bạn có thể thay đổi các giá trị căn chỉnh hoặc áp dụng các giá trị đối tượng sửa đổi khác nhau (chẳng hạn như phần đệm) để thay đổi vị trí và kích thước của các thành phần. Hãy xem tài liệu tham khảo để biết danh sách đầy đủ các thành phần, tham số và đối tượng sửa đổi có sẵn cho từng lớp.

Triển khai góc bo tròn

Android 12 giới thiệu các tham số hệ thống để tuỳ chỉnh bán kính góc của tiện ích cho ứng dụng một cách linh hoạt:

• system_app_widget_background_radius: Chỉ định bán kính góc của vùng chứa nền tiện ích (không bao giờ lớn hơn 28 dp).
• Bán kính bên trong: Để ngăn nội dung bị cắt, hãy tính toán bán kính tỷ lệ cho nội dung bên trong dựa trên đường viền nền hệ thống: systemRadiusValue - widgetPadding

Trong Glance, bạn có thể áp dụng các thuộc tính kích thước bán kính góc một cách linh hoạt trong thành phần bằng cách sử dụng GlanceModifier.cornerRadius(android.R.dimen.system_app_widget_background_radius).

Để có khả năng tương thích ngược trên các thiết bị chạy Android 11 (cấp độ API 30) trở xuống, hãy triển khai các thuộc tính tuỳ chỉnh và các phương án dự phòng về tài nguyên chủ đề tuỳ chỉnh:

• /values/attrs.xml

  <resources>
  <attr name="backgroundRadius" format="dimension" />
  </resources>
  

• /values/styles.xml

  <resources>
  <style name="MyWidgetTheme">
    <item name="backgroundRadius">@dimen/my_background_radius_dimen</item>
  </style>
  </resources>
  

• /values-31/styles.xml

  <resources>
  <style name="MyWidgetTheme" parent="@android:style/Theme.DeviceDefault.DayNight">
    <item name="backgroundRadius">@android:dimen/system_app_widget_background_radius</item>
  </style>
  </resources>
  

• /drawable/my_widget_background.xml

  <shape xmlns:android="http://schemas.android.com/apk/res/android"
  android:shape="rectangle">
  <corners android:radius="?attr/backgroundRadius" />
  </shape>