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

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

「快速設定」面板顯示「VPN」圖塊
  開啟/關閉
圖 1. 「快速設定」面板顯示「VPN」圖塊 保持開啟狀態。

決定建立資訊方塊的時機

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

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

健身應用程式圖塊使用情境
圖 2. 建議與非推薦的健身應用程式資訊方塊範例。

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

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

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

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

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

建立資訊方塊

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

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

建立自訂圖示

你需要提供自訂圖示,這個圖示會顯示在快速 設定面板。(您將在宣告 TileService 時新增這個圖示。 說明)。圖示必須是純白色,並加上 透明背景,測量 24 x 24dp,且採用 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 生命週期總覽

除了控制繫結服務生命週期的回呼外,您也必須 實作 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_ACTIVETile 物件最暗, STATE_INACTIVESTATE_UNAVAILABLE越來越輕。確切色調 專屬於製造商和版本

將 VPN 圖塊色調以反映物件狀態
圖 4. 色調為反映圖塊狀態的圖塊範例 (分別處於有效、無效和無法使用的狀態)。

更新動態磚

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

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

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

,瞭解如何調查及移除這項存取權。

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

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_ACTIVESTATE_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() 在收合 面板。如果顯示更詳細的資訊,活動就能派上用場 或是在對話方塊顯示互動,或是動作非常有互動性

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

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

快速設定刊登位置 API 提示
圖 5.快速設定刊登位置 API 提示。
public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

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

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

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