本頁面由 Cloud Translation API 翻譯而成。

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

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

「快速設定」面板，VPN 圖塊已開啟和關閉 — **圖 1.** 「快速設定」面板，以及開啟和關閉 VPN 圖塊。

決定建立動態磚的時機

建議您為使用者經常存取或需要快速存取 (或兩者皆是) 的特定功能建立資訊方塊。最有效的動態磚是同時符合這兩項特質的動態磚，可快速存取經常執行的動作。

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

健身應用程式資訊方塊用途 — **圖 2.** 健身應用程式的建議與不建議使用的動態磚範例。

為提升動態磚的曝光度和易用性，建議您避免下列做法：

避免使用動態磚啟動應用程式，請改用應用程式捷徑或標準啟動器。
請勿使用動態磚執行一次性使用者動作。請改用應用程式捷徑或通知。
避免建立過多動態磚。每個應用程式最多可設定兩個。建議改用應用程式捷徑。
避免使用會顯示資訊，但使用者無法互動的動態磚。請改用通知或小工具。

建立資訊方塊

如要建立動態磚，請先建立適當的動態磚圖示，然後在應用程式的資訊清單檔案中建立及宣告 TileService。

快速設定範例提供如何建立及管理動態磚的範例。

建立自訂圖示

您必須提供自訂圖示，該圖示會顯示在「快速設定」面板的圖塊上。(您會在宣告 TileService 時新增這個圖示，詳情請見下一節。)圖示必須為實心白色，背景為透明，尺寸為 24 x 24 dp，且格式為 VectorDrawable。

建立圖示，以視覺方式提示動態磚的用途。這有助於使用者輕鬆判斷動態磚是否符合需求。舉例來說，您可以為健身應用程式的動態磚建立碼錶圖示，讓使用者開始運動。

建立及宣告 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 通訊時，TileService 就會繫結。典型的繫結服務生命週期包含下列四個回呼方法：onCreate()、onBind()、onUnbind() 和 onDestroy()。每當服務進入新的生命週期階段時，系統就會叫用這些方法。

TileService 生命週期總覽

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

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

onTileAdded()：只有在使用者首次新增你的動態磚，以及移除並重新新增動態磚時，才會呼叫這個方法。這是執行一次性初始化的最佳時機。不過，這可能無法滿足所有必要的初始化作業。

注意： 建立圖塊時，系統不會呼叫 onTileAdded()。舉例來說，如果裝置關機前已新增圖塊但未移除，裝置重新啟動或開機時就不會呼叫 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() 的回呼。您可以在 onStartListening() 和 onStopListening() 之間，視需要更新 Tile 物件。

您不需要宣告非使用中模式，只要不要在應用程式的資訊清單檔案中加入 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 則越來越亮。確切色調取決於製造商和版本。

VPN 圖塊會根據物件狀態改變色調 — **圖 4.** 資訊方塊的顏色會反映資訊方塊狀態 (分別為啟用、停用和無法使用)。

更新資訊方塊

收到 onStartListening() 的回呼後，即可更新動態磚。視圖塊模式而定，圖塊至少會更新一次，直到收到 onStopListening() 的回呼為止。

在正常模式下，您可以在收到 onStopListening() 的回呼之前，更新動態磚一次。在非使用中模式下，你可以在 onStartListening() 和 onStopListening() 之間更新動態磚任意次數。

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

將 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() 會收合「快速設定」面板，並顯示對話方塊。如果動作需要額外輸入內容或使用者同意聲明，請使用對話方塊為動作新增背景資訊。

啟動活動

startActivityAndCollapse() 會在收合面板時啟動活動。如果需要顯示比對話方塊更詳細的資訊，或動作具有高度互動性，活動就非常實用。

如果應用程式需要大量使用者互動，則應盡量避免啟動活動。建議改用對話方塊或切換按鈕。

