Crea un metodo di immissione

Un editor di metodi di inserimento (IME) è un controllo utente che consente agli utenti di inserire del testo. Android fornisce un framework di metodi di inserimento estendibile che consente alle applicazioni di offrire agli utenti metodi di inserimento alternativi, come le tastiere sullo schermo o l'inserimento vocale. Dopo aver installato gli IME, l'utente può selezionarne uno le impostazioni di sistema e utilizzarle in tutto il sistema. È possibile attivare un solo IME alla volta.

Per aggiungere un IME al sistema Android, crea un'applicazione Android contenente una classe si estende InputMethodService. Inoltre, solitamente crei "impostazioni" l'attività che trasmette opzioni al servizio IME. Tu puoi anche definire una UI delle impostazioni che viene visualizzata nelle impostazioni di sistema.

Questa pagina tratta i seguenti argomenti:

Se non hai utilizzato gli IME, leggi l'articolo introduttivo Metodi di immissione sullo schermo per prima cosa.

Ciclo di vita dell'IME

Il seguente diagramma descrive il ciclo di vita di un IME:

Un'immagine che mostra il ciclo di vita di un IME.
Figura 1. Il ciclo di vita di un IME.

Le seguenti sezioni descrivono come implementare l'interfaccia utente e il codice associati a un IME che segue questo ciclo di vita.

Dichiara i componenti IME nel file manifest

Nel sistema Android, un IME è un'applicazione Android che contiene un servizio IME speciale. Il file manifest dell'applicazione deve dichiarare il servizio, richiedere le autorizzazioni necessarie, fornire un filtro per intent che corrisponda all'azione action.view.InputMethod e fornire metadati che definiscono le caratteristiche dell'IME. Inoltre, per fornire un'interfaccia di impostazioni che consente modificare il comportamento dell'IME, è possibile definire "impostazioni" dell'attività che può essere avviata Impostazioni di sistema.

Lo snippet seguente dichiara un servizio IME. Richiede l'autorizzazione BIND_INPUT_METHOD per consentire al servizio di connettere l'IME al sistema, configura un filtro per intent corrispondente all'azione android.view.InputMethod e definisce i metadati per l'IME:

<!-- Declares the input method service. -->
<service android:name="FastInputIME"
    android:label="@string/fast_input_label"
    android:permission="android.permission.BIND_INPUT_METHOD">
    <intent-filter>
        <action android:name="android.view.InputMethod" />
    </intent-filter>
    <meta-data android:name="android.view.im"
               android:resource="@xml/method" />
</service>

Lo snippet successivo dichiara l'attività di impostazioni per l'IME. Ha un filtro per intent per ACTION_MAIN che indica che questa attività è il punto di contatto principale per l'applicazione IME:

<!-- Optional: an activity for controlling the IME settings. -->
<activity android:name="FastInputIMESettings"
    android:label="@string/fast_input_settings">
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
    </intent-filter>
</activity>

Puoi anche fornire l'accesso alle impostazioni dell'IME direttamente dalla relativa UI.

L'API del metodo di input

Le classi specifiche per le IME si trovano nei pacchetti android.inputmethodservice e android.view.inputmethod. Il corso KeyEvent è è importante per la gestione dei caratteri della tastiera.

La parte centrale di un IME è un componente di servizio, una classe che si estende InputMethodService. Oltre a implementare il normale ciclo di vita del servizio, dispone di callback per fornire l'interfaccia utente dell'IME, gestire l'input utente e inviare testo al campo attivo. Per impostazione predefinita, la classe InputMethodService fornisce la maggior parte delle implementazione per gestire lo stato e la visibilità dell'IME e comunicare con il campo di immissione.

Sono importanti anche le seguenti classi:

