chrome.input.ime

Important : Cette API ne fonctionne que sur ChromeOS.

Description

Utilise l'API chrome.input.ime pour implémenter un IME personnalisé pour ChromeOS. Cela permet à votre extension de gérer les frappes au clavier, de définir la composition et de gérer la fenêtre de candidats.

Autorisations

input

Vous devez déclarer l'autorisation "input" dans le fichier manifeste de l'extension pour utiliser l'API input.ime. Exemple :

{
  "name": "My extension",
  ...
  "permissions": [
    "input"
  ],
  ...
}

Disponibilité

ChromeOS uniquement

Exemples

Le code suivant crée un IME qui convertit les lettres saisies en majuscules.

var context_id = -1;

chrome.input.ime.onFocus.addListener(function(context) {
  context_id = context.contextID;
});

chrome.input.ime.onKeyEvent.addListener(
  function(engineID, keyData) {
    if (keyData.type == "keydown" && keyData.key.match(/^[a-z]$/)) {
      chrome.input.ime.commitText({"contextID": context_id,
                                    "text": keyData.key.toUpperCase()});
      return true;
    } else {
      return false;
    }
  }
);

Types

AssistiveWindowButton

Chrome 85 et versions ultérieures

ID des boutons dans la fenêtre d'assistance.

Énumération

"undo"

"addToDictionary"

AssistiveWindowProperties

Chrome 85 et versions ultérieures

Propriétés de la fenêtre d'assistance.

Propriétés

• announceString

  chaîne facultatif

  Chaînes que ChromeVox doit annoncer.

• type

  "undo"
  

• visible

  booléen

  Définit la valeur sur "true" pour afficher AssistiveWindow et sur "false" pour la masquer.

AssistiveWindowType

Chrome 85 et versions ultérieures

Type de fenêtre d'assistance.

Valeur

"undo"

AutoCapitalizeType

Chrome 69 et versions ultérieures

Type de mise en majuscules automatique du champ de texte.

Énumération

"characters"

"words"

"sentences"

InputContext

Décrit un contexte d'entrée

Propriétés

• autoCapitalize

  AutoCapitalizeType

  Chrome 69 et versions ultérieures

  Type de mise en majuscules automatique du champ de texte.

• autoComplete

  booléen

  Indique si le champ de texte souhaite la saisie semi-automatique.

• autoCorrect

  booléen

  Indique si le champ de texte souhaite la correction automatique.

• contextID

  nombre

  Cela permet de spécifier les cibles des opérations sur les champs de texte. Cet ID devient non valide dès que onBlur est appelé.

• shouldDoLearning

  booléen

  Chrome 68 et versions ultérieures

  Indique si le texte saisi dans le champ de texte doit être utilisé pour améliorer les suggestions de saisie pour l'utilisateur.

• spellCheck

  booléen

  Indique si le champ de texte souhaite bénéficier du correcteur orthographique.

• type

  InputContextType

  Type de valeur que ce champ de texte modifie (texte, nombre, URL, etc.)

InputContextType

Chrome 44 et versions ultérieures

Type de valeur que ce champ de texte modifie (texte, nombre, URL, etc.)

Énumération

"text"

"search"

"tel"

"url"

"email"

"number"

"password"

"null"

KeyboardEvent

Consultez http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent.

Propriétés

• altKey

  booléen facultatif

  Indique si la touche ALT est enfoncée.

• altgrKey

  booléen facultatif

  Chrome 79 et versions ultérieures

  Indique si la touche ALTGR est enfoncée.

• capsLock

  booléen facultatif

  Indique si la touche VERR MAJ est activée ou non.

• code

  chaîne

  Valeur de la touche physique sur laquelle l'utilisateur appuie. La valeur n'est pas affectée par la disposition actuelle du clavier ni par l'état du modificateur.

• ctrlKey

  booléen facultatif

  Indique si la touche CTRL est enfoncée.

• extensionId

  chaîne facultatif

  ID de l'extension de l'expéditeur de cet événement clavier.

• clé

  chaîne

  Valeur de la touche enfoncée

• keyCode

  number facultatif

  Code numérique déconseillé, dépendant du système et de l'implémentation, qui indique l'identifiant non modifié associé à la touche enfoncée.

• requestId

  chaîne facultatif

  (Obsolète) ID de la requête. Utilisez plutôt le paramètre requestId de l'événement onKeyEvent.

