Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Tạo ô Cài đặt nhanh tuỳ chỉnh cho ứng dụng

Cài đặt nhanh là các ô hiển thị trong bảng điều khiển Cài đặt nhanh, đại diện cho các thao tác mà người dùng có thể nhấn vào để nhanh chóng hoàn thành các việc cần làm định kỳ. Ứng dụng của bạn có thể cung cấp một ô tuỳ chỉnh cho người dùng thông qua lớp TileService và sử dụng đối tượng Tile để theo dõi trạng thái của ô. Ví dụ: bạn có thể tạo một ô cho phép người dùng bật hoặc tắt VPN do ứng dụng của bạn cung cấp.

Bảng Cài đặt nhanh có ô VPN được bật và tắt — **Hình 1.** Bảng điều khiển Cài đặt nhanh với ô VPN được bật và tắt.

Quyết định thời điểm tạo thẻ thông tin

Bạn nên tạo thẻ thông tin cho các chức năng cụ thể mà bạn muốn người dùng truy cập thường xuyên hoặc cần truy cập nhanh (hoặc cả hai). Thẻ thông tin hiệu quả nhất là thẻ thông tin đáp ứng cả hai tiêu chí này, giúp truy cập nhanh vào các thao tác thường xuyên thực hiện.

Ví dụ: bạn có thể tạo một ô cho ứng dụng theo dõi thể chất để cho phép người dùng nhanh chóng bắt đầu một buổi tập. Tuy nhiên, bạn không nên tạo một thẻ thông tin cho cùng một ứng dụng để cho phép người dùng xem lại toàn bộ nhật ký tập luyện của họ.

Các trường hợp sử dụng ô của ứng dụng theo dõi thể chất — **Hình 2.** Ví dụ về thẻ nên dùng và không nên dùng cho một ứng dụng theo dõi thể chất.

Để giúp cải thiện khả năng khám phá và tính dễ sử dụng của thẻ thông tin, bạn nên tránh một số phương pháp sau:

Tránh sử dụng thẻ thông tin để chạy ứng dụng. Thay vào đó, hãy sử dụng lối tắt ứng dụng hoặc trình chạy tiêu chuẩn.
Tránh sử dụng thẻ thông tin cho các hành động một lần của người dùng. Thay vào đó, hãy sử dụng lối tắt ứng dụng hoặc thông báo.
Tránh tạo quá nhiều thẻ thông tin. Bạn nên dùng tối đa 2 lối tắt cho mỗi ứng dụng. Thay vào đó, hãy dùng lối tắt ứng dụng.
Tránh sử dụng các thẻ thông tin hiển thị thông tin nhưng không tương tác được với người dùng. Thay vào đó, hãy sử dụng thông báo hoặc tiện ích.

Tạo thẻ thông tin

Để tạo một thẻ thông tin, trước tiên, bạn cần tạo một biểu tượng thẻ thông tin thích hợp, sau đó tạo và khai báo TileService trong tệp kê khai của ứng dụng.

Mẫu Cài đặt nhanh cung cấp ví dụ về cách tạo và quản lý một ô.

Tạo biểu tượng tuỳ chỉnh

Bạn cần cung cấp một biểu tượng tuỳ chỉnh, biểu tượng này sẽ xuất hiện trên ô trong bảng Cài đặt nhanh. (Bạn sẽ thêm biểu tượng này khi khai báo TileService, được mô tả trong phần tiếp theo.) Biểu tượng phải có màu trắng đồng nhất với nền trong suốt, có kích thước 24 x 24 dp và ở dạng VectorDrawable.

Ví dụ về drawable vector — **Hình 3.** Ví dụ về một drawable vector.

Tạo một biểu tượng gợi ý trực quan về mục đích của thẻ thông tin. Điều này giúp người dùng xác định xem thẻ thông tin của bạn có phù hợp với nhu cầu của họ hay không. Ví dụ: bạn có thể tạo biểu tượng đồng hồ bấm giờ cho một ô của ứng dụng theo dõi thể chất để cho phép người dùng bắt đầu một buổi tập.

Tạo và khai báo TileService

Tạo một dịch vụ cho thẻ mở rộng lớp TileService.

class MyQSTileService : TileService() {

    // Called when the user adds your tile.
    override fun onTileAdded() {
        super.onTileAdded()
    }
    // Called when your app can update your tile.
    override fun onStartListening() {
        super.onStartListening()
    }