BaseInputConnection
Definisce il canale di comunicazione da un InputMethod all'applicazione che riceve il suo input. Puoi utilizzarlo per leggere il testo intorno alla il cursore, eseguire il commit del testo nella casella di testo e inviare gli eventi chiave non elaborati all'applicazione. Le applicazioni devono estendere questa classe anziché implementare l'interfaccia di base InputConnection.
KeyboardView
Un'estensione di View che esegue il rendering di una tastiera e risponde agli eventi di input dell'utente. Il layout della tastiera è specificato da un'istanza di Keyboard, che puoi definire in un file XML.

Progetta l'interfaccia utente del metodo di inserimento

Esistono due elementi visivi principali per un IME: la visualizzazione di input e la visualizzazione di candidati. Devi implementare solo gli elementi pertinenti al metodo di inserimento che stai progettando.

Visualizzazione immissione

La visualizzazione degli input è la UI in cui l'utente inserisce il testo sotto forma di clic sui tasti, scrittura a mano libera o gesti. Quando l'IME viene visualizzato per la prima volta, il sistema chiama il callback onCreateInputView(). Nell'implementazione di questo metodo, crea il layout che vuoi visualizzare nella finestra dell'IME e restituiscilo al sistema. Lo snippet seguente mostra un esempio di implementazione del metodo onCreateInputView():

Kotlin

override fun onCreateInputView(): View {
    return layoutInflater.inflate(R.layout.input, null).apply {
        if (this is MyKeyboardView) {
            setOnKeyboardActionListener(this@MyInputMethod)
            keyboard = latinKeyboard
        }
    }
}

Java

@Override
public View onCreateInputView() {
    MyKeyboardView inputView =
        (MyKeyboardView) getLayoutInflater().inflate(R.layout.input, null);

    inputView.setOnKeyboardActionListener(this);
    inputView.setKeyboard(latinKeyboard);

    return inputView;
}

In questo esempio, MyKeyboardView è un'istanza di un'implementazione personalizzata di KeyboardView che esegue il rendering di un Keyboard.

Visualizzazione candidati

La visualizzazione candidati è l'interfaccia utente in cui l'IME mostra potenziali correzioni o suggerimenti di parole che l'utente può selezionare. Nel ciclo di vita dell'IME, il sistema chiama onCreateCandidatesView() quando è pronto per visualizzare la visualizzazione dei candidati. Nell'implementazione di questo metodo, restituisci un layout che mostri i suggerimenti di parole o restituisci null se non vuoi mostrare nulla. Una risposta null è il comportamento predefinito, quindi non devi implementarla se non fornisci suggerimenti.

Considerazioni sul design dell'interfaccia utente

Questa sezione descrive alcune considerazioni sul design dell'interfaccia utente per gli IME.

Gestione di più dimensioni dello schermo

L'interfaccia utente dell'IME deve poter adattarsi a schermi di diverse dimensioni e gestire sia l'orientamento orizzontale orientamenti verticali. In modalità IME non a schermo intero, lascia spazio sufficiente per consentire all'applicazione di mostrare il campo di testo e l'eventuale contesto associato, in modo che l'IME non occupi più della metà dello schermo. In modalità IME a schermo intero, questo non è un problema.

Gestione di diversi tipi di input

I campi di testo Android ti consentono di impostare un tipo di input specifico, ad esempio testo in formato libero, numeri, URL, indirizzi email e stringhe di ricerca. Quando implementi un nuovo IME, rileva il tipo di input di ogni e a fornire l'interfaccia appropriata. Tuttavia, non devi configurare l'IME per controlla se l'utente inserisce un testo valido per il tipo di input. È responsabilità dell'applicazione proprietaria del campo di testo.

Ad esempio, ecco l'interfaccia fornita dall'IME latino per il testo della piattaforma Android input:

Un&#39;immagine che mostra un input di testo su un IME latino
Figura 2. Input di testo IME latino.

Ecco l'interfaccia fornita dall'IME latino per l'inserimento numerico sulla piattaforma Android:

Un&#39;immagine che mostra un input numerico su un IME latino
Figura 3. Immissione numerica con IME latino.

