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

Cài đặt nhanh là các ô xuất hiện trong bảng điều khiển Cài đặt nhanh, thể hiện các hành động mà người dùng có thể nhấn để 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 thẻ thông tin tuỳ chỉnh cho người dùng thông qua TileService lớp và sử dụng đối tượng Tile để theo dõi trạng thái của thẻ thông tin. Ví dụ: bạn có thể tạo một thẻ thông tin cho phép người dùng bật VPN do ứng dụng của bạn cung cấp hoặc tắt.

Bảng điều khiển Cài đặt nhanh, trong đó ô VPN đang bật bật và tắt
Hình 1. Bảng điều khiển Cài đặt nhanh, trong đó ô VPN đang bật 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 những chức năng cụ thể mà bạn mong đợi người dùng để truy cập thường xuyên hoặc cần truy cập nhanh (hoặc cả hai). Hiệu quả nhất thẻ thông tin phù hợp với cả hai đặc điểm này, cho phép bạn truy cập nhanh vào các hành động được thực hiện thường xuyên.

Ví dụ: bạn có thể tạo một thẻ thông tin cho một ứng dụng thể dục để cho phép người dùng nhanh chóng bắt đầu một buổi tập thể dục. Tuy nhiên, bạn không nên tạo 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 thể dục của họ.

Các trường hợp sử dụng thẻ thông tin của ứng dụng thể dục
Hình 2. Ví dụ về thẻ thông tin được đề xuất và không nên dùng cho ứng dụng thể dục.

Để giúp thẻ thông tin của bạn dễ tìm thấy hơn và dễ sử dụng hơn, bạn nên tránh một số phương pháp nhất định:

  • Tránh sử dụng thẻ thông tin để chạy ứng dụng. Sử dụng lối tắt ứng dụng hoặc phím tắt chuẩn thay thế cho trình chạy.

  • Tránh sử dụng thẻ thông tin cho các thao tác một lần của người dùng. Sử dụng lối tắt ứng dụng hoặc lối tắt notification (thông báo).

  • Tránh tạo quá nhiều thẻ thông tin. Bạn nên sử dụng tối đa 2 cho mỗi ứng dụng. Sử dụng lối tắt ứng dụng.

  • Tránh sử dụng thẻ thông tin hiển thị thông tin nhưng không tương tác với người dùng. Thay vào đó, hãy chuyển sang 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 ô phù 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 một ví dụ về cách tạo và quản lý thẻ thông tin.

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 trình đơn Quick Bảng điều khiển Cài đặt. (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 kèm theo nền trong suốt, có kích thước 24 x 24 dp và có dạng VectorDrawable.

Ví dụ về vectơ vẽ được
Hình 3. Ví dụ về một vectơ vẽ được.

Tạo một biểu tượng gợi ý trực quan mục đích của thẻ thông tin. Điều này giúp người dùng dễ 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 một biểu tượng đồng hồ bấm giờ cho thẻ thông tin của ứng dụng thể dục mà người dùng có thể bắt đầu buổi tập thể dục của bạn.

Tạo và khai báo dịch vụ TileService

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

Kotlin

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()
  }
}

Java

public class MyQSTileService extends TileService {

  // Called when the user adds your tile.
  @Override
  public void onTileAdded() {
    super.onTileAdded();
  }

  // Called when your app can update your tile.
  @Override
  public void onStartListening() {
    super.onStartListening();
  }

  // Called when your app can no longer update your tile.
  @Override
  public void onStopListening() {
    super.onStopListening();
  }

  // Called when the user taps on your tile in an active or inactive state.
  @Override
  public void onClick() {
    super.onClick();
  }

  // Called when the user removes your tile.
  @Override
  public void onTileRemoved() {
    super.onTileRemoved();
  }
}

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

 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"  // 18-character limit.
     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ý dịch vụ Thẻ thông tin của bạn

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 nó.

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

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