    // Called when your app can no longer update your tile.
    override fun onStopListening() {
        super.onStopListening()
    }

    // Called when the user taps on your tile in an active or inactive state.
    override fun onClick() {
        super.onClick()
    }
    // Called when the user removes your tile.
    override fun onTileRemoved() {
        super.onTileRemoved()
    }
}QuickSettingsTilesSnippets.kt

Khai báo TileService trong tệp kê khai của ứng dụng. Thêm tên và nhãn của TileService (tối đa 18 ký tự cho android:label), biểu tượng tuỳ chỉnh mà bạn đã tạo trong phần trước và quyền thích hợp.

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

Quản lý TileService

Sau khi tạo và khai báo TileService trong tệp kê khai ứng dụng, bạn phải quản lý trạng thái của tệp đó.

TileService là một dịch vụ ràng buộc. TileService của bạn được liên kết khi ứng dụng yêu cầu hoặc nếu hệ thống cần giao tiếp với ứng dụng đó. Vòng đời dịch vụ ràng buộc thông thường chứa 4 phương thức gọi lại sau: onCreate(), onBind(), onUnbind() và onDestroy(). Hệ thống sẽ gọi các phương thức này mỗi khi dịch vụ chuyển sang một giai đoạn mới trong vòng đời.

Tổng quan về vòng đời của TileService

Ngoài các lệnh gọi lại kiểm soát vòng đời của dịch vụ ràng buộc, bạn phải triển khai các phương thức khác dành riêng cho vòng đời của TileService. Các phương thức này có thể được gọi bên ngoài onCreate() và onDestroy() vì các phương thức vòng đời Service và các phương thức vòng đời TileService được gọi trong hai luồng không đồng bộ riêng biệt.

Vòng đời TileService chứa các phương thức sau đây, được hệ thống gọi mỗi khi TileService của bạn chuyển sang một giai đoạn mới trong vòng đời:

onTileAdded(): Phương thức này chỉ được gọi khi người dùng thêm thẻ thông tin của bạn lần đầu tiên, và nếu người dùng xoá rồi thêm lại thẻ thông tin của bạn. Đây là thời điểm thích hợp nhất để thực hiện mọi thao tác khởi chạy một lần. Tuy nhiên, điều này có thể không đáp ứng tất cả các yêu cầu khởi chạy cần thiết.

Lưu ý: onTileAdded() không được gọi bất cứ khi nào thẻ thông tin được tạo. Ví dụ: onTileAdded() không được gọi khi thiết bị khởi động lại hoặc bật nguồn nếu ô đã được thêm và không bị xoá trước khi thiết bị tắt nguồn.
onStartListening() và onStopListening(): Các phương thức này được gọi bất cứ khi nào ứng dụng của bạn cập nhật thẻ thông tin và thường xuyên được gọi. TileService vẫn được liên kết giữa onStartListening() và onStopListening(), cho phép ứng dụng của bạn sửa đổi thẻ thông tin và đẩy bản cập nhật.
onTileRemoved(): Phương thức này chỉ được gọi nếu người dùng xoá ô của bạn.

Chọn một chế độ nghe

TileService của bạn lắng nghe ở chế độ đang hoạt động hoặc chế độ không hoạt động. Bạn nên sử dụng chế độ hoạt động và cần khai báo chế độ này trong tệp kê khai ứng dụng. Nếu không, TileService sẽ là chế độ chuẩn và không cần khai báo.

Đừng giả định rằng TileService của bạn sẽ tồn tại bên ngoài cặp phương thức onStartListening() và onStopListening().

Chế độ đang hoạt động (nên dùng)

Sử dụng chế độ hoạt động cho một TileService lắng nghe và giám sát trạng thái của nó trong quy trình riêng. TileService ở chế độ đang hoạt động được liên kết với onTileAdded(), onTileRemoved(), sự kiện nhấn và khi được quy trình ứng dụng yêu cầu.

Bạn nên dùng chế độ hoạt động nếu TileService được thông báo khi trạng thái thẻ thông tin cần được cập nhật theo quy trình riêng. Thẻ thông tin đang hoạt động giúp hạn chế áp lực lên hệ thống vì không cần phải liên kết mỗi khi người dùng nhìn thấy bảng điều khiển Cài đặt nhanh.

