在 Android 11 以上版本中，使用者可透過「快速存取裝置控制」功能，在預設啟動器的三次互動中，以及功能可見的情況下，快速檢視及控制外部裝置，例如指示燈、溫度控制器及相機。裝置 OEM 會選擇要使用的啟動器。裝置集結網站 (例如 Google Home) 和第三方供應商應用程式可以在此提供要顯示的裝置。本頁面說明如何在這個區域中顯示裝置控制，以及將其連結至控制應用程式。
如要新增這項支援，請建立並宣告 ControlsProviderService。根據預先定義的控制類型建立應用程式支援的控制項，接著建立這些控制項的發布者。
使用者介面
裝置會以樣板化的小工具顯示在「Device controls」中。目前有五個裝置控制小工具可供使用，如以下圖所示：
|
|
|
|
|
按住小工具可前往應用程式進行更多控制。您可以自訂每個小工具的圖示和顏色，但為了維護最佳的使用者體驗，如果預設設定與裝置相符，請使用預設圖示和顏色。
建立服務
本節說明如何建立 ControlsProviderService。這項服務會通知 Android 系統 UI，應用程式具有應列於 Android UI 中裝置控制區域的裝置控制。
ControlsProviderService API 會預期有類似的回應式訊息串，就如同在 Reactive Streams GitHub 專案所定義以及在 Java 9 流程介面中所實作的。此 API 是圍繞著以下概念建構而成：
- 發布商：您的應用程式是發布商。
- 訂閱者：系統 UI 是訂閱者，可要求發布者提出一些控制選項。
- 訂閱：發布商可將更新傳送至系統 UI 的時間範圍。發布者或訂閱者都可以關閉這個視窗。
宣告服務
應用程式必須在應用程式資訊清單中宣告服務，例如 MyCustomControlService。
服務必須為 ControlsProviderService 加上一個意圖篩選器。這個篩選器可讓應用程式為系統 UI 提供控制項。
您還需要一個 label，顯示在系統 UI 的控制項中。
以下範例說明如何宣告服務：
<service
android:name="MyCustomControlService"
android:label="My Custom Controls"
android:permission="android.permission.BIND_CONTROLS"
android:exported="true"
>
<intent-filter>
<action android:name="android.service.controls.ControlsProviderService" />
</intent-filter>
</service>
接著，請建立名為 MyCustomControlService.kt 的新 Kotlin 檔案，並讓該檔案擴充 ControlsProviderService()：
Kotlin
class MyCustomControlService : ControlsProviderService() { ... }
Java
public class MyCustomJavaControlService extends ControlsProviderService { ... }
選取正確的控制項類型
API 提供建構工具方法以建立控制選項。如要填入建構工具，請決定要控制的裝置，以及使用者與其互動的方式。請執行下列步驟：
- 選擇控制項所代表的裝置類型。
DeviceTypes類別是所有支援裝置的列舉。該類型用於決定 UI 中裝置的圖示和顏色。 - 決定向使用者顯示的名稱、裝置位置 (例如廚房) 以及其他與控制項相關的 UI 文字元素。
- 選擇最適合用來支援使用者互動的範本。應用程式會指派一個
ControlTemplate給控制項。該範本可直接向使用者顯示控制狀態，以及可用的輸入方法 (即ControlAction)。下表列出部分可用的範本以及支援的動作：
| 範本 | 操作 | 說明 |
ControlTemplate.getNoTemplateObject()
|
None
|
應用程式可用來傳送控制項資訊，但使用者無法與其互動。 |
ToggleTemplate
|
BooleanAction
|
代表該控制項可在啟用及停用狀態之間切換。BooleanAction 物件包含一個欄位，當使用者輕觸控制項時，其內容會變更以顯示要求的新狀態。 |
RangeTemplate
|
FloatAction
|
代表含有指定最小值、最大值和步驟值的滑桿小工具。當使用者與滑桿互動時，請將新的 FloatAction 物件傳回應用程式，並附上更新的值。 |
ToggleRangeTemplate
|
BooleanAction, FloatAction
|
本範本是 ToggleTemplate 和 RangeTemplate 的組合。可支援觸控事件及滑桿，例如可調暗燈光的控制項。 |
TemperatureControlTemplate
|
ModeAction, BooleanAction, FloatAction
|
除了封裝上述操作外，此範本還可讓使用者設定模式，例如暖氣、冷氣、暖/冷氣、節能或關閉。 |
StatelessTemplate
|
CommandAction
|
用來表示提供觸控功能但無法確定狀態的控制項，例如紅外線電視遙控器。您可以使用此範本定義例行工作或巨集，其為控制項和狀態變更的集合。 |
有了這些資訊，您現在可以建立控制項：
- 如果控制項的狀態不明，請使用
Control.StatelessBuilder建構工具類別。 - 如果控制項的狀態為已知狀態，請使用
Control.StatefulBuilder建構工具類別。
舉例來說，如要控制智慧型燈泡和溫度控制器，請將下列常數新增至 MyCustomControlService：
Kotlin
private const val LIGHT_ID = 1234 private const val LIGHT_TITLE = "My fancy light" private const val LIGHT_TYPE = DeviceTypes.TYPE_LIGHT private const val THERMOSTAT_ID = 5678 private const val THERMOSTAT_TITLE = "My fancy thermostat" private const val THERMOSTAT_TYPE = DeviceTypes.TYPE_THERMOSTAT class MyCustomControlService : ControlsProviderService() { ... }
Java
public class MyCustomJavaControlService extends ControlsProviderService { private final int LIGHT_ID = 1337; private final String LIGHT_TITLE = "My fancy light"; private final int LIGHT_TYPE = DeviceTypes.TYPE_LIGHT; private final int THERMOSTAT_ID = 1338; private final String THERMOSTAT_TITLE = "My fancy thermostat"; private final int THERMOSTAT_TYPE = DeviceTypes.TYPE_THERMOSTAT; ... }
為控制項建立發布商
建立控制項後，需要有發布商。發布商會告知系統 UI 控制項的存在。ControlsProviderService 類別有兩個發布商方法，必須在應用程式的程式碼中將其覆寫：
createPublisherForAllAvailable()：為應用程式中的所有控制項建立Publisher。使用Control.StatelessBuilder()為此發布商建構Control物件。createPublisherFor()：為給定的控制項清單建立Publisher，控制項以其字串識別碼作為識別。使用Control.StatefulBuilder建立這些Control物件，因為發布者必須為每個控制項指定狀態。
建立發布商
應用程式首次將控制項發布至系統 UI 時，應用程式不知道各個控制項的狀態。取得狀態可能會相當耗時，這項作業涉及裝置與供應商網路中的許多躍點。使用 createPublisherForAllAvailable() 方法向系統推送可用的控制項。此方法會使用 Control.StatelessBuilder 建構工具類別，因為每個控制項的狀態不明。
當 Android UI 顯示這些控制項後，使用者就能選取喜愛的控制項。
如要使用 Kotlin 協同程式建立 ControlsProviderService，請在 build.gradle 中新增依附元件：
Groovy
dependencies { implementation "org.jetbrains.kotlinx:kotlinx-coroutines-jdk9:1.6.4" }
Kotlin
dependencies { implementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk9:1.6.4") }
同步處理 Gradle 檔案後，請在 Service 中新增下列程式碼片段，以實作 createPublisherForAllAvailable()：
Kotlin
class MyCustomControlService : ControlsProviderService() { override fun createPublisherForAllAvailable(): Flow.Publisher= flowPublish { send(createStatelessControl(LIGHT_ID, LIGHT_TITLE, LIGHT_TYPE)) send(createStatelessControl(THERMOSTAT_ID, THERMOSTAT_TITLE, THERMOSTAT_TYPE)) } private fun createStatelessControl(id: Int, title: String, type: Int): Control { val intent = Intent(this, MainActivity::class.java) .putExtra(EXTRA_MESSAGE, title) .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK) val action = PendingIntent.getActivity( this, id, intent, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE ) return Control.StatelessBuilder(id.toString(), action) .setTitle(title) .setDeviceType(type) .build() } override fun createPublisherFor(controlIds: List ): Flow.Publisher { TODO() } override fun performControlAction( controlId: String, action: ControlAction, consumer: Consumer ) { TODO() } }
Java
public class MyCustomJavaControlService extends ControlsProviderService { private final int LIGHT_ID = 1337; private final String LIGHT_TITLE = "My fancy light"; private final int LIGHT_TYPE = DeviceTypes.TYPE_LIGHT; private final int THERMOSTAT_ID = 1338; private final String THERMOSTAT_TITLE = "My fancy thermostat"; private final int THERMOSTAT_TYPE = DeviceTypes.TYPE_THERMOSTAT; private boolean toggleState = false; private float rangeState = 18f; private final Map<String, ReplayProcessor> controlFlows = new HashMap<>(); @NonNull @Override public Flow.Publisher createPublisherForAllAvailable() { List controls = new ArrayList<>(); controls.add(createStatelessControl(LIGHT_ID, LIGHT_TITLE, LIGHT_TYPE)); controls.add(createStatelessControl(THERMOSTAT_ID, THERMOSTAT_TITLE, THERMOSTAT_TYPE)); return FlowAdapters.toFlowPublisher(Flowable.fromIterable(controls)); } @NonNull @Override public Flow.Publisher createPublisherFor(@NonNull List controlIds) { ReplayProcessor updatePublisher = ReplayProcessor.create(); controlIds.forEach(control -> { controlFlows.put(control, updatePublisher); updatePublisher.onNext(createLight()); updatePublisher.onNext(createThermostat()); }); return FlowAdapters.toFlowPublisher(updatePublisher); } }
向下滑動系統選單，找出「裝置控制選項」按鈕，如圖 4 所示：
輕觸「Device controls」後，系統會前往第二個畫面，讓您選取應用程式。選取應用程式後，您會看到上一個程式碼片段如何建立自訂系統選單，顯示新的控制項，如圖 5 所示：
現在，請實作 createPublisherFor() 方法，並將以下內容新增至 Service：
Kotlin
private val job = SupervisorJob() private val scope = CoroutineScope(Dispatchers.IO + job) private val controlFlows = mutableMapOf<String, MutableSharedFlow>() private var toggleState = false private var rangeState = 18f override fun createPublisherFor(controlIds: List ): Flow.Publisher { val flow = MutableSharedFlow (replay = 2, extraBufferCapacity = 2) controlIds.forEach { controlFlows[it] = flow } scope.launch { delay(1000) // Retrieving the toggle state. flow.tryEmit(createLight()) delay(1000) // Retrieving the range state. flow.tryEmit(createThermostat()) } return flow.asPublisher() } private fun createLight() = createStatefulControl( LIGHT_ID, LIGHT_TITLE, LIGHT_TYPE, toggleState, ToggleTemplate( LIGHT_ID.toString(), ControlButton( toggleState, toggleState.toString().uppercase(Locale.getDefault()) ) ) ) private fun createThermostat() = createStatefulControl( THERMOSTAT_ID, THERMOSTAT_TITLE, THERMOSTAT_TYPE, rangeState, RangeTemplate( THERMOSTAT_ID.toString(), 15f, 25f, rangeState, 0.1f, "%1.1f" ) ) private fun createStatefulControl(id: Int, title: String, type: Int, state: T, template: ControlTemplate): Control { val intent = Intent(this, MainActivity::class.java) .putExtra(EXTRA_MESSAGE, "$title $state") .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK) val action = PendingIntent.getActivity( this, id, intent, PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE ) return Control.StatefulBuilder(id.toString(), action) .setTitle(title) .setDeviceType(type) .setStatus(Control.STATUS_OK) .setControlTemplate(template) .build() } override fun onDestroy() { super.onDestroy() job.cancel() }
Java
@NonNull @Override public Flow.PublishercreatePublisherFor(@NonNull List controlIds) { ReplayProcessor updatePublisher = ReplayProcessor.create(); controlIds.forEach(control -> { controlFlows.put(control, updatePublisher); updatePublisher.onNext(createLight()); updatePublisher.onNext(createThermostat()); }); return FlowAdapters.toFlowPublisher(updatePublisher); } private Control createStatelessControl(int id, String title, int type) { Intent intent = new Intent(this, MainActivity.class) .putExtra(EXTRA_MESSAGE, title) .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); PendingIntent action = PendingIntent.getActivity( this, id, intent, PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE ); return new Control.StatelessBuilder(id + "", action) .setTitle(title) .setDeviceType(type) .build(); } private Control createLight() { return createStatefulControl( LIGHT_ID, LIGHT_TITLE, LIGHT_TYPE, toggleState, new ToggleTemplate( LIGHT_ID + "", new ControlButton( toggleState, String.valueOf(toggleState).toUpperCase(Locale.getDefault()) ) ) ); } private Control createThermostat() { return createStatefulControl( THERMOSTAT_ID, THERMOSTAT_TITLE, THERMOSTAT_TYPE, rangeState, new RangeTemplate( THERMOSTAT_ID + "", 15f, 25f, rangeState, 0.1f, "%1.1f" ) ); } private Control createStatefulControl(int id, String title, int type, T state, ControlTemplate template) { Intent intent = new Intent(this, MainActivity.class) .putExtra(EXTRA_MESSAGE, "$title $state") .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK); PendingIntent action = PendingIntent.getActivity( this, id, intent, PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE ); return new Control.StatefulBuilder(id + "", action) .setTitle(title) .setDeviceType(type) .setStatus(Control.STATUS_OK) .setControlTemplate(template) .build(); }
在這個範例中，createPublisherFor() 方法包含應用程式必須執行的假實作：與裝置通訊以擷取其狀態，並將該狀態傳送至系統。
createPublisherFor() 方法會使用 Kotlin 協同程式和流程，透過執行下列操作來滿足所需的 Reactive Streams API：
- 建立
Flow。 - 等待一秒鐘。
- 建立並發出智慧型燈具的狀態。
- 等待另一秒。
- 建立並發出溫度控制器的狀態。
處理動作
performControlAction() 方法會在使用者與發布的控制項互動時發出信號。傳送的 ControlAction 類型會決定動作。對給定的控制項採取適當操作，然後在 Android UI 中更新裝置狀態。
如要完成範例，請在 Service 中新增以下內容：
Kotlin
override fun performControlAction( controlId: String, action: ControlAction, consumer: Consumer) { controlFlows[controlId]?.let { flow -> when (controlId) { LIGHT_ID.toString() -> { consumer.accept(ControlAction.RESPONSE_OK) if (action is BooleanAction) toggleState = action.newState flow.tryEmit(createLight()) } THERMOSTAT_ID.toString() -> { consumer.accept(ControlAction.RESPONSE_OK) if (action is FloatAction) rangeState = action.newValue flow.tryEmit(createThermostat()) } else -> consumer.accept(ControlAction.RESPONSE_FAIL) } } ?: consumer.accept(ControlAction.RESPONSE_FAIL) }
Java
@Override public void performControlAction(@NonNull String controlId, @NonNull ControlAction action, @NonNull Consumerconsumer) { ReplayProcessor processor = controlFlows.get(controlId); if (processor == null) return; if (controlId.equals(LIGHT_ID + "")) { consumer.accept(ControlAction.RESPONSE_OK); if (action instanceof BooleanAction) toggleState = ((BooleanAction) action).getNewState(); processor.onNext(createLight()); } if (controlId.equals(THERMOSTAT_ID + "")) { consumer.accept(ControlAction.RESPONSE_OK); if (action instanceof FloatAction) rangeState = ((FloatAction) action).getNewValue() processor.onNext(createThermostat()); } }
執行應用程式，存取「裝置控制項」選單，查看燈具和溫度控制器控制項。