• shiftKey

  booléen facultatif

  Indique si la touche MAJ est enfoncée.

• type

  KeyboardEventType

  "keyup" ou "keydown".

KeyboardEventType

Chrome 44 et versions ultérieures

Énumération

"keyup"

"keydown"

MenuItem

Élément de menu utilisé par une méthode de saisie pour interagir avec l'utilisateur à partir du menu de langue.

Propriétés

• coché

  booléen facultatif

  Indique que cet élément doit être dessiné avec une coche.

• activé

  booléen facultatif

  Indique que cet élément est activé.

• id

  chaîne

  Chaîne qui sera transmise aux rappels faisant référence à ce MenuItem.

• étiquette

  chaîne facultatif

  Texte affiché dans le menu pour cet élément.

• style

  MenuItemStyle facultatif

  Type de l'élément de menu.

• visible

  booléen facultatif

  Indique que cet élément est visible.

MenuItemStyle

Chrome 44 et versions ultérieures

Type de l'élément de menu. Les cases d'option entre les séparateurs sont considérées comme regroupées.

Énumération

"check"

"radio"

"separator"

MenuParameters

Chrome 88 et versions ultérieures

Propriétés

• engineID

  chaîne

  ID du moteur à utiliser.

• éléments

  MenuItem[]

  MenuItems à ajouter ou à mettre à jour. Ils seront ajoutés dans l'ordre dans lequel ils figurent dans le tableau.

MouseButton

Chrome 44 et versions ultérieures

Boutons de la souris sur lesquels l'utilisateur a cliqué.

Énumération

"left"

"middle"

"right"

ScreenType

Chrome 44 et versions ultérieures

Type d'écran sous lequel l'IME est activé.

Énumération

"normal"

"login"

"lock"

"secondary-login"

UnderlineStyle

Chrome 44 et versions ultérieures

Type de soulignement à modifier pour ce segment.

Énumération

"underline"

"doubleUnderline"

"noUnderline"

WindowPosition

Chrome 44 et versions ultérieures

Où afficher la fenêtre de candidats. Si la valeur est définie sur "curseur", la fenêtre suit le curseur. Si la valeur est définie sur "composition", la fenêtre est verrouillée au début de la composition.

Énumération

"cursor"

"composition"

Méthodes

clearComposition()

chrome.input.ime.clearComposition(
  parameters: object,
): Promise<boolean>

Efface la composition actuelle. Si cette extension n'est pas propriétaire de l'IME actif, cette opération échoue.

Paramètres

• paramètres

  objet

  • contextID

    nombre

    ID du contexte dans lequel la composition sera effacée

Renvoie

• Promise<boolean>

  Chrome 111 et versions ultérieures

  Résolution lorsque l'opération se termine avec une valeur booléenne indiquant si le texte a été accepté ou non. En cas d'échec, la promesse sera rejetée.

commitText()

chrome.input.ime.commitText(
  parameters: object,
): Promise<boolean>

Valide le texte fourni dans l'entrée actuelle.

Paramètres

• paramètres

  objet

  • contextID

    nombre

    ID du contexte dans lequel le texte sera validé

  • texte

    chaîne

    Texte à valider

Renvoie

• Promise<boolean>

  Chrome 111 et versions ultérieures

  Résolution lorsque l'opération se termine avec une valeur booléenne indiquant si le texte a été accepté ou non. En cas d'échec, la promesse sera rejetée.

deleteSurroundingText()

chrome.input.ime.deleteSurroundingText(
  parameters: object,
): Promise<void>

Supprime le texte autour du curseur.

Paramètres

• paramètres

  objet

  • contextID

    nombre

    ID du contexte dans lequel le texte environnant sera supprimé.

  • engineID

    chaîne

    ID du moteur recevant l'événement.

  • longueur

    nombre

    Nombre de caractères à supprimer

  • offset

    nombre

    Décalage par rapport à la position du curseur à partir duquel la suppression commencera. Cette valeur peut être négative.

Renvoie

• Promise<void>

  Chrome 111 et versions ultérieures

  Résout lorsque l'opération est terminée.

hideInputView()

chrome.input.ime.hideInputView(): void

Masque la fenêtre de saisie, qui s'affiche automatiquement par le système. Si la fenêtre de vue d'entrée est déjà masquée, cette fonction n'aura aucun effet.