長按動態磚會提示使用者開啟「應用程式資訊」畫面。如要覆寫這項行為，改為啟動活動來設定偏好設定，請在其中一個活動中加入 <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.xmlActivity區段中新增標記。

將動態磚標示為可切換

如果圖塊主要做為雙態切換開關 (這是圖塊最常見的行為)，建議將圖塊標示為可切換。這有助於向作業系統提供有關動態磚行為的資訊，並提升整體無障礙功能。

將 TOGGLEABLE_TILE 中繼資料設為 true，即可將動態磚標示為可切換。

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

只能在安全鎖定的裝置上執行安全動作

在裝置鎖定時，動態磚可能會顯示在螢幕鎖定畫面上方。如果圖塊含有私密資訊，請檢查 isSecure() 的值，判斷裝置是否處於安全狀態，並據此變更 TileService 的行為。

如果圖塊動作可在鎖定狀態下安全執行，請使用 startActivity() 在螢幕鎖定畫面上方啟動活動。

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

將動態磚分類

如要提升「快速設定」的使用者體驗，可以將資訊方塊分類。系統會將圖塊歸類為「連線」、「螢幕」和「隱私權」等類別。系統會使用這些類別，在「快速設定」編輯模式中排序及分組動態磚，方便使用者尋找及管理。

實作

如要指定 TileService 的類別，請在 AndroidManifest.xml 檔案的服務宣告中新增中繼資料欄位：

在 AndroidManifest.xml 中，於 TileService 的 <service> 元素內新增 <meta-data> 元素。
android:name：將這個值設為 android.service.quicksettings.TILE_CATEGORY。
android:value：指派其中一個預先定義的類別常數，例如 android.service.quicksettings.CATEGORY_CONNECTIVITY 或 android.service.quicksettings.CATEGORY_DISPLAY。

如以下範例所示：

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

這項 API 提供一組預先定義的類別供您選擇。這些類別在 TileService 類別中定義為字串常數。

如果未指定類別，系統會自動指派預設類別：

來自系統應用程式：適用於屬於系統應用程式的動態磚。
來自安裝的應用程式：使用者安裝的應用程式資訊方塊。

雖然 Google Pixel 裝置會使用「快速設定」中的類別，但原始設備製造商 (OEM) 可以在各自的系統 UI 中使用或忽略這項類別資訊。

提示使用者新增你的動態磚

如要手動新增動態磚，使用者必須完成下列步驟：

向下滑動開啟「快速設定」面板。
輕觸「編輯」按鈕。
在裝置上捲動瀏覽所有動態磚，直到找到你的動態磚為止。
按住動態磚，然後拖曳至有效動態磚清單。

使用者也可以隨時移動或移除你的動態磚。

從 Android 13 開始，您可以使用 requestAddTileService() 方法，讓使用者更輕鬆地將動態磚新增至裝置。這個方法會提示使用者，要求他們直接在「快速設定」面板中新增動態磚。提示會顯示應用程式名稱、提供的標籤和圖示。

快速設定放置 API 提示 — **圖 5.** 快速設定位置資訊 API 提示。

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

回呼包含圖塊是否已新增、未新增、已存在，或是否發生任何錯誤的相關資訊。

請自行斟酌提示使用者的時機和頻率。建議您只在適當情境下呼叫 requestAddTileService()，例如使用者首次與圖塊輔助的功能互動時。

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

為應用程式建立自訂「快速設定」方塊 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

決定建立動態磚的時機

建立資訊方塊

建立自訂圖示

建立及宣告 TileService

Kotlin

Java

管理 TileService

TileService 生命週期總覽

選取聆聽模式

啟用模式 (建議)

非啟用模式

資訊方塊狀態總覽

更新資訊方塊

Kotlin

Java

處理輕觸事件

Kotlin

Java

啟動對話方塊

啟動活動

將動態磚標示為可切換

只能在安全鎖定的裝置上執行安全動作

將動態磚分類

實作

提示使用者新增你的動態磚

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