Quando un campo di immissione viene attivato e l'IME viene avviato, il sistema chiama onStartInputView(), passando un Oggetto EditorInfo contenente i dettagli sul tipo di input e altri attributi del campo di testo. In questo oggetto, il inputType contiene il tipo di input del campo di testo.

Il campo inputType è un int che contiene pattern di bit per varie impostazioni del tipo di input. Per testare il tipo di input del campo di testo, mascheralo con la costante TYPE_MASK_CLASS, nel seguente modo:

Kotlin

inputType and InputType.TYPE_MASK_CLASS

Java

inputType & InputType.TYPE_MASK_CLASS

Il pattern di bit del tipo di input può avere uno di diversi valori, tra cui:

TYPE_CLASS_NUMBER
Un campo di testo per l'inserimento di numeri. Come illustrato nella figura 3, l'IME latino mostra un tastierino numerico per i campi di questo tipo.
TYPE_CLASS_DATETIME
Un campo di testo per inserire una data e un'ora.
TYPE_CLASS_PHONE
Un campo di testo per inserire i numeri di telefono.
TYPE_CLASS_TEXT
Un campo di testo per inserire qualsiasi carattere supportato.

Queste costanti sono descritte in maggiore dettaglio nella documentazione di riferimento perInputType.

Il campo inputType può contenere altri bit che indicano una variante del tipo di campo di testo, ad esempio:

TYPE_TEXT_VARIATION_PASSWORD
Una variante di TYPE_CLASS_TEXT per l'inserimento delle password. Il metodo di inserimento mostra simboli anziché il testo effettivo.
TYPE_TEXT_VARIATION_URI
Una variante di TYPE_CLASS_TEXT per inserire URL web e altri Uniform Resource Identifier (URI).
TYPE_TEXT_FLAG_AUTO_COMPLETE
Una variante di TYPE_CLASS_TEXT per inserire il testo che l'applicazione completa automaticamente da un dizionario, una ricerca o un'altra funzionalità.

Maschera inputType con la costante appropriata quando esegui il test per queste varianti. Le costanti della maschera disponibili sono elencate nella documentazione di riferimento di InputType.

Invia testo all'applicazione

Quando l'utente inserisce testo con il tuo IME, puoi inviare testo all'applicazione inviando singole eventi chiave o modificando il testo attorno al cursore nel campo di testo dell'applicazione. In entrambi i casi, utilizza un'istanza di InputConnection per inviare il testo. Per ottenere questa istanza, chiama InputMethodService.getCurrentInputConnection().

Modificare il testo attorno al cursore

Quando gestisci la modifica del testo esistente, alcuni metodi utili in BaseInputConnection sono i seguenti:

getTextBeforeCursor()
Restituisce un CharSequence contenente il numero di caratteri richiesti prima della posizione corrente del cursore.
getTextAfterCursor()
Restituisce un CharSequence contenente il numero di caratteri richiesti successivi alla posizione corrente del cursore.
deleteSurroundingText()
Elimina il numero specificato di caratteri prima e dopo la posizione corrente del cursore.
commitText()
Esegue il commit di un CharSequence nel campo di testo e imposta una nuova posizione del cursore.

Ad esempio, lo snippet seguente mostra come sostituire i quattro caratteri a sinistra del cursore con il testo "Ciao!":

Kotlin

currentInputConnection.also { ic: InputConnection ->
    ic.deleteSurroundingText(4, 0)
    ic.commitText("Hello", 1)
    ic.commitText("!", 1)
}

Java

InputConnection ic = getCurrentInputConnection();
ic.deleteSurroundingText(4, 0);
ic.commitText("Hello", 1);
ic.commitText("!", 1);

Supporto della scrittura del testo prima di impegnarsi

Se l'IME prevede il testo o richiede più passaggi per comporre un glifo o una parola, puoi mostrare lo stato di avanzamento nel campo di testo finché l'utente non conferma la parola, dopodiché puoi sostituire la composizione parziale con il testo completato. Puoi applicare un trattamento speciale al testo aggiungendo un elemento span quando lo passi a setComposingText().