keyEventHandled()

chrome.input.ime.keyEventHandled(
  requestId: string,
  response: boolean,
): void

Indique que l'événement de touche reçu par onKeyEvent est géré. Cette méthode ne doit être appelée que si l'écouteur onKeyEvent est asynchrone.

Paramètres

• requestId

  chaîne

  ID de la requête de l'événement qui a été traité. Cette valeur doit provenir de keyEvent.requestId.

• réponse

  booléen

  "True" si la frappe a été traitée, "false" dans le cas contraire

sendKeyEvents()

chrome.input.ime.sendKeyEvents(
  parameters: object,
): Promise<void>

Envoie les événements clés. Cette fonction est censée être utilisée par les claviers virtuels. Lorsqu'un utilisateur appuie sur une ou plusieurs touches d'un clavier virtuel, cette fonction est utilisée pour propager cet événement au système.

Paramètres

• paramètres

  objet

  • contextID

    nombre

    ID du contexte dans lequel les événements clés seront envoyés, ou zéro pour envoyer les événements clés à un champ non destiné à la saisie.

  • keyData

    KeyboardEvent[]

    Données sur l'événement clé.

Renvoie

• Promise<void>

  Chrome 111 et versions ultérieures

  Résout lorsque l'opération est terminée.

setAssistiveWindowButtonHighlighted()

Chrome 86 et versions ultérieures

chrome.input.ime.setAssistiveWindowButtonHighlighted(
  parameters: object,
): Promise<void>

Met en surbrillance/Supprime la mise en surbrillance d'un bouton dans une fenêtre d'assistance.

Paramètres

• paramètres

  objet

  • announceString

    chaîne facultatif

    Texte que le lecteur d'écran doit énoncer.

  • buttonID

    AssistiveWindowButton

    ID du bouton

  • contextID

    nombre

    ID du contexte propriétaire de la fenêtre d'assistance.

  • en surbrillance

    booléen

    Indique si le bouton doit être mis en surbrillance.

  • windowType

    "undo"
    

    Type de fenêtre auquel appartient le bouton.

Renvoie

• Promise<void>

  Chrome 111 et versions ultérieures

  Résout lorsque l'opération est terminée. En cas d'échec, la promesse sera rejetée.

setAssistiveWindowProperties()

Chrome 85 et versions ultérieures

chrome.input.ime.setAssistiveWindowProperties(
  parameters: object,
): Promise<boolean>

Affiche/Masque une fenêtre d'assistance avec les propriétés indiquées.

Paramètres

• paramètres

  objet

  • contextID

    nombre

    ID du contexte propriétaire de la fenêtre d'assistance.

  • properties

    AssistiveWindowProperties

    Propriétés de la fenêtre d'assistance.

Renvoie

• Promise<boolean>

  Chrome 111 et versions ultérieures

  Résout lorsque l'opération est terminée.

setCandidates()

chrome.input.ime.setCandidates(
  parameters: object,
): Promise<boolean>

Définit la liste actuelle des candidats. Échec si cette extension n'est pas propriétaire de l'IME actif

Paramètres

• paramètres

  objet

  • candidats

    object[]

    Liste des candidats à afficher dans la fenêtre de candidats

    • annotation

      chaîne facultatif

      Texte supplémentaire décrivant le candidat

    • candidat

      chaîne

      Le candidat

    • id

      nombre

      ID du candidat

    • étiquette

      chaîne facultatif

      Courte chaîne affichée à côté du candidat, souvent la touche de raccourci ou l'index

    • parentId

      number facultatif

      ID sous lequel ajouter ces candidats

    • utilisation

      object facultatif

      Description de l'utilisation ou du détail du mot.

      • body

        chaîne

        Chaîne du corps de la description détaillée.

      • title

        chaîne

        Chaîne de titre de la description des détails.

  • contextID

    nombre

    ID du contexte propriétaire de la fenêtre du candidat.

Renvoie

• Promise<boolean>

  Chrome 111 et versions ultérieures

  Résout lorsque l'opération est terminée.

setCandidateWindowProperties()

chrome.input.ime.setCandidateWindowProperties(
  parameters: object,
): Promise<boolean>

Définit les propriétés de la fenêtre de candidats. Cette opération échoue si l'extension n'est pas propriétaire de l'IME actif.