Ngoài các phương thức gọi lại kiểm soát vòng đời 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 TileService. Các phương thức này có thể được gọi bên ngoài onCreate() và onDestroy() vì Service phương thức vòng đời và phương thức vòng đời TileService được gọi trong 2 các 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 gọi) mỗi khi TileService của bạn bước vào một giai đoạn vòng đời mới:

  • onTileAdded(): Phương thức này chỉ được gọi khi người dùng thêm thẻ thông tin 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 tốt nhất để thực hiện mọi hoạt động khởi chạy một lần. Tuy nhiên, việc này có thể không đáp ứng tất cả hoạt động khởi tạo cần thiết.

  • onStartListening() và onStopListening(): Các phương thức này là được gọi mỗi khi ứng dụng cập nhật thẻ thông tin và được gọi thường xuyên. Chiến lược phát hành đĩa đơn TileService vẫn được liên kết từ onStartListening() đến onStopListening(), cho phép ứng dụng 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á ô.

Chọn một chế độ nghe

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

Đừng cho rằng TileService của bạn sẽ sống ở bên ngoài onStartListening() và onStopListening() cặp phương thức.

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

Bạn nên sử dụng chế độ đang hoạt động nếu TileService nhận được thông báo khi thẻ thông tin về trạng thái phải được cập nhật theo quy trình riêng. Thẻ thông tin đang hoạt động sẽ hạn chế sự căng thẳng trên hệ thống vì chúng không phải bị ràng buộc mỗi khi bảng điều khiển Cài đặt nhanh hiển thị với người dùng.

Phương thức TileService.requestListeningState() tĩnh có thể được gọi tới 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ế độ đang 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 nó được liên kết bất cứ khi nào thẻ thông tin của bạn hiển thị với người dùng. Điều này có nghĩa là TileService 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. Nó cũng có thể không được 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 sẽ nhận được lệnh gọi lại đến onStartListening() sau khi người dùng mở Bảng điều khiển Quick Settings (Cài đặt nhanh). Bạn có thể cập nhật đối tượng Tile bao nhiêu lần tuỳ thích muốn trong khoảng từ onStartListening() đến onStopListening().

Bạn không cần khai báo chế độ không hoạt động — chỉ cần khô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 đang 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 thẻ thông tin ứng dụng thể dục cho phép người dùng bắt đầu một bài tập thể dục theo thời gian cụ thể STATE_ACTIVE có nghĩa là người dùng đã bắt đầu một bài tập thể dục và bộ tính giờ đang chạy.

  • STATE_INACTIVE: Cho biết trạng thái đang 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ề thẻ thông tin ứng dụng thể dục, một thẻ thông tin trong STATE_INACTIVE sẽ có nghĩa là người dùng chưa bắt đầu phiên tập thể dục, nhưng có thể làm như vậy nếu mà họ muốn.

  • STATE_UNAVAILABLE: Cho biết trạng thái tạm thời không hoạt động. Chiến lược phát hành đĩa đơn 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 này không hiện được cung cấp cho người dùng vì lý do nào đó.

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

Hệ thống có thể phủ màu biểu tượng ô và nền để phản ánh trạng thái của ô Đối tượng Tile. Đối tượng Tile được đặt thành STATE_ACTIVE là đối tượng tối nhất, với STATE_INACTIVE và STATE_UNAVAILABLE ngày càng nhẹ hơn. Màu sắc chính xác dành riêng cho nhà sản xuất và phiên bản.

Ô VPN được phủ màu để phản ánh trạng thái đối tượng
Hình 4. Ví dụ về thẻ thông tin được phủ màu để thể hiện trạng thái thẻ thông tin (trạng thái đang hoạt động, không hoạt động và không hoạt động tương ứng).

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

Bạn có thể cập nhật thẻ thông tin của mình khi nhận được lệnh gọi lại đến onStartListening(). Tuỳ thuộc vào chế độ của thẻ thông tin, bạn có thể cập nhật thẻ thông tin ít nhất một lần cho đến 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 của mình chính xác 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 của mình thành bao nhiêu lần tuỳ ý trong khoảng từ onStartListening() đến onStopListening().