Il seguente snippet mostra come mostrare l'avanzamento in un campo di testo:

Kotlin

currentInputConnection.also { ic: InputConnection ->
    ic.setComposingText("Composi", 1)
    ic.setComposingText("Composin", 1)
    ic.commitText("Composing ", 1)
}

Java

InputConnection ic = getCurrentInputConnection();
ic.setComposingText("Composi", 1);
ic.setComposingText("Composin", 1);
ic.commitText("Composing ", 1);

Intercetta eventi chiave hardware

Anche se la finestra del metodo di immissione non ha uno stato attivo esplicito, riceve eventi chiave hardware. e può utilizzarli o inoltrarli all'applicazione. Ad esempio, potresti voler utilizza i tasti direzionali per navigare all'interno dell'interfaccia utente per la selezione del candidato durante la composizione. Potresti anche voler bloccare il tasto Indietro per chiudere le eventuali finestre di dialogo che hanno origine dal metodo di inserimento. finestra.

Per intercettare le chiavi hardware, sostituisci onKeyDown() e onKeyUp().

Chiama il metodo super() per le chiavi che non vuoi gestire autonomamente.

Crea un sottotipo di IME

I sottotipi consentono all'IME di esporre più modalità di input e lingue supportate da un IME. Un sottotipo può rappresentano quanto segue:

  • Una lingua, ad esempio en_US o fr_FR
  • Una modalità di immissione, ad esempio voce, tastiera o scrittura a mano libera
  • Altri stili di input, moduli o proprietà specifici dell'IME, come i layout tastiera con 10 tasti o QWERTY

La modalità può essere qualsiasi testo, ad esempio "tastiera" o "voce". Un sottotipo può anche esporre una combinazione di questi.

Le informazioni sul sottotipo vengono utilizzate per una finestra di dialogo di commutazione dell'IME disponibile nella barra delle notifiche e per le impostazioni dell'IME. Le informazioni consentono inoltre al framework di visualizzare un sottotipo specifico di IME . Quando crei un IME, utilizza la funzionalità di sottotipo perché aiuta l'utente a identificare e passare da un linguaggio IME e da una modalità all'altra.

Definisci i sottotipi in uno dei file di risorse XML del metodo di input utilizzando il metodo Elemento <subtype>. Il seguente snippet di codice definisce un IME con due sottotipi: sottotipo di tastiera per l'impostazione internazionale dell'inglese americano e un altro sottotipo di tastiera per la lingua francese impostazioni internazionali della Francia:

<input-method xmlns:android="http://schemas.android.com/apk/res/android"
        android:settingsActivity="com.example.softkeyboard.Settings"
        android:icon="@drawable/ime_icon">
    <subtype android:name="@string/display_name_english_keyboard_ime"
            android:icon="@drawable/subtype_icon_english_keyboard_ime"
            android:languageTag="en-US"
            android:imeSubtypeMode="keyboard"
            android:imeSubtypeExtraValue="somePrivateOption=true" />
    <subtype android:name="@string/display_name_french_keyboard_ime"
            android:icon="@drawable/subtype_icon_french_keyboard_ime"
            android:languageTag="fr-FR"
            android:imeSubtypeMode="keyboard"
            android:imeSubtypeExtraValue="someVariable=30,someInternalOption=false" />
    <subtype android:name="@string/display_name_german_keyboard_ime" ... />
</input-method>

Per assicurarti che i tuoi sottotipi siano etichettati correttamente nell'interfaccia utente, usa "%s" per ottenere un'etichetta di sottotipo che corrisponde all'etichetta di impostazioni internazionali del sottotipo. Questo è dimostrato nei due snippet di codice successivi. La il primo snippet mostra parte del file XML del metodo di inserimento:

<subtype
    android:label="@string/label_subtype_generic"
    android:imeSubtypeLocale="en_US"
    android:icon="@drawable/icon_en_us"
    android:imeSubtypeMode="keyboard" />

