此页面由 Cloud Translation API 翻译。

为您的应用创建自定义“快捷设置”图块

快捷设置是显示在“快捷设置”面板中的图块，表示用户可以点按的操作，以便快速完成重复性任务。您的应用可以通过 TileService 类向用户提供自定义功能块，并使用 Tile 对象跟踪功能块的状态。例如，您可以创建一个功能块，让用户开启或关闭应用提供的 VPN。

确定何时创建功能块

我们建议您为用户经常访问或需要快速访问（或两者兼具）的特定功能创建功能块。最有效的功能块是同时具备这两种特性的功能块，可让用户快速访问经常执行的操作。

例如，您可以为健身应用创建一个功能块，让用户快速开始锻炼会话。不过，我们不建议为同一应用创建可让用户查看其完整锻炼历史记录的功能块。

健身应用功能块使用场景 — **图 2.** 健身应用的推荐功能块与非推荐功能块示例。

为帮助提高功能块的易发现性和易用性，我们建议您避免以下做法：

避免使用功能块启动应用。请改用应用快捷方式或标准启动器。
避免使用功能块来执行一次性用户操作。请改用应用快捷方式或通知。
避免创建过多的功能块。我们建议每个应用最多使用两个。请改用应用快捷方式。
避免使用显示信息但不与用户互动的功能块。请改用通知或微件。

创建功能块

如需创建功能块，您需要先创建相应的功能块图标，然后在应用的清单文件中创建并声明 TileService。

快捷设置示例提供了一个有关如何创建和管理功能块的示例。

创建自定义图标

您需要提供自定义图标，该图标会显示在“快捷设置”面板中的功能块上。（您将在声明 TileService 时添加此图标，如下一部分中所述。）图标必须为纯白色，具有透明背景，尺寸为 24 x 24dp，并且采用 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 会被绑定。典型的绑定服务生命周期包含以下四个回调方法：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() 来更新图块。这样一来，系统就会解析更新后的功能块数据并更新界面。

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() 的回调时，它可以启动对话框或 activity、触发后台工作或更改功能块的状态。

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() 会收起“快捷设置”面板并显示一个对话框。如果操作需要额外输入或用户同意，请使用对话框为操作添加上下文。

启动 activity

startActivityAndCollapse() 在收起面板的同时启动 activity。如果需要显示比对话框中更详细的信息，或者您的操作具有高度互动性，那么 activity 就非常有用。

如果您的应用需要大量用户互动，则该应用应仅在万不得已的情况下才启动 activity。请考虑改用对话框或切换开关。

用户长按某个功能块后，系统会显示应用信息界面。如需替换此行为并改为启动用于设置偏好的 activity，请向您的某个 activity 添加 <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);
}

或者，您也可以在特定 Activity 部分的 AndroidManifest.xml 中添加标志。

将您的功能块标记为可切换

如果功能块主要用作双状态开关（这是功能块最常见的行为），我们建议您将其标记为可切换。这有助于向操作系统提供有关功能块行为的信息，并提高整体无障碍功能。

将 TOGGLEABLE_TILE 元数据设置为 true，以将相应功能块标记为可切换。

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

仅在安全锁定的设备上执行安全操作

您的功能块可能会显示在锁定设备的锁屏顶部。如果相应功能块包含敏感信息，请检查 isSecure() 的值，以确定设备是否处于安全状态，并让 TileService 相应地更改其行为。

如果锁定时可以安全地执行功能块操作，请使用 startActivity() 在锁屏上启动 activity。

如果功能块操作不安全，请使用 unlockAndRun() 提示用户解锁设备。如果成功，系统会执行您传递给此方法的 Runnable 对象。

提示用户添加您的功能块

如需手动添加功能块，用户必须按以下步骤操作：

向下滑动以打开“快捷设置”面板。
点按“修改”按钮。
在设备上滚动浏览所有功能块，直到找到您的功能块。
按住相应功能块，然后将其拖动到有效功能块列表中。

用户还可以随时移动或移除您的功能块。

从 Android 13 开始，您可以使用 requestAddTileService() 方法，让用户更轻松地将您的功能块添加到设备中。此方法会提示用户，询问他们是否要将您的功能块直接添加到“快捷设置”面板。提示包含应用名称、提供的标签和图标。

“Quick Settings Placement API”提示 — **图 5.** “快捷设置”放置位置 API 提示。

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

回调包含有关以下方面的信息：相应功能块是否已添加、未添加（如果已存在），或是否发生了任何错误。

在决定提示用户的时机和频率时，请自行斟酌。我们建议仅在特定情境下调用 requestAddTileService()，例如当用户首次与您的功能块所促成的功能互动时。

如果用户之前拒绝某个 ComponentName 的次数足够多，系统可以选择停止处理该 ComponentName 的请求。用户由用于检索此服务的 Context 确定，必须与当前用户匹配。

为您的应用创建自定义“快捷设置”图块 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

确定何时创建功能块

创建功能块

创建自定义图标

创建并声明 TileService

Kotlin

Java

管理 TileService

TileService 生命周期概览

选择聆听模式

活动模式（推荐）

非活动模式

卡片状态概览

更新功能块

Kotlin

Java

处理点按

Kotlin

Java

启动对话框

启动 activity

将您的功能块标记为可切换

仅在安全锁定的设备上执行安全操作

提示用户添加您的功能块

为您的应用创建自定义“快捷设置”图块