為應用程式建立自訂「快速設定」方塊

快速設定是顯示在快速設定面板中的資訊方塊，代表使用者可輕觸快速完成重複性工作的工作。應用程式可以透過 TileService 類別向使用者提供自訂資訊方塊，並使用 Tile 物件追蹤資訊方塊的狀態。舉例來說，您可以建立資訊方塊，讓使用者開啟或關閉應用程式提供的 VPN。

圖 1. 開啟和關閉 VPN 圖塊的快速設定面板。

注意： 本指南只討論非 Wear 圖塊，快速設定圖塊與 Wear OS 中定義的圖塊無關。如要瞭解 Wear OS 資訊方塊，請參閱 WearOS 資訊方塊指南。

決定建立圖塊的時機

建議您為使用者經常存取或需要快速存取的特定功能建立資訊方塊。最有效的資訊方塊必須同時具備這兩種特質，才能讓使用者快速存取經常執行的動作。

舉例來說，您可以為健身應用程式建立資訊方塊，讓使用者快速開始健身課程。不過，我們不建議為同一個應用程式建立資訊方塊，讓使用者查看完整的健身記錄。

圖 2. 健身應用程式中建議和不建議的資訊方塊範例。

為提升資訊方塊的可發現度和易用性，建議您避免採用下列做法：

• 請避免使用圖塊啟動應用程式，改用應用程式捷徑或標準啟動器。

• 避免將資訊方塊用於一次性使用者動作。請改用應用程式捷徑或通知。

• 避免建立過多資訊方塊。建議每個應用程式最多使用兩個。請改用應用程式快捷方式。

• 避免使用只顯示資訊但無法讓使用者互動的資訊方塊。請改用通知或小工具。

建立資訊方塊

如要建立資訊方塊，您必須先建立適當的資訊方塊圖示，然後在應用程式的資訊清單檔案中建立並宣告 TileService。

注意： 為應用程式建立 TileService 不會將其新增至使用者的「快速設定」面板。只有在使用者新增資訊方塊後，TileService 才會成為資訊方塊的介面。

快速設定範例提供建立及管理資訊方塊的範例。

建立自訂圖示

您必須提供自訂圖示，以便顯示在「快速設定」面板的圖塊中。(您會在宣告 TileService 時新增此圖示，詳情請見下一節)。圖示必須是純白色，且背景為透明，大小為 24 x 24 dp，並採用 VectorDrawable 的形式。

圖 3. 向量可繪項目範例。

建立可視覺化提示資訊方塊用途的圖示。這有助於使用者輕鬆判斷你的資訊方塊是否符合需求。舉例來說，您可以為健身應用程式建立可讓使用者開始運動時段的方塊，並為該方塊建立秒錶圖示。

建立並宣告 TileService

為圖塊建立可擴充 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();
  }
}

請在應用程式的資訊清單檔案中宣告 TileService。新增 TileService 的名稱和標籤、您在前一個部分建立的自訂圖示，以及適當的權限。

 <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>

管理 TileService

在應用程式資訊清單中建立及宣告 TileService 後，您必須管理其狀態。

TileService 是繫結服務。當應用程式要求或系統需要與 TileService 通訊時，系統會將其繫結。典型的繫結服務生命週期包含以下四種回呼方法：onCreate()、onBind()、onUnbind() 和 onDestroy()。每次服務進入新的生命週期階段時，系統都會叫用這些方法。

重要事項： 您的 TileService 仍會經歷一般 Service 生命週期。不過，TileService 與大多數其他已綁定服務不同，因為它包含應用程式必須回應的 TileService 專屬生命週期方法。

TileService 生命週期總覽

除了用於控制繫結服務生命週期的回呼之外，您還必須實作其他特定於 TileService 生命週期的其他方法。這些方法可能會在 onCreate() 和 onDestroy() 之外呼叫，因為 Service 生命週期方法和 TileService 生命週期方法是在兩個個別的非同步執行緒中呼叫。

TileService 生命週期包含下列方法，系統會在 TileService 每次進入新的生命週期階段時叫用這些方法：

• onTileAdded()：只有在使用者首次新增資訊方塊，以及使用者移除資訊方塊後再次新增時，才會呼叫這個方法。這是執行任何一次性初始化的最佳時機。不過，這可能無法滿足所有必要的初始化作業。

  注意： 系統不會在建立資訊方塊時呼叫 onTileAdded()。舉例來說，如果在裝置關機前已新增資訊方塊，且未移除，則在裝置重新啟動或開機時，系統不會呼叫 onTileAdded()。

• onStartListening() 和 onStopListening()：每當應用程式更新資訊方塊時，系統就會呼叫這些方法，且會經常呼叫。TileService 會繼續在 onStartListening() 和 onStopListening() 之間綁定，讓應用程式修改資訊方塊並推送更新。