Bạn có thể truy xuất đối tượng Tile bằng cách gọi getQsTile(). Cần 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 của mình sau khi đặt xong của đối tượng Tile thành các giá trị chính xác. Việc này sẽ giúp 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.

Kotlin

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 = tile.label
  qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
  qsTile.icon = state.icon
  qsTile.updateTile()
}

Java

public class StateModel {
  final boolean enabled;
  final String label;
  final Icon icon;

  public StateModel(boolean e, String l, Icon i) {
    enabled = e;
    label = l;
    icon = i;
  }
}

@Override
public void onStartListening() {
  super.onStartListening();
  StateModel state = getStateFromService();
  Tile tile = getQsTile();
  tile.setLabel(state.label);
  tile.setContentDescription(state.label);
  tile.setState(state.enabled ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setIcon(state.icon);
  tile.updateTile();
}

Xử lý thao tác nhấn

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

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

Kotlin

var clicks = 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()
}

Java

int clicks = 0;

@Override
public void onClick() {
  super.onClick();
  counter++;
  Tile tile = getQsTile();
  tile.setState((counter % 2 == 0) ? Tile.STATE_ACTIVE : Tile.STATE_INACTIVE);
  tile.setLabel("Clicked " + counter + " times");
  tile.setContentDescription(tile.getLabel());
  tile.updateTile();
}

Chạy hộp thoại

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

Chạy 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. Các hoạt động sẽ hữu ích nếu hiển thị thông tin chi tiết hơn so với trong một 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 tương tác đáng kể của người dùng, ứng dụng nên khởi chạy một chỉ khi không còn cách nào khác. Thay vào đó, hãy cân nhắc dùng hộp thoại hoặc nút bật/tắt.

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

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

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

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

Đánh dấu ô của bạn 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 ô này hoạt động chủ yếu là chuyển đổi hai trạng thái (hoạt động phổ biến nhất của thẻ thông tin). Đ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 tiếp cận nói chung.

Đặt siêu dữ liệu TOGGLEABLE_TILE thành true để đánh dấu thẻ thông tin 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 các thiết bị đã được khoá an toàn

Ô của bạn có thể hiển thị ở đầu màn hình khoá trên các thiết bị đang 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ó ở trạng thái an toàn không và TileService của bạn sẽ thay đổi hành vi cho phù hợp.

Nếu thao tác với thẻ thông tin có thể thực hiện an toàn trong khi bị khoá, hãy sử dụng startActivity() để chạy một hoạt động ở đầu màn hình khoá.

Nếu thao tác không an toàn đối với thẻ thông tin, 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 đối tượng này .

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

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

  1. Vuốt xuống để mở bảng điều khiển Quick Settings (Cài đặt nhanh).
  2. Nhấn vào nút chỉnh sửa.
  3. Di chuyển qua tất cả thẻ thông tin trên thiết bị của họ cho đến khi tìm được thẻ thông tin của bạn.
  4. Nhấn và giữ ô của bạn rồi kéo nó đến danh sách các ô đang hoạt động.

Người dùng cũng có thể di chuyển hoặc xoá thẻ thông tin 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 thêm thẻ thông tin của bạn vào một thiết bị dễ dàng hơn nhiều. Phương thức này nhắc người dùng kèm theo yêu cầu nhanh chóng thêm thẻ thông tin của bạn trực tiếp vào trình duyệt Quick của họ Bảng điều khiển Cài đặt. 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 về API vị trí cài đặt nhanh
Hình 5. Lời nhắc về API Vị trí 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 thẻ thông tin đã được thêm hay chưa. nếu mã này đã có sẵn hoặc đã xảy ra lỗi nào.

Hãy cân nhắc khi quyết định thời điểm và tần suất nhắc người dùng. T4 khuyên bạn chỉ nên gọi requestAddTileService() trong ngữ 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ý yêu cầu cho một ComponentName nếu trước đây đã bị người dùng từ chối đủ số lần. Chiến lược phát hành đĩa đơn người dùng được xác định từ Context dùng để truy xuất dịch vụ—dịch vụ đó phải khớp với người dùng hiện tại.