Bạn có thể gọi phương thức tĩnh TileService.requestListeningState() để yêu cầu bắt đầu trạng thái nghe và nhận lệnh gọi lại đến onStartListening().

Bạn có thể khai báo chế độ hoạt động bằng cách thêm META_DATA_ACTIVE_TILE vào tệp kê khai của ứng dụng.

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
       android:value="true" />
    ...
</service>

Chế độ không hoạt động

Chế độ không hoạt động là chế độ tiêu chuẩn. TileService ở chế độ không hoạt động nếu được liên kết bất cứ khi nào người dùng nhìn thấy thẻ thông tin của bạn. Điều này có nghĩa là TileService của bạn có thể được tạo và liên kết lại vào những thời điểm nằm ngoài tầm kiểm soát. Thành phần này cũng có thể bị huỷ liên kết và bị huỷ khi người dùng không xem thẻ thông tin.

Ứng dụng của bạn nhận được lệnh gọi lại đến onStartListening() sau khi người dùng mở bảng điều khiển Cài đặt nhanh. Bạn có thể cập nhật đối tượng Tile bao nhiêu lần tuỳ thích trong khoảng thời gian từ onStartListening() đến onStopListening().

Bạn không cần khai báo chế độ không hoạt động: đừng thêm META_DATA_ACTIVE_TILE vào tệp kê khai của ứng dụng.

Tổng quan về trạng thái thẻ thông tin

Sau khi người dùng thêm thẻ thông tin của bạn, thẻ thông tin đó luôn tồn tại ở một trong các trạng thái sau.

STATE_ACTIVE: Cho biết trạng thái bật hoặc đã bật. Người dùng có thể tương tác với thẻ thông tin của bạn khi ở trạng thái này.

Ví dụ: đối với ô ứng dụng theo dõi thể chất cho phép người dùng bắt đầu một phiên tập luyện có hẹn giờ, STATE_ACTIVE có nghĩa là người dùng đã bắt đầu một phiên tập luyện và đồng hồ hẹn giờ đang chạy.
STATE_INACTIVE: Cho biết trạng thái tắt hoặc tạm dừng. Người dùng có thể tương tác với thẻ thông tin của bạn khi ở trạng thái này.

Để sử dụng lại ví dụ về ô ứng dụng theo dõi thể chất, ô trong STATE_INACTIVE có nghĩa là người dùng chưa bắt đầu một phiên tập luyện, nhưng có thể làm như vậy nếu muốn.
STATE_UNAVAILABLE: Cho biết trạng thái tạm thời không hoạt động. Người dùng không thể tương tác với thẻ thông tin của bạn khi ở trạng thái này.

Ví dụ: một thẻ thông tin trong STATE_UNAVAILABLE có nghĩa là thẻ thông tin đó hiện không có sẵn cho người dùng vì một lý do nào đó.

Thận trọng: Sử dụng STATE_UNAVAILABLE cho các thẻ hiện không có sẵn nhưng có thể được chuyển sang trạng thái có sẵn sau này. Nếu thành phần này không bao giờ có thể dùng được cho người dùng nữa, hãy truyền COMPONENT_ENABLED_STATE_DISABLED vào setComponentEnabledSetting().

Hệ thống chỉ đặt trạng thái ban đầu của đối tượng Tile. Bạn đặt trạng thái của đối tượng Tile trong suốt phần còn lại của vòng đời.

Hệ thống có thể phủ màu biểu tượng và nền của ô để phản ánh trạng thái của đối tượng Tile. Các đối tượng Tile được đặt thành STATE_ACTIVE là tối nhất, còn STATE_INACTIVE và STATE_UNAVAILABLE thì sáng hơn. Sắc thái màu chính xác tuỳ thuộc vào nhà sản xuất và phiên bản.

Ô VPN được tô màu để phản ánh trạng thái của đối tượng — **Hình 4.** Ví dụ về một thẻ thông tin được phủ màu để phản ánh trạng thái của thẻ thông tin (lần lượt là trạng thái đang hoạt động, không hoạt động và không có sẵn).

Cập nhật thẻ thông tin

Bạn có thể cập nhật thẻ thông tin sau khi nhận được lệnh gọi lại đến onStartListening(). Tuỳ thuộc vào chế độ của thẻ thông tin, thẻ thông tin của bạn có thể được cập nhật ít nhất một lần cho đến khi nhận được lệnh gọi lại đến onStopListening().

