Créer un mode de saisie

Un éditeur de mode de saisie (IME) est une commande qui permet aux utilisateurs de saisir du texte. Android fournit un framework extensible de saisie qui permet aux applications de proposer aux utilisateurs d'autres méthodes de saisie, telles que les claviers à l'écran ou la saisie vocale. Après avoir installé les IME, l'utilisateur peut en sélectionner un dans les paramètres système et l'utiliser dans l'ensemble du système. Vous ne pouvez activer qu'un seul IME à la fois.

Pour ajouter un IME au système Android, créez une application Android contenant une classe qui étend InputMethodService En outre, vous créez généralement une activité "paramètres" qui transmet des options au service IME. Vous pouvez également définir une UI de paramètres qui s'affiche dans les paramètres système.

Cette page aborde les sujets suivants :

• Cycle de vie de l'IME
• Déclarer des composants IME dans le fichier manifeste de l'application
• API IME
• Concevoir une UI d'IME
• Envoyer du texte à une application à partir d'un IME
• Utiliser des sous-types d'IME
• Autres points à prendre en compte concernant les IME

Si vous n'avez jamais travaillé avec des IME, commencez par lire l'article introductif Modes de saisie à l'écran.

Remarque : À partir d'Android 11, la plate-forme permet aux IME d'afficher des suggestions de saisie automatique intégrées au lieu d'utiliser un menu déroulant. Pour en savoir plus sur la compatibilité des services de saisie automatique avec cette fonctionnalité, consultez comment intégrer la saisie automatique à votre IME.

Cycle de vie des IME

Le schéma suivant décrit le cycle de vie d'un IME:

Figure 1 : Cycle de vie d'un IME

Les sections suivantes expliquent comment implémenter l'UI et le code associés à un IME qui suit ce cycle de vie.

Déclarer les composants IME dans le fichier manifeste

Dans le système Android, un IME est une application Android qui contient un service IME spécial. Le fichier manifeste de l'application doit déclarer le service, demander les autorisations nécessaires, fournir un filtre d'intent correspondant à l'action action.view.InputMethod et fournir des métadonnées qui définissent les caractéristiques de l'IME. En outre, pour fournir une interface de configuration qui permet au modifier le comportement de l'IME, vous pouvez définir un "paramètre" qui peut être lancée depuis Paramètres système.

L'extrait de code suivant déclare un service IME. Il demande l'autorisation BIND_INPUT_METHOD pour permettre au service de connecter l'IME au système, configure un filtre d'intent correspondant à l'action android.view.InputMethod et définit des métadonnées pour 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>

L'extrait de code suivant déclare l'activité de paramètres pour le IME. Il comporte un filtre d'intent pour ACTION_MAIN qui indique que cette activité est le point d'entrée principal de l'application 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>

Vous pouvez également fournir l'accès aux paramètres de l'IME directement depuis son interface utilisateur.

API de méthode d'entrée

Les classes spécifiques aux IME se trouvent dans le android.inputmethodservice et android.view.inputmethod packages. La classe KeyEvent est important pour la gestion des caractères du clavier.

La partie centrale d'un IME est un composant de service, une classe qui étend InputMethodService En plus de mettre en œuvre le cycle de vie normal du service, comporte des rappels permettant de fournir l'interface utilisateur de l'IME, de gérer les entrées utilisateur et d'envoyer du texte au qui est ciblé. Par défaut, la classe InputMethodService fournit la majeure partie de l'implémentation pour gérer l'état et la visibilité de l'IME, et pour communiquer avec le champ de saisie actuel.

Les classes suivantes sont également importantes:

BaseInputConnection

Définit le canal de communication d'un InputMethod à l'application qui reçoit ses entrées. Vous l'utilisez pour lire le texte autour du curseur, enregistrer le texte dans la zone de texte et envoyer des événements de touche bruts à l'application. Les applications doivent étendre cette classe plutôt que d'implémenter l'interface de base InputConnection.

KeyboardView

Une extension de View qui affiche un clavier et répond aux événements d'entrée utilisateur. La mise en page du clavier est spécifiée par une instance de Keyboard, que vous pouvez définir dans un fichier XML.

Concevoir l'interface utilisateur du mode de saisie