• onTileRemoved()：只有在使用者移除資訊方塊時，系統才會呼叫這個方法。

注意： 這些階段可能不會連續發生。當使用者將設定方塊新增至「快速設定」面板時，onTileAdded() 可能只會呼叫一次。onStartListening() 和 onStopListening() 可能會在 TileService 生命週期內多次呼叫。如果使用者未從快速設定面板中移除您的資訊方塊，系統就不會呼叫 onTileRemoved()。

選取聆聽模式

TileService 會在「啟用」模式或「非啟用」模式下收聽。我們建議您使用活動模式，並在應用程式資訊清單中宣告此模式。否則，TileService 是標準模式，不需要宣告。

請勿假設 TileService 會位於 onStartListening() 和 onStopListening() 方法組合之外。

啟用模式 (建議)

針對在自身程序中監聽及監控狀態的 TileService，使用啟用模式。處於啟用模式的 TileService 會繫結至 onTileAdded()、onTileRemoved()、輕觸事件，以及應用程式處理程序要求時。

如果您的資訊方塊狀態應由其自身程序更新，建議您採用活動模式。TileService活動資訊方塊可限制系統負擔，因為使用者每次看到快速設定面板時，系統不必綁定這些資訊方塊。

您可以呼叫靜態 TileService.requestListeningState() 方法，要求開始收聽狀態，並接收 onStartListening() 的回呼。

如要宣告活動模式，請在應用程式的資訊清單檔案中加入 META_DATA_ACTIVE_TILE。

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

非啟用模式

非活動模式是標準模式。如果 TileService 在使用者可見資訊方塊時綁定，則處於非活動模式。也就是說，TileService 可能會在無法控制的時間點建立及重新繫結。當使用者未查看資訊方塊時，也可能會解除繫結並銷毀。

使用者開啟「快速設定」面板後，應用程式會收到 onStartListening() 的回呼。您可以在 onStartListening() 和 onStopListening() 之間更新 Tile 物件，次數不限。

注意： 如果您使用非活動模式而非活動模式，則每次使用者開啟快速設定面板時，系統都可能會繫結 TileService。

您不需要宣告非活動模式，只要不要將 META_DATA_ACTIVE_TILE 新增至應用程式的資訊清單檔案即可。

資訊方塊狀態總覽

使用者新增資訊方塊後，資訊方塊一律會處於下列其中一種狀態。

• STATE_ACTIVE：表示開啟或已啟用狀態。使用者可在這個狀態下與資訊方塊互動。

  舉例來說，如果健身應用程式資訊方塊可讓使用者啟動計時健身工作階段，STATE_ACTIVE 就表示使用者已啟動健身工作階段，且計時器正在運作。

• STATE_INACTIVE：表示關閉或暫停狀態。使用者可在這個狀態下與資訊方塊互動。

  舉例來說，如果要使用健身應用程式資訊方塊，STATE_INACTIVE 中的資訊方塊表示使用者尚未啟動健身工作階段，但可以視需要啟動。

• STATE_UNAVAILABLE：表示暫時無法使用的狀態。使用者在這個狀態下無法與您的資訊方塊互動。

  舉例來說，STATE_UNAVAILABLE 中的圖塊表示圖塊目前因某些原因無法供使用者使用。

  注意： 如果資訊方塊目前無法使用，但日後可能會變成可用狀態，請使用 STATE_UNAVAILABLE。如果元件永遠不會再次提供給使用者，請將 COMPONENT_ENABLED_STATE_DISABLED 傳遞至 setComponentEnabledSetting()。

系統只會設定 Tile 物件的初始狀態。您會在 Tile 物件的整個生命週期中設定其狀態。

系統可能會為資訊方塊圖示和背景著色，以反映 Tile 物件的狀態。設定為 STATE_ACTIVE 的 Tile 物件最深色，STATE_INACTIVE 和 STATE_UNAVAILABLE 則越來越淺色。確切色調會因製造商和版本而異。

圖 4. 範例：資訊方塊的色調會反映資訊方塊狀態 (分別為有效、無效和無法使用狀態)。

更新資訊方塊

收到 onStartListening() 的回呼後，您可以更新資訊方塊。視圖塊的模式而定，圖塊至少會更新一次，直到收到 onStopListening() 的回呼為止。

在啟用模式下，您可以在收到 onStopListening() 的回呼之前，將資訊方塊更新一次。在非啟用模式中，您可以在 onStartListening() 和 onStopListening() 之間更新資訊方塊。

注意： 在啟用模式下，無論資訊方塊是否對使用者顯示，您都可以更新資訊方塊。