Ở chế độ đang hoạt động, bạn có thể cập nhật thẻ thông tin đúng một lần trước khi nhận được lệnh gọi lại đến onStopListening(). Ở chế độ không hoạt động, bạn có thể cập nhật thẻ thông tin bao nhiêu lần tuỳ ý trong khoảng thời gian từ onStartListening() đến onStopListening().

Bạn có thể truy xuất đối tượng Tile bằng cách gọi getQsTile(). Để cập nhật các trường cụ thể của đối tượng Tile, hãy gọi các phương thức sau:

Bạn phải gọi updateTile() để cập nhật thẻ thông tin sau khi đặt các trường của đối tượng Tile thành giá trị chính xác. Thao tác này sẽ khiến hệ thống phân tích cú pháp dữ liệu thẻ thông tin đã cập nhật và cập nhật giao diện người dùng.

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
    super.onStartListening()
    val state = getStateFromService()
    qsTile.label = state.label
    qsTile.contentDescription = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}QuickSettingsTilesSnippets.kt

Xử lý thao tác nhấn

Người dùng có thể nhấn vào ô của bạn để kích hoạt một hành động nếu ô của bạn ở trạng thái STATE_ACTIVE hoặc STATE_INACTIVE. Sau đó, hệ thống sẽ gọi lệnh gọi lại onClick() của ứng dụng.

Sau khi nhận được lệnh gọi lại đến onClick(), ứng dụng có thể chạy một hộp thoại hoặc hoạt động, kích hoạt công việc trong nền hoặc thay đổi trạng thái của thẻ thông tin.

var counter = 0
override fun onClick() {
    super.onClick()
    counter++
    qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.label = "Clicked $counter times"
    qsTile.contentDescription = qsTile.label
    qsTile.updateTile()
}QuickSettingsTilesSnippets.kt

Chạy hộp thoại

showDialog() thu gọn bảng Cài đặt nhanh và hiện một hộp thoại. Sử dụng hộp thoại để thêm ngữ cảnh vào hành động của bạn nếu hành động đó yêu cầu thêm thông tin đầu vào hoặc sự đồng ý của người dùng.

Bắt đầu một hoạt động

startActivityAndCollapse() bắt đầu một hoạt động trong khi thu gọn bảng điều khiển. Hoạt động sẽ hữu ích nếu có nhiều thông tin chi tiết cần hiển thị hơn so với trong hộp thoại hoặc nếu hành động của bạn có tính tương tác cao.

Nếu ứng dụng của bạn yêu cầu người dùng tương tác nhiều, thì ứng dụng chỉ nên khởi chạy một hoạt động như một phương án cuối cùng. Thay vào đó, hãy cân nhắc sử dụng hộp thoại hoặc nút bật/tắt.

Thao tác nhấn và giữ một ô sẽ nhắc màn hình Thông tin ứng dụng cho người dùng. Để ghi đè hành vi này và thay vào đó chạy một hoạt động để đặt lựa chọn ưu tiên, hãy thêm <intent-filter> vào một trong các hoạt động của bạn bằng ACTION_QS_TILE_PREFERENCES.

Kể từ Android API 28, PendingIntent phải có Intent.FLAG_ACTIVITY_NEW_TASK:

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}QuickSettingsTilesSnippets.kt

Ngoài ra, bạn có thể thêm cờ vào AndroidManifest.xml trong phần Activity cụ thể.

Đánh dấu ô là có thể bật/tắt

Bạn nên đánh dấu ô của mình là có thể bật/tắt nếu ô đó hoạt động chủ yếu dưới dạng nút chuyển hai trạng thái (đây là hành vi phổ biến nhất của ô). Điều này giúp cung cấp thông tin về hành vi của thẻ thông tin cho hệ điều hành và cải thiện khả năng hỗ trợ tiếp cận tổng thể.

Đặt siêu dữ liệu TOGGLEABLE_TILE thành true để đánh dấu ô của bạn là có thể bật/tắt.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

Chỉ thực hiện các thao tác an toàn trên thiết bị được khoá an toàn

Thẻ thông tin của bạn có thể xuất hiện trên màn hình khoá của các thiết bị đã khoá. Nếu ô chứa thông tin nhạy cảm, hãy kiểm tra giá trị của isSecure() để xác định xem thiết bị có đang ở trạng thái an toàn hay không và TileService của bạn sẽ thay đổi hành vi cho phù hợp.

