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

快速設定是顯示在快速設定面板中的資訊方塊，代表使用者可輕觸快速完成重複性工作的工作。應用程式可透過 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() 會在收合面板時啟動活動。如果您需要顯示的詳細資訊比對話方塊中更多，或是您的動作需要高度互動，活動就會很實用。

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

長按資訊方塊會提示使用者的「App Info」畫面。如要覆寫此行為並改為啟動用於設定偏好設定的活動，請使用 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() 來提高資訊方塊的曝光率，並減輕使用者將資訊方塊新增至快速設定面板的負擔。