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

快速設定是快速設定面板中顯示的方塊， 表示動作，使用者只要輕觸一下就能快速完成週期性工作。 應用程式可透過 TileService 為使用者提供自訂資訊方塊 類別，並使用 Tile 物件追蹤資訊方塊狀態。例如： 您可以建立資訊方塊，讓使用者開啟您的應用程式提供的 VPN，或是 關閉。

決定建立資訊方塊的時機

建議您為預期使用者採用的特定功能建立圖塊 以便經常存取或需要快速存取 (或兩者皆有)。最有效的 資訊方塊就是同時符合這兩個條件的方塊，可以快速存取 互動頻率相當高

例如，您可以建立健身應用程式資訊方塊，讓使用者可以： 快速開始健身課程不過，我們不建議建立資訊方塊 這款應用程式，可讓使用者查看完整的健身記錄。

為提高資訊方塊的曝光度和使用便利性，我們建議你 避免特定做法：

• 避免使用資訊方塊啟動應用程式。使用應用程式捷徑或標準模式 啟動器。

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

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

• 避免使用會顯示資訊但不具互動性的資訊方塊 使用者。請改用通知或小工具。

建立資訊方塊

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

快速設定範例舉例說明如何建立 以及管理資訊方塊

建立自訂圖示

你需要提供自訂圖示，這個圖示會顯示在快速 設定面板。(您將在宣告 TileService 時新增這個圖示。 說明)。圖示必須是純白色，並加上 透明背景，測量 24 x 24dp，且採用 VectorDrawable。

建立以視覺化方式呈現資訊方塊用途的圖示。這可以讓使用者 方便辨別資訊方塊是否符合需求舉例來說，您可以建立 健身應用程式資訊方塊的碼錶圖示，可讓使用者啟動 鍛鍊課程

建立並宣告 TileService

為擴充 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()
  }
}

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 生命週期總覽

除了控制繫結服務生命週期的回呼外，您也必須 實作 TileService 生命週期特有的其他方法。這些方法 可能會在 onCreate() 和 onDestroy() 之外呼叫，因為 Service 系統會透過以下兩種方法呼叫生命週期方法和 TileService 生命週期方法 以及個別的非同步執行緒

TileService 生命週期包含下列叫用的方法 每次 TileService 進入新的生命週期階段時，系統都會執行這項作業：

• onTileAdded()：只有在使用者新增 方塊，以及如果使用者移除並再次新增您的動態磚。 這就是執行任何一次性初始化的最佳時機。不過 不符合所有必要的初始化作業。

• onStartListening() 和 onStopListening()：這些方法 。 TileService 仍繫結於 onStartListening() 至 onStopListening()，可讓您的應用程式修改資訊方塊及推送更新。

• 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() 的回呼 快速設定面板。您可以更新 Tile 物件，次數不限 介於 onStartListening() 到 onStopListening() 之間

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

資訊方塊狀態總覽

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

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

  例如健身應用程式資訊方塊，讓使用者啟動限時健身 工作階段，STATE_ACTIVE 表示使用者已開始健身 以及計時器正在執行

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

  如要再次使用健身應用程式資訊方塊範例，STATE_INACTIVE 中的資訊方塊會 表示使用者尚未啟動健身工作階段，但可以 他們想要瀏覽的內容

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

  例如，STATE_UNAVAILABLE 中的資訊方塊表示資訊方塊不是 供使用者使用。

系統只會設定 Tile 物件的初始狀態。您設定了Tile 物件狀態

系統可能會配合 Tile 物件。設為 STATE_ACTIVE 的 Tile 物件最暗， STATE_INACTIVE，STATE_UNAVAILABLE越來越輕。確切色調 專屬於製造商和版本

更新動態磚

收到對 onStartListening() 的回呼後，即可更新資訊方塊。 根據資訊方塊模式，動態磚至少可以更新一次， 接收對 onStopListening() 的回呼。

在正常模式中，您可以只更新一次動態磚，然後才會收到 回呼 onStopListening()。在非啟用模式下，您可以將資訊方塊更新為 onStartListening() 和 onStopListening() 之間可無限次。

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

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

完成設定後，你必須呼叫 updateTile() 才能更新資訊方塊 將 Tile 物件的欄位更新為正確的值。這樣系統就會 剖析更新的資訊方塊資料並更新使用者介面。

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

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() 的回呼後，即可啟動對話方塊或 活動、觸發背景工作或變更資訊方塊狀態。

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

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() 收合「快速設定」面板，並顯示對話方塊。 視需要使用對話方塊，為您的動作補充背景資訊 或使用者同意選項

啟動活動

startActivityAndCollapse() 在收合 面板。如果顯示更詳細的資訊，活動就能派上用場 或是在對話方塊顯示互動，或是動作非常有互動性

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

長按資訊方塊會提示使用者的「App Info」畫面。覆寫 而是啟動活動以設定偏好設定 透過以下應用程式參加您的一項活動：<intent-filter> ACTION_QS_TILE_PREFERENCES。

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

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

您也可以在 AndroidManifest.xml 的 「Activity」專區。

將動態磚標示為可切換

如果您的資訊方塊主要功能為 雙狀態切換 (這是最常見的資訊方塊行為)。這有助於 向作業系統提供資訊方塊行為的相關資訊 提升整體的無障礙程度

將 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() 方法。 ，方便使用者將你的資訊方塊新增至裝置。這個方法 提示使用者要求，讓他們快速將您的資訊方塊直接新增至 設定面板。提示包含應用程式名稱、提供的標籤 和圖示

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

回呼中包含資訊方塊是否已新增，而非 已新增、位於該物件 (如果有的話) 或發生任何錯誤。

請自行斟酌是否要顯示提示訊息的時機和頻率。三 建議您只在使用情境下呼叫 requestAddTileService()，例如 使用者初次與資訊方塊輔助的功能互動時。

系統可以選擇停止處理 ComponentName。 系統會根據用於擷取此內容的 Context 服務 - 必須與目前的使用者相符。