Un IME comporte deux éléments visuels principaux : la vue Saisie et la vue Candidats. Vous n'avez à implémenter que les éléments pertinents pour la méthode d'entrée que vous concevez.

Vue d'entrée

La vue d'entrée est l'UI dans laquelle l'utilisateur saisit du texte sous la forme de clics sur des touches, d'écriture manuscrite ou de gestes. Lorsque l'IME est affiché pour la première fois, le système appelle la méthode onCreateInputView() . Dans l'implémentation de cette méthode, créez la mise en page que vous souhaitez afficher dans la fenêtre de l'IME et renvoyez-la au système. L'extrait de code suivant montre un exemple d'implémentation de la méthode 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;
}

Dans cet exemple, MyKeyboardView est une instance d'une implémentation personnalisée de KeyboardView qui affiche un Keyboard.

Vue des candidats

La vue des suggestions est l'UI dans laquelle le IME affiche les corrections ou suggestions de mots potentiels que l'utilisateur peut sélectionner. Dans le cycle de vie de l'IME, le système appelle onCreateCandidatesView() lorsqu'il est prêt à afficher la vue des candidats. Dans votre implémentation de cette méthode, renvoyez une mise en page qui affiche des suggestions de mots, ou renvoyez la valeur "null" si vous ne souhaitez rien afficher. Une valeur Null est le comportement par défaut. Vous n'avez donc pas à l'implémenter si vous ne fournissez pas des suggestions.

Considérations relatives à la conception de l'interface utilisateur

Cette section décrit certaines considérations de conception de l'interface utilisateur pour les IME.

Gérer plusieurs tailles d'écran

L'UI de votre IME doit pouvoir s'adapter à différentes tailles d'écran et gérer les orientations Paysage et Portrait. En mode IME hors plein écran, laissez suffisamment d'espace pour que l'application affiche le champ de texte et tout contexte associé, de sorte que l'IME n'occupe pas plus de la moitié de l'écran. En mode IME plein écran, ce n'est pas un problème.

Gérer différents types d'entrées

Les champs de texte Android vous permettent de définir un type de saisie spécifique, tel que du texte libre, des nombres, des URL, des adresses e-mail et des chaînes de recherche. Lorsque vous implémentez un nouvel IME, détectez le type d'entrée de chaque et fournissez l'interface appropriée. Toutefois, vous n'avez pas besoin de configurer votre IME pour vérifier si l'utilisateur saisit du texte valide pour le type de saisie. C'est la responsabilité de l'application propriétaire du champ de texte.

Par exemple, voici l'interface fournie par l'IME latin pour la saisie de texte de la plate-forme Android :

Figure 2 : Saisie de texte IME latin.

Voici l'interface que l'IME latin fournit pour la saisie numérique de la plate-forme Android :

Figure 3 : Saisie numérique avec l'IME latin

Lorsqu'un champ de saisie reçoit la sélection et que votre IME démarre, le système appelle onStartInputView(), en transmettant un objet EditorInfo contenant des informations sur le type de saisie et d'autres attributs du champ de texte. Dans cet objet, le champ inputType contient le type de saisie du champ de texte.

Le champ inputType est un int qui contient des modèles de bits pour différents paramètres de type d'entrée. Pour tester le type d'entrée du champ de texte, masquez-le avec la constante TYPE_MASK_CLASS, comme ceci:

Kotlin

inputType and InputType.TYPE_MASK_CLASS

Java

inputType & InputType.TYPE_MASK_CLASS

Le modèle de bits du type d'entrée peut avoir l'une des valeurs suivantes:

TYPE_CLASS_NUMBER

Champ de texte permettant de saisir des chiffres. Comme illustré dans la figure 3, l'éditeur de mode de saisie latin affiche une pour les champs de ce type.

TYPE_CLASS_DATETIME

Champ de texte permettant de saisir une date et une heure.

TYPE_CLASS_PHONE

Champ de texte permettant de saisir des numéros de téléphone.

TYPE_CLASS_TEXT

Champ de texte permettant de saisir des caractères acceptés.

Ces constantes sont décrites plus en détail dans la documentation de référence InputType

Le champ inputType peut contenir d'autres bits qui indiquent une variante du champ de texte par exemple:

TYPE_TEXT_VARIATION_PASSWORD

Variante de TYPE_CLASS_TEXT pour saisir des mots de passe. Le mode de saisie s'affiche des barres de couleur au lieu du texte lui-même.