Lo snippet successivo fa parte del file strings.xml dell'IME. La risorsa stringa label_subtype_generic, utilizzata dalla definizione dell'interfaccia utente del metodo di inserimento per impostare la dell'etichetta del sottotipo, è definita come segue:

<string name="label_subtype_generic">%s</string>

Con questa impostazione, il nome visualizzato del sottotipo corrisponde alle impostazioni internazionali. Ad esempio, in qualsiasi Impostazioni internazionali dell'inglese, il nome visualizzato è "Inglese (Stati Uniti)".

Scegliere i sottotipi di IME dalla barra delle notifiche

Il sistema Android gestisce tutti i sottotipi esposti da tutti gli IME. I sottotipi IME vengono trattati come modalità all'IME a cui appartengono. L'utente può passare dalla barra delle notifiche o dall'app Impostazioni a un dei sottotipi IME disponibili, come mostrato nella figura seguente:

Un&#39;immagine che mostra il menu Sistema Lingue e immissione
Figura 4. Il menu di sistema Lingue e immissione.

Scegli i sottotipi IME dalle impostazioni di sistema

L'utente può anche controllare il modo in cui vengono utilizzati i sottotipi nel riquadro delle impostazioni Lingua e inserimento nelle impostazioni di sistema:

Un&#39;immagine che mostra il menu di selezione delle lingue
Figura 5. Il menu di sistema Lingue

Passare da un sottotipo di IME all'altro

Puoi consentire agli utenti di passare facilmente da un sottotipo di IME all'altro fornendo un tasto di attivazione/disattivazione, ad esempio l'icona della lingua a forma di globo sulla tastiera. In questo modo, la tastiera è più facile da usare e comoda per l'utente. Per attivare questo passaggio:

  1. Dichiara supportsSwitchingToNextInputMethod = "true" nel codice XML del metodo di inserimento di risorse. La tua dichiarazione deve avere un aspetto simile al seguente snippet di codice: 
    <input-method xmlns:android="http://schemas.android.com/apk/res/android"
        android:settingsActivity="com.example.softkeyboard.Settings"
        android:icon="@drawable/ime_icon"
        android:supportsSwitchingToNextInputMethod="true">
  2. Chiama il metodo shouldOfferSwitchingToNextInputMethod().
  3. Se il metodo restituisce true, mostra un tasto di attivazione/disattivazione.
  4. Quando l'utente tocca il tasto di attivazione/disattivazione, chiama switchToNextInputMethod(), passando false. Un valore false indica al sistema di trattare tutti i sottotipi allo stesso modo, indipendentemente dall'IME a cui appartengono. Se specifichi true, il sistema deve scorrere i sottotipi nell'IME corrente.

Considerazioni generali sull'IME

Di seguito sono riportati altri aspetti da considerare durante l'implementazione dell'IME:

  • Offri agli utenti un modo per impostare le opzioni direttamente dall'interfaccia utente dell'IME.
  • Fornisci agli utenti un modo per passare a un IME diverso direttamente dall'interfaccia utente del metodo di inserimento, perché sul dispositivo potrebbero essere installati più IME.
  • Visualizza rapidamente l'interfaccia utente dell'IME. Precarica o carica on demand risorse di grandi dimensioni in modo che gli utenti visualizzare l'IME non appena toccano un campo di testo. Memorizza nella cache risorse e viste per le successive del metodo di input.
  • Libera allocazioni di memoria di grandi dimensioni subito dopo aver nascosto la finestra del metodo di inserimento, in modo che le applicazioni abbiano memoria sufficiente per funzionare. Utilizza un messaggio in ritardo per rilasciare risorse se l'IME è nascosto per qualche secondo.
  • Assicurati che gli utenti possano inserire il maggior numero possibile di caratteri per la lingua o le impostazioni internazionali associate all'IME. Gli utenti potrebbero utilizzare la punteggiatura nelle password o nei nomi utente, quindi l'IME deve fornire molti caratteri diversi per consentire agli utenti di inserire una password e accedere dispositivo.