In Android 11 e versioni successive, la funzionalità Controllo dispositivo di accesso rapido consente all'utente di visualizzare e controllare rapidamente i dispositivi esterni come luci, termostati e videocamere da un'interazione utente entro tre interazioni da un Avvio app predefinito. L'OEM del dispositivo sceglie quale Avvio app utilizzare. Gli aggregatori di dispositivi, ad esempio Google Home, e le app di fornitori di terze parti possono fornire dispositivi da visualizzare in questo spazio. Questa pagina mostra come visualizzare i controlli dei dispositivi in questo spazio e collegarli all'app di controllo.
Per aggiungere questo supporto, crea e dichiara un ControlsProviderService
. Crea i controlli supportati dalla tua app in base ai tipi di controllo predefiniti, quindi crea i publisher per questi controlli.
Interfaccia utente
I dispositivi vengono visualizzati nella sezione Controlli dispositivo come widget basati su modelli. Sono disponibili cinque widget di controllo dei dispositivi, come mostrato nella figura che segue:
![]() |
![]() |
![]() |
![]() |
![]() |
Toccando e tenendo premuto un widget, si aprirà l'app per un controllo maggiore. Puoi personalizzare l'icona e il colore di ogni widget, ma per un'esperienza utente ottimale, utilizza l'icona e il colore predefiniti se l'insieme predefinito corrisponde al dispositivo.
![Un'immagine che mostra il widget del riquadro della temperatura (aperto)](https://developer.android.com/static/images/device-control/device-control-panel2.png?authuser=9&hl=it)
Crea il servizio
Questa sezione mostra come creare ControlsProviderService
.
Questo servizio indica all'interfaccia utente del sistema Android che la tua app contiene controlli dei dispositivi che devono essere visualizzati nell'area Controlli dispositivo dell'interfaccia utente di Android.
L'API ControlsProviderService
presuppone di avere dimestichezza con i flussi reattivi, come definito nel progetto GitHub di Reactive Streams e implementato nelle interfacce Java 9 Flow.
L'API si basa sui seguenti concetti:
- Publisher: la tua applicazione è il publisher.
- Abbonato: l'interfaccia utente di sistema è l'abbonato e può richiedere una serie di controlli all'editore.
- Abbonamento: il periodo di tempo durante il quale l'editore può inviare aggiornamenti all'interfaccia utente di sistema. Sia l'editore che il sottoscrittore possono chiudere questa finestra.
Dichiara il servizio
La tua app deve dichiarare un servizio, ad esempio MyCustomControlService
, nel file manifest dell'app.
Il servizio deve includere un filtro per intent per ControlsProviderService
. Questo filtro consente alle applicazioni di contribuire ai controlli dell'interfaccia utente di sistema.
È necessario anche un label
che venga visualizzato nei controlli dell'interfaccia utente di sistema.
L'esempio seguente mostra come dichiarare un servizio:
<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>
Quindi, crea un nuovo file Kotlin denominato MyCustomControlService.kt
e amplialo ControlsProviderService()
:
Kotlin
class MyCustomControlService : ControlsProviderService() { ... }
Java
public class MyCustomJavaControlService extends ControlsProviderService { ... }
Seleziona il tipo di controllo corretto
L'API fornisce metodi del builder per creare i controlli. Per completare il generatore, determina il dispositivo che vuoi controllare e il modo in cui l'utente vi interagisce. Svolgi i seguenti passaggi:
- Scegli il tipo di dispositivo rappresentato dal controllo. La classe
DeviceTypes
è un'enumerazione di tutti i dispositivi supportati. Il tipo consente di determinare le icone e i colori del dispositivo nell'interfaccia utente. - Determina il nome rivolto agli utenti, la posizione del dispositivo, ad esempio cucina, e altri elementi di testo dell'interfaccia utente associati al controllo.
- Scegli il modello migliore per favorire l'interazione degli utenti. Ai controlli viene assegnato un valore
ControlTemplate
dall'applicazione. Questo modello mostra direttamente all'utente lo stato del controllo e i metodi di input disponibili, ovveroControlAction
. La seguente tabella descrive alcuni dei modelli disponibili e le azioni che supportano:
Modello | Azione | Descrizione |
ControlTemplate.getNoTemplateObject()
|
None
|
L'applicazione potrebbe utilizzarlo per trasmettere informazioni sul controllo, ma l'utente non può interagire con quest'ultimo. |
ToggleTemplate
|
BooleanAction
|
Rappresenta un controllo che può essere alternato tra lo stato Attivato e Disattivato. L'oggetto BooleanAction contiene un campo che cambia
per rappresentare il nuovo stato richiesto quando l'utente tocca il controllo.
|
RangeTemplate
|
FloatAction
|
Rappresenta un widget del dispositivo di scorrimento con i valori minimo, massimo e passo specificato. Quando l'utente interagisce con il cursore, invia un nuovo oggetto FloatAction all'applicazione con il valore aggiornato.
|
ToggleRangeTemplate
|
BooleanAction, FloatAction
|
Questo modello è una combinazione di ToggleTemplate e
RangeTemplate . Supporta gli eventi touch e un dispositivo di scorrimento, ad esempio per controllare le luci dimmerabili.
|
TemperatureControlTemplate
|
ModeAction, BooleanAction, FloatAction
|
Oltre a racchiudere le azioni precedenti, questo modello consente all'utente di impostare una modalità, ad esempio Caldo, Freddo, Caldo/Freddo, Eco o Spento. |
StatelessTemplate
|
CommandAction
|
Utilizzato per indicare un controllo che offre funzionalità touch, ma il cui stato non può essere determinato, ad esempio un telecomando a infrarossi. Puoi utilizzare questo modello per definire una routine o una macro, ovvero un'aggregazione delle modifiche dei controlli e dello stato. |
Con queste informazioni puoi creare il controllo:
- Utilizza la classe del builder
Control.StatelessBuilder
quando lo stato del controllo è sconosciuto. - Utilizza la classe del builder
Control.StatefulBuilder
quando lo stato del controllo è noto.
Ad esempio, per controllare una lampadina smart e un termostato, aggiungi
le seguenti costanti a 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; ... }
Creare publisher per i controlli
Dopo averlo creato, il controllo ha bisogno di un publisher. L'editore informa l'interfaccia utente di sistema dell'esistenza del controllo. La classe ControlsProviderService
ha due metodi del publisher che devi sostituire nel codice dell'applicazione:
createPublisherForAllAvailable()
: crea unPublisher
per tutti i controlli disponibili nella tua app. UsaControl.StatelessBuilder()
per creareControl
oggetti per questo publisher.createPublisherFor()
: crea unPublisher
per un elenco di determinati controlli, come identificati dai relativi identificatori di stringa. UtilizzaControl.StatefulBuilder
per creare questi oggettiControl
, poiché il publisher deve assegnare uno stato a ogni controllo.
Creare il publisher
Quando l'app pubblica per la prima volta controlli nell'interfaccia utente di sistema, l'app non conosce lo stato di ogni controllo. Ottenere lo stato può essere un'operazione
dispendiosa in termini di tempo, che prevede molti hop nella rete del provider di dispositivi. Utilizza il metodo
createPublisherForAllAvailable()
per pubblicizzare al sistema i controlli disponibili. Questo metodo utilizza la classe builder Control.StatelessBuilder
, poiché lo stato di ogni controllo è sconosciuto.
Una volta che i controlli vengono visualizzati nell'interfaccia utente di Android , l'utente può selezionare i controlli preferiti.
Per utilizzare le coroutine Kotlin per creare un ControlsProviderService
, aggiungi una nuova
dipendenza a build.gradle
:
trendy
dependencies { implementation "org.jetbrains.kotlinx:kotlinx-coroutines-jdk9:1.6.4" }
Kotlin
dependencies { implementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk9:1.6.4") }
Dopo aver sincronizzato i file Gradle, aggiungi il seguente snippet a Service
per implementare 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> 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); } }
Scorri verso il basso sul menu di sistema e individua il pulsante Controlli dispositivo, mostrato nella Figura 4:
![Un'immagine che mostra l'UI di sistema per i controlli dei dispositivi](https://developer.android.com/static/images/ui/device_controls_ui.png?authuser=9&hl=it)
Toccando Controlli dispositivo, si apre una seconda schermata in cui puoi selezionare l'app. Una volta selezionata l'app, vedrai come lo snippet precedente crea un menu di sistema personalizzato con i nuovi controlli, come mostrato nella figura 5:
![Un'immagine che mostra il menu di sistema contenente una luce e il controllo del termostato](https://developer.android.com/static/images/ui/device_controls_example_1.png?authuser=9&hl=it)
Ora implementa il metodo createPublisherFor()
, aggiungendo quanto segue a Service
:
Kotlin
private val job = SupervisorJob() private val scope = CoroutineScope(Dispatchers.IO + job) private val controlFlows = mutableMapOf>() 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(); }
In questo esempio, il metodo createPublisherFor()
contiene un'implementazione falsa di ciò che deve fare la tua app: comunicare con il dispositivo per recuperarne lo stato ed emettere questo stato al sistema.
Il metodo createPublisherFor()
utilizza coroutine e flussi Kotlin per soddisfare
l'API Reactive Streams richiesta seguendo questi passaggi:
- Crea un
Flow
. - Attende un secondo.
- Crea ed emette lo stato della luce smart.
- Attende un altro secondo.
- Crea ed emette lo stato del termostato.
Gestisci le azioni
Il metodo performControlAction()
segnala quando l'utente interagisce con un
controllo pubblicato. Il tipo di ControlAction
inviato determina l'azione.
Esegui l'azione appropriata per il controllo specificato, quindi aggiorna lo stato del dispositivo nella UI di Android.
Per completare l'esempio, aggiungi quanto segue a 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()); } }
Esegui l'app, accedi al menu Controlli del dispositivo e visualizza i controlli della lampadina e del termostato.
![Un'immagine che mostra una luce e un controllo del termostato](https://developer.android.com/static/images/ui/device_controls_example_2.png?authuser=9&hl=it)