TYPE_TEXT_VARIATION_URI

Variante de TYPE_CLASS_TEXT permettant de saisir des URL Web et d'autres ressources uniformes Identifiants (URI)

TYPE_TEXT_FLAG_AUTO_COMPLETE

Variante de TYPE_CLASS_TEXT permettant de saisir du texte que l'application saisie semi-automatique à partir d'un dictionnaire, d'une recherche ou d'une autre fonction.

Masquez inputType avec la constante appropriée lorsque vous testez ces variantes. Les constantes de masque disponibles sont répertoriées dans la documentation de référence de InputType.

<ph type="x-smartling-placeholder">

</ph> Attention:Dans votre propre IME, gérez correctement le texte lorsque vous l'envoyez à un champ de mot de passe. Masquez le mot de passe dans votre UI, à la fois dans la vue de saisie et dans la vue des candidats. Ne stockez pas de mots de passe sur un appareil. Pour en savoir plus, consultez Conseils de sécurité

Envoyer du texte à l'application

Lorsque l'utilisateur saisit du texte avec votre IME, vous pouvez envoyer du texte à l'application en envoyant des ou en modifiant le texte autour du curseur dans le champ de texte de l'application. Dans les deux cas, utilisez une instance de InputConnection pour diffuser le texte. Pour obtenir cette instance, appelez InputMethodService.getCurrentInputConnection().

Modifier le texte autour du curseur

Lorsque vous gérez la modification d'un texte existant, certaines méthodes utiles Les BaseInputConnection sont les suivantes:

getTextBeforeCursor()

Renvoie un CharSequence contenant le nombre de caractères demandés avant la position actuelle du curseur.

getTextAfterCursor()

Renvoie un CharSequence contenant le nombre de caractères demandés après la position actuelle du curseur.

deleteSurroundingText()

Supprime le nombre spécifié de caractères avant et après la position actuelle du curseur.

commitText()

Enregistre un CharSequence dans le champ de texte et définit une nouvelle position du curseur.

Par exemple, l'extrait suivant montre comment remplacer les quatre caractères à gauche du curseur par le texte "Bonjour !" :

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

Prise en charge de la rédaction de texte avant de valider

Si votre IME prédit du texte ou nécessite plusieurs étapes pour composer un glyphe ou un mot, vous pouvez afficher le progression dans le champ de texte jusqu'à ce que l'utilisateur valide le mot. Vous pouvez ensuite remplacer la partie la composition avec le texte terminé. Vous pouvez traiter le texte de manière spéciale en y ajoutant un élément span lorsque vous le transmettez à setComposingText().

L'extrait de code suivant montre comment afficher la progression dans un champ de texte:

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

Interception des événements de touche matérielle

Même si la fenêtre de mode de saisie n'a pas de ciblage explicite, elle reçoit les événements de touche matérielle et peuvent les utiliser ou les transférer à l'application. Par exemple, vous pouvez utiliser les touches directionnelles pour naviguer dans votre UI afin de sélectionner des candidats lors de la composition. Vous pouvez également capturer la touche Retour pour fermer toutes les boîtes de dialogue provenant de la fenêtre de méthode d'entrée.

Pour intercepter les clés matérielles, remplacez onKeyDown() et onKeyUp().

Appelez la méthode super() pour les clés que vous ne souhaitez pas gérer vous-même.

Créer un sous-type IME

Les sous-types permettent à l'IME d'exposer plusieurs modes de saisie et langues pris en charge par un IME. Un sous-type peut représenter les éléments suivants :

• Des paramètres régionaux, tels que en_US ou fr_FR
• Un mode de saisie (voix, clavier ou écriture manuscrite, par exemple)
• Autres styles de saisie, formulaires ou propriétés spécifiques à l'IME, tels que 10 touches ou QWERTY configurations de clavier

Le mode peut être n'importe quel texte, par exemple "clavier" ou "voix". Un sous-type peut également exposer une combinaison de ces éléments.

Les informations sur le sous-type sont utilisées pour une boîte de dialogue de commutation d'IME disponible dans la barre de notification et pour les paramètres de l'IME. Ces informations permettent également au framework d'afficher un sous-type spécifique d'un IME. directement. Lorsque vous créez un IME, utilisez l'utilitaire sous-type "feature", car il permet à l'utilisateur d'identifier et basculer entre les différents modes et langages IME.