Paramètres

• paramètres

  objet

  • engineID

    chaîne

    ID du moteur sur lequel définir les propriétés.

  • properties

    objet

    • auxiliaryText

      chaîne facultatif

      Texte affiché en bas de la fenêtre de candidats.

    • auxiliaryTextVisible

      booléen facultatif

      True pour afficher le texte auxiliaire, false pour le masquer.

    • currentCandidateIndex

      number facultatif

      Chrome 84 et versions ultérieures

      Index du candidat actuellement sélectionné sur le nombre total de candidats.

    • cursorVisible

      booléen facultatif

      True pour afficher le curseur, false pour le masquer.

    • pageSize

      number facultatif

      Nombre de candidats à afficher par page.

    • totalCandidates

      number facultatif

      Chrome 84 et versions ultérieures

      Nombre total de candidats pour la fenêtre de candidats.

    • verticale

      booléen facultatif

      "True" si la fenêtre de candidats doit être rendue verticalement, "false" pour la rendre horizontalement.

    • visible

      booléen facultatif

      True pour afficher la fenêtre "Candidat", false pour la masquer.

    • windowPosition

      WindowPosition facultatif

      Où afficher la fenêtre de candidats.

Renvoie

• Promise<boolean>

  Chrome 111 et versions ultérieures

  Résout lorsque l'opération est terminée.

setComposition()

chrome.input.ime.setComposition(
  parameters: object,
): Promise<boolean>

Définissez la composition actuelle. Si cette extension n'est pas propriétaire de l'IME actif, cette opération échoue.

Paramètres

• paramètres

  objet

  • contextID

    nombre

    ID du contexte dans lequel le texte de la composition sera défini

  • cursor

    nombre

    Position du curseur dans le texte.

  • similaires

    object[] facultatif

    Liste des segments et de leurs types associés.

    • end

      nombre

      Index du caractère après lequel ce segment doit se terminer.

    • start

      nombre

      Index du caractère à partir duquel ce segment doit commencer

    • style

      UnderlineStyle

      Type de soulignement à modifier pour ce segment.

  • selectionEnd

    number facultatif

    Position dans le texte où se termine la sélection.

  • selectionStart

    number facultatif

    Position dans le texte où la sélection commence.

  • texte

    chaîne

    Texte à définir

Renvoie

• Promise<boolean>

  Chrome 111 et versions ultérieures

  Résolution lorsque l'opération se termine avec une valeur booléenne indiquant si le texte a été accepté ou non. En cas d'échec, la promesse sera rejetée.

setCursorPosition()

chrome.input.ime.setCursorPosition(
  parameters: object,
): Promise<boolean>

Définissez la position du curseur dans la fenêtre de candidats. Il s'agit d'une no-op si cette extension n'est pas propriétaire de l'IME actif.

Paramètres

• paramètres

  objet

  • candidateID

    nombre

    ID du candidat à sélectionner.

  • contextID

    nombre

    ID du contexte propriétaire de la fenêtre du candidat.

Renvoie

• Promise<boolean>

  Chrome 111 et versions ultérieures

  Résolution lorsque l'opération est terminée

setMenuItems()

chrome.input.ime.setMenuItems(
  parameters: MenuParameters,
): Promise<void>

Ajoute les éléments de menu fournis au menu de langue lorsque cet IME est actif.

Paramètres

• paramètres

  MenuParameters

Renvoie

• Promise<void>

  Chrome 111 et versions ultérieures

updateMenuItems()

chrome.input.ime.updateMenuItems(
  parameters: MenuParameters,
): Promise<void>

Met à jour l'état des MenuItems spécifiés.

Paramètres

• paramètres

  MenuParameters

Renvoie

• Promise<void>

  Chrome 111 et versions ultérieures

  Résolution lorsque l'opération est terminée

Événements

onActivate

chrome.input.ime.onActivate.addListener(
  callback: function,
)

Cet événement est envoyé lorsqu'un IME est activé. Il indique que l'IME recevra des événements onKeyPress.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (engineID: string, screen: ScreenType) => void

  • engineID

    chaîne

  • écran

    ScreenType

onAssistiveWindowButtonClicked

Chrome 85 et versions ultérieures

chrome.input.ime.onAssistiveWindowButtonClicked.addListener(
  callback: function,
)