您可以呼叫 getQsTile() 來擷取 Tile 物件。如要更新 Tile 物件的特定欄位，請呼叫下列方法：

• setContentDescription()
• setIcon()
• setLabel()
• setState()
• setStateDescription()
• setSubtitle()

注意： 應用程式資訊清單檔案中設定的圖示和標籤，是快速設定面板中圖塊上顯示的預設值。不過，您可以在更新資訊方塊時呼叫 setIcon() 和 setLabel() 方法，將欄位設為新的值。

將 Tile 物件的欄位設為正確值後，您必須呼叫 updateTile() 來更新資訊方塊。這樣系統就會剖析更新後的資訊方塊資料，並更新 UI。

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

處理輕觸

如果資訊方塊位於 STATE_ACTIVE 或 STATE_INACTIVE，使用者可以輕觸資訊方塊來觸發動作。系統接著會叫用應用程式的 onClick() 回呼。

應用程式收到 onClick() 的回呼後，即可啟動對話方塊或活動、觸發背景工作，或變更資訊方塊的狀態。

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

啟動對話方塊

showDialog()：收合「快速設定」面板並顯示對話方塊。如果動作需要額外輸入或使用者同意，請使用對話方塊為動作新增背景資訊。

注意： isLocked() 會檢查使用者的螢幕鎖定畫面是否顯示。當 isLocked() 傳回 true 時，showDialog() 不會顯示可見的對話方塊，因為它會在鎖定畫面下載。

啟動活動

startActivityAndCollapse() 會在收合面板時啟動活動。如果您需要顯示的資訊比對話方塊中更多，或是您的動作需要高度互動，活動就會很實用。

如果應用程式需要大量使用者互動，應只在萬不得已的情況下啟動活動。建議改用對話方塊或切換鈕。

長按資訊方塊會提示使用者開啟「應用程式資訊」畫面。如要覆寫這項行為，並改為啟動設定偏好設定的活動，請使用 ACTION_QS_TILE_PREFERENCES 將 <intent-filter> 新增至其中一個活動。

從 Android API 28 開始，PendingIntent 必須具備 Intent.FLAG_ACTIVITY_NEW_TASK：

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

您也可以在特定 Activity 區段的 AndroidManifest.xml 中新增標記。

將資訊方塊標示為可切換

如果資訊方塊主要用於兩種狀態切換 (這是資訊方塊最常見的行為)，建議將其標示為可切換。這有助於向作業系統提供資訊，說明資訊方塊的行為，並改善整體無障礙功能。

將 TOGGLEABLE_TILE 中繼資料設為 true，即可將資訊方塊標示為可切換的項目。

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

僅在安全鎖定的裝置上執行安全操作

在已鎖定的裝置上，資訊方塊可能會顯示在螢幕鎖定畫面的頂端。如果資訊方塊含有機密資訊，請檢查 isSecure() 的值，判斷裝置是否處於安全狀態，而 TileService 應相應變更其行為。

如果資訊方塊動作在鎖定螢幕時執行時是安全的，請使用 startActivity() 在鎖定螢幕上方啟動活動。

如果資訊方塊動作不安全，請使用 unlockAndRun() 提示使用者解鎖裝置。如果成功，系統會執行您傳入此方法的 Runnable 物件。

提示使用者新增資訊方塊

如要手動新增資訊方塊，使用者必須按照以下步驟操作：

1. 向下滑動即可開啟「快速設定」面板。
2. 輕觸「編輯」按鈕。
3. 捲動瀏覽裝置上的所有資訊方塊，直到找到您的資訊方塊為止。
4. 按住圖塊，然後拖曳至使用中的圖塊清單。

使用者也可以隨時移動或移除資訊方塊。

自 Android 13 起，您可以使用 requestAddTileService() 方法，讓使用者更輕鬆地將資訊方塊新增至裝置。這個方法會提示使用者快速將設定方塊直接加入「快速設定」面板。提示包含應用程式名稱、提供的標籤和圖示。

圖 5. Quick Settings Placement API 提示。

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

回呼會提供資訊，說明是否已新增資訊方塊、未新增資訊方塊、是否已存在資訊方塊，或是否發生任何錯誤。

請根據您的判斷決定提示使用者的時機和頻率。建議您只在情境中呼叫 requestAddTileService()，例如使用者第一次與資訊方塊提供的功能互動時。

如果使用者拒絕特定 ComponentName 的要求次數已達到一定程度，系統可以選擇停止處理該要求。系統會根據用於擷取這項服務的 Context 判斷使用者，且該使用者必須與目前使用者相符。

注意： 建議您呼叫 requestAddTileService()，提高資訊方塊的可發現度，並減輕使用者將資訊方塊新增至快速設定面板的負擔。