Elle définit les sous-types dans l'un des fichiers de ressources XML de la méthode d'entrée, à l'aide de la méthode Élément <subtype>. L'extrait de code suivant définit un IME avec deux sous-types : sous-type de clavier pour l'anglais américain et un autre sous-type de clavier pour le français langue pour la France:

<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>

Pour vous assurer que vos sous-types sont correctement libellés dans l'UI, utilisez "%s" pour obtenir un libellé de sous-type identique à celui du libellé de paramètres régionaux du sous-type. Cela est illustré dans les deux extraits de code suivants. Le premier extrait montre une partie du fichier XML de la méthode d'entrée :

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

L'extrait suivant fait partie du fichier strings.xml de l'IME. La ressource de chaîne label_subtype_generic, qui est utilisée par la définition de l'UI de la méthode de saisie pour définir le libellé du sous-type, est définie comme suit :

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

Ce paramètre fait en sorte que le nom à afficher du sous-type corresponde au paramètre régional. Par exemple, dans n'importe quel paramètre régional en anglais, le nom à afficher est "Anglais (États-Unis)".

Choisir des sous-types d'IME dans la barre de notification

Le système Android gère tous les sous-types exposés par tous les IME. Les sous-types d'IME sont traités comme des modes de l'IME auquel ils appartiennent. L'utilisateur peut naviguer de la barre de notification ou de l'application Paramètres vers un des sous-types d'IME disponibles, comme illustré dans la figure suivante:

Figure 4 : La page Langues et d'entrée dans le menu système.

Choisir des sous-types d'IME dans les paramètres système

L'utilisateur peut également contrôler l'utilisation des sous-types dans le panneau de paramètres Langue et saisie des paramètres système :

Figure 5 : Menu système Langues

Passer d'un sous-type d'IME à un autre

Vous pouvez permettre aux utilisateurs de basculer facilement entre les sous-types d'IME en fournissant une touche de commutation, comme l'icône de langue en forme de globe sur le clavier. Cela améliore la facilité d'utilisation du clavier et est pratique pour l'utilisateur. Pour activer ce basculement, procédez comme suit :

1. Déclarez supportsSwitchingToNextInputMethod = "true" dans les fichiers de ressources XML de la méthode de saisie. Votre déclaration doit ressembler à l'extrait de code suivant:

   <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. Appelez la méthode shouldOfferSwitchingToNextInputMethod().
3. Si la méthode renvoie la valeur "true", affichez une clé de basculement.
4. Lorsque l'utilisateur appuie sur la touche de basculement, appelez switchToNextInputMethod(), en transmettant la valeur "false". Une valeur de "false" indique au système de traiter tous les sous-types de manière égale, quel que soit l'IME auquel ils appartiennent. Si vous spécifiez "true", le système doit faire défiler les sous-types dans l'IME actuel.

Considérations générales liées aux IME

Voici d'autres éléments à prendre en compte lorsque vous implémentez votre IME:

• Fournissez aux utilisateurs un moyen de définir des options directement depuis l'interface utilisateur de l'IME.
• permettre aux utilisateurs de basculer vers un autre IME directement à partir de l'interface utilisateur du mode de saisie ; car plusieurs IME peuvent être installés sur l'appareil.
• Affichez rapidement l'interface utilisateur de l'IME. Préchargez ou chargez à la demande les ressources volumineuses pour que les utilisateurs l'IME dès qu'il appuie sur un champ de texte. Mise en cache des ressources et des vues pour les appels ultérieurs de la méthode de saisie.
• Libérez les allocations de mémoire importantes immédiatement après le masquage de la fenêtre de saisie afin que les applications disposent de suffisamment de mémoire pour s'exécuter. Utilisez un message différé pour libérer des ressources si le IME est masqué pendant quelques secondes.
• S'assurer que les utilisateurs peuvent saisir autant de caractères que possible pour la langue ou les paramètres régionaux associé à l'IME. Les utilisateurs peuvent utiliser des signes de ponctuation dans leurs mots de passe ou leurs noms d'utilisateur. Votre IME doit donc fournir de nombreux caractères différents pour permettre aux utilisateurs de saisir un mot de passe et d'accéder à l'appareil.