Cet événement est envoyé lorsqu'un bouton d'une fenêtre d'assistance est cliqué.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (details: object) => void

  • détails

    objet

    • buttonID

      AssistiveWindowButton

      ID du bouton sur lequel l'utilisateur a cliqué.

    • windowType

      AssistiveWindowType

      Type de fenêtre d'assistance.

onBlur

chrome.input.ime.onBlur.addListener(
  callback: function,
)

Cet événement est envoyé lorsque le focus quitte une zone de texte. Il est envoyé à toutes les extensions qui écoutent cet événement et qui sont activées par l'utilisateur.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (contextID: number) => void

  • contextID

    nombre

onCandidateClicked

chrome.input.ime.onCandidateClicked.addListener(
  callback: function,
)

Cet événement est envoyé si cette extension possède l'IME actif.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (engineID: string, candidateID: number, button: MouseButton) => void

  • engineID

    chaîne

  • candidateID

    nombre

  • bouton

    MouseButton

onDeactivated

chrome.input.ime.onDeactivated.addListener(
  callback: function,
)

Cet événement est envoyé lorsqu'un IME est désactivé. Cela indique que l'IME ne recevra plus d'événements onKeyPress.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (engineID: string) => void

  • engineID

    chaîne

onFocus

chrome.input.ime.onFocus.addListener(
  callback: function,
)

Cet événement est envoyé lorsque le focus entre dans une zone de texte. Il est envoyé à toutes les extensions qui écoutent cet événement et qui sont activées par l'utilisateur.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (context: InputContext) => void

  • context

    InputContext

onInputContextUpdate

chrome.input.ime.onInputContextUpdate.addListener(
  callback: function,
)

Cet événement est envoyé lorsque les propriétés de l'InputContext actuel changent, comme le type. Il est envoyé à toutes les extensions qui écoutent cet événement et qui sont activées par l'utilisateur.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (context: InputContext) => void

  • context

    InputContext

onKeyEvent

chrome.input.ime.onKeyEvent.addListener(
  callback: function,
)

Déclenché lorsqu'un événement de touche est envoyé par le système d'exploitation. L'événement sera envoyé à l'extension si celle-ci possède l'IME actif. La fonction d'écouteur doit renvoyer "true" si l'événement a été géré et "false" dans le cas contraire. Si l'événement doit être évalué de manière asynchrone, cette fonction doit renvoyer "undefined" et l'IME doit appeler keyEventHandled() ultérieurement avec le résultat.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (engineID: string, keyData: KeyboardEvent, requestId: string) => boolean | undefined

  • engineID

    chaîne

  • keyData

    KeyboardEvent

  • requestId

    chaîne

  • Renvoie

    boolean | undefined

onMenuItemActivated

chrome.input.ime.onMenuItemActivated.addListener(
  callback: function,
)

Appelée lorsque l'utilisateur sélectionne un élément de menu

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (engineID: string, name: string) => void

  • engineID

    chaîne

  • nom

    chaîne

onReset

chrome.input.ime.onReset.addListener(
  callback: function,
)

Cet événement est envoyé lorsque Chrome met fin à la session de saisie de texte en cours.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (engineID: string) => void

  • engineID

    chaîne

onSurroundingTextChanged

chrome.input.ime.onSurroundingTextChanged.addListener(
  callback: function,
)

Appelé lorsque la chaîne modifiable autour du curseur est modifiée ou lorsque la position du curseur est déplacée. La longueur du texte est limitée à 100 caractères pour chaque aller-retour.

Paramètres

• callback

  fonction

  Le paramètre callback se présente comme suit :

  (engineID: string, surroundingInfo: object) => void

  • engineID

    chaîne

  • surroundingInfo

    objet

    • anchor

      nombre

      Position de début de la sélection. Cette valeur indique la position du curseur en l'absence de sélection.

    • concentration

      nombre

      Position de fin de la sélection. Cette valeur indique la position du curseur en l'absence de sélection.

    • offset

      nombre

      Chrome 46 et versions ultérieures

      Position de décalage de text. Étant donné que text n'inclut qu'un sous-ensemble de texte autour du curseur, l'offset indique la position absolue du premier caractère de text.

    • texte

      chaîne

      Texte autour du curseur. Il ne s'agit que d'un sous-ensemble de tout le texte du champ de saisie.