Nếu hành động của ô an toàn để thực hiện khi bị khoá, hãy sử dụng startActivity() để chạy một hoạt động trên màn hình khoá.

Nếu hành động của thẻ thông tin không an toàn, hãy sử dụng unlockAndRun() để nhắc người dùng mở khoá thiết bị. Nếu thành công, hệ thống sẽ thực thi đối tượng Runnable mà bạn truyền vào phương thức này.

Phân loại thẻ thông tin

Để nâng cao trải nghiệm người dùng trong phần Cài đặt nhanh, bạn có thể phân loại ô của mình. Hệ thống sắp xếp các ô thành các danh mục như Kết nối, Hiển thị và Quyền riêng tư. Hệ thống sử dụng các danh mục này để sắp xếp và nhóm các ô trong chế độ chỉnh sửa Cài đặt nhanh, giúp người dùng dễ dàng tìm và quản lý các ô đó.

Triển khai

Để chỉ định danh mục cho TileService, hãy thêm một trường siêu dữ liệu vào nội dung khai báo dịch vụ trong tệp AndroidManifest.xml:

Trong AndroidManifest.xml, trong phần tử <service> cho TileService, hãy thêm phần tử <meta-data>.
android:name: Đặt giá trị này thành android.service.quicksettings.TILE_CATEGORY.
android:value: Chỉ định một trong các hằng số danh mục được xác định trước, chẳng hạn như android.service.quicksettings.CATEGORY_CONNECTIVITY hoặc android.service.quicksettings.CATEGORY_DISPLAY.

Như trong ví dụ sau:

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

API này cung cấp một tập hợp các danh mục được xác định trước để bạn lựa chọn. Các danh mục này được xác định là hằng số chuỗi trong lớp TileService.

Nếu bạn không chỉ định danh mục, hệ thống sẽ tự động chỉ định một danh mục mặc định:

Từ các ứng dụng hệ thống: Đối với các ô thuộc một ứng dụng hệ thống.
Từ các ứng dụng bạn đã cài đặt: Đối với các ô từ ứng dụng do người dùng cài đặt.

Mặc dù thiết bị Google Pixel sử dụng các danh mục trong phần Cài đặt nhanh, nhưng OEM có thể sử dụng hoặc bỏ qua thông tin danh mục này trong giao diện người dùng hệ thống tương ứng của họ.

Nhắc người dùng thêm thẻ thông tin của bạn

Để thêm thẻ thông tin theo cách thủ công, người dùng phải làm theo một số bước:

Vuốt xuống để mở bảng Cài đặt nhanh.
Nhấn vào nút chỉnh sửa.
Cuộn qua tất cả các ô trên thiết bị cho đến khi tìm thấy ô của bạn.
Nhấn và giữ ô, sau đó kéo ô vào danh sách các ô đang hoạt động.

Người dùng cũng có thể di chuyển hoặc xoá ô của bạn bất cứ lúc nào.

Kể từ Android 13, bạn có thể sử dụng phương thức requestAddTileService() để giúp người dùng dễ dàng thêm ô của bạn vào thiết bị. Phương thức này nhắc người dùng bằng một yêu cầu thêm nhanh ô của bạn trực tiếp vào bảng điều khiển Cài đặt nhanh. Lời nhắc bao gồm tên ứng dụng, nhãn được cung cấp và biểu tượng.

Lời nhắc của API Vị trí cài đặt nhanh — **Hình 5.** Lời nhắc của API vị trí trong trình đơn Cài đặt nhanh.

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

Lệnh gọi lại chứa thông tin về việc ô đã được thêm, chưa được thêm, đã có sẵn hay đã xảy ra lỗi.

Hãy cân nhắc kỹ khi quyết định thời điểm và tần suất nhắc người dùng. Bạn chỉ nên gọi requestAddTileService() trong bối cảnh, chẳng hạn như khi người dùng tương tác lần đầu với một tính năng mà thẻ thông tin của bạn hỗ trợ.

Hệ thống có thể chọn ngừng xử lý các yêu cầu cho một ComponentName nhất định nếu người dùng đã từ chối yêu cầu đó đủ số lần trước đó. Người dùng được xác định từ Context dùng để truy xuất dịch vụ này: người dùng phải khớp với người dùng hiện tại.