Questa pagina è stata tradotta dall'API Cloud Translation.

Controllare i dispositivi esterni

In Android 11 e versioni successive, la funzionalità Controllo rapido dei dispositivi consente all'utente di visualizzare e controllare rapidamente dispositivi esterni come luci, termostati e videocamere da un invito dell'utente entro tre interazioni da un Avvio app predefinito. L'OEM del dispositivo sceglie quale Avvio app utilizzare. Dispositivo gli aggregatori, ad esempio Google Home, e le app di fornitori di terze parti possono forniscono dispositivi per la visualizzazione in questo spazio. Questa pagina mostra come visualizzare i controlli dei dispositivi in questo spazio e collegarli all'app di controllo.

Figura 1. Spazio di controllo del dispositivo nell'UI di Android.

Per aggiungere questo supporto, crea e dichiara un ControlsProviderService. Crea i controlli supportati dalla tua app in base a tipi di controllo predefiniti, quindi crea i publisher per questi controlli.

Interfaccia utente

I dispositivi vengono visualizzati in Controllo dispositivi come widget basati su modelli. Cinque sono disponibili widget di controllo del dispositivo, come mostrato nella figura seguente:

Attiva/disattiva	Attiva/disattiva con il cursore	Intervallo (non può essere attivato o disattivato)
Pulsante di attivazione/disattivazione senza stato	Riquadro della temperatura (chiuso)

Figura 2. Raccolta di widget basati su modelli.

Toccante e tieni premuto un widget per accedere all'app per un controllo più approfondito. 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) — **Figura 3.** Apri il widget del riquadro della temperatura.

Crea il servizio

Questa sezione illustra come creare ControlsProviderService Questo servizio indica all'interfaccia utente di sistema di Android che la tua app contiene controlli del dispositivo che devono essere visualizzati nell'area Controlli dispositivo dell'interfaccia utente di Android.

L'API ControlsProviderService presuppone la familiarità con gli stream reattivi, poiché definita nel documento Reactive Streams GitHub progetto e implementato nel Java 9 Flow di programmazione di applicazioni. L'API si basa sui seguenti concetti:

Editore: la tua applicazione è l'editore.
Abbonato: l'interfaccia utente di sistema corrisponde all'abbonato e può richiedere un numero di controlli da parte del publisher.
Abbonamento: il periodo di tempo durante il quale il publisher può inviare aggiornamenti all'interfaccia utente di sistema. Il publisher o l'abbonato possono chiudere questa finestra.

Dichiara il servizio

La tua app deve dichiarare un servizio, ad esempio MyCustomControlService, in del file manifest dell'app.

Il servizio deve includere un filtro per intent per ControlsProviderService. Questo filtro consente alle applicazioni di aggiungere controlli all'interfaccia utente di sistema.

Inoltre, devi avere un label 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>

Ora crea un nuovo file Kotlin denominato MyCustomControlService.kt e crealo estendere 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 compilare il Builder, determinano il dispositivo che vuoi controllare e il modo in cui l'utente interagisce con essa. Procedi nel seguente modo:

Scegli il tipo di dispositivo rappresentato dal controllo. La Il corso DeviceTypes è un l'enumerazione di tutti i dispositivi supportati. Il tipo viene utilizzato per determinare le icone e i colori del dispositivo nell'interfaccia utente.
Determina il nome rivolto all'utente, la posizione del dispositivo (ad esempio cucina) e altri elementi di testo dell'interfaccia utente associati al controllo.
Scegli il modello migliore per supportare l'interazione con l'utente. I controlli vengono assegnati a un ControlTemplate dall'applicazione. Questo modello mostra direttamente lo stato del controllo dell'utente e ai metodi di immissione disponibili, ovvero ControlAction La tabella seguente illustra alcuni dei modelli disponibili e le azioni supportate:

Modello	Azione	Descrizione
`ControlTemplate.getNoTemplateObject()`	`None`	L'applicazione potrebbe utilizzarlo per trasmettere informazioni sul controllo, ma l'utente non può interagire con esso.
`ToggleTemplate`	`BooleanAction`	Rappresenta un controllo che può essere attivato o disattivato. stati. 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 dispositivo di scorrimento con valori minimo, massimo e passo specificati. 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 eventi touch, nonché un cursore, ad esempio per controllare le luci regolabili.
`TemperatureControlTemplate`	`ModeAction, BooleanAction, FloatAction`	Oltre a incapsulare 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, come nel caso di un telecomando IR. Puoi utilizzare questo modello per definire una routine o una macro, ovvero un'aggregazione di controlli e modifiche dello stato.

Con queste informazioni, puoi creare il controllo:

Utilizza la Control.StatelessBuilder Builder quando lo stato del controllo è sconosciuto.
Utilizza la Control.StatefulBuilder Builder quando lo stato del controllo è noto.

Ad esempio, per controllare una lampadina smart e un termostato, aggiungi quanto segue costanti su 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 aver creato il controllo, hai bisogno di un publisher. Il publisher informa di sistema dell'esistenza del controllo. La classe ControlsProviderService ha due metodi del publisher che devi sostituire nel codice dell'applicazione:

createPublisherForAllAvailable(): crea un Publisher per tutti i controlli disponibili nella tua app. Utilizza Control.StatelessBuilder() per creare oggetti Control per questo publisher.
createPublisherFor(): crea un Publisher per un elenco di controlli specifici, identificati dai relativi identificatori di stringa. Usa Control.StatefulBuilder per crea questi oggetti Control, poiché il publisher deve assegnare uno stato per ciascun controllo.

Crea il publisher

Quando la tua app pubblica per la prima volta i controlli nell'UI di sistema, l'app non sa lo stato di ogni controllo. L'ottenimento dello stato può essere un'operazione che richiede tempo e che coinvolge molti hop nella rete del fornitore del dispositivo. Utilizza il metodo createPublisherForAllAvailable() per pubblicizzare i controlli disponibili al sistema. Questo metodo utilizza la Control.StatelessBuilder classe del generatore, poiché lo stato di ciascun controllo è sconosciuto.

Una volta visualizzati i controlli nell'interfaccia utente di Android, l'utente può selezionare i controlli preferiti.

Per utilizzare le coroutine Kotlin per creare un ControlsProviderService, aggiungi una nuova della dipendenza da 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")
}

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<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);
        }
    }

Scorri verso il basso nel menu di sistema e individua il pulsante Controlli dispositivo, mostrato nella Figura 4:

Un'immagine che mostra l'interfaccia utente di sistema per i controlli del dispositivo — **Figura 4.** Controllo dei dispositivi nel menu di sistema.

Se tocchi Controlli dei dispositivi, si apre una seconda schermata in cui puoi selezionare la tua app. Una volta selezionata l'app, vedrai come lo snippet precedente crea un menu di sistema personalizzato che mostra i nuovi controlli, come mostrato nella figura 5:

Un'immagine che mostra il menu di sistema contenente un controllo della luce e del termostato — **Figura 5.** Controlli per luci e termostati da aggiungere.

Ora implementa il metodo createPublisherFor(), aggiungendo quanto segue alla sezione 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.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);
    }
 
    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 falso implementazione di ciò che la tua app deve fare: comunicare con il tuo dispositivo per recuperarne lo stato e trasmetterlo al sistema.

Il metodo createPublisherFor() utilizza le coroutine e i flussi di Kotlin per soddisfare l'API Reactive Streams richiesta nel seguente modo:

Crea un Flow.
Aspetta un secondo.
Crea ed emette lo stato della luce smart.
Aspetta un altro secondo.
Crea ed emette lo stato del termostato.

Azioni dell'handle

Il metodo performControlAction() segnala quando l'utente interagisce con un e il controllo pubblicato. Il tipo di ControlAction inviato determina l'azione. Esegui l'azione appropriata per il controllo specificato, quindi aggiorna lo stato del dispositivo nell'interfaccia utente 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 Consumer consumer) {
        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 Controllo dispositivi e osserva la lampadina e i controlli del termostato.

Un'immagine che mostra una luce e un controllo del termostato — **Figura 6.** Controlli di illuminazione e termostato.