chrome.input.ime

Descrição

Use a API chrome.input.ime para implementar um IME personalizado para o Chrome OS. Isso permite que sua extensão processe pressionamentos de tecla, defina a composição e gerencie a janela de candidatos.

Permissões

input

Declare a permissão "input" no manifesto de extensões para usar a API input.ime. Exemplo:

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

Disponibilidade

Somente ChromeOS

Exemplos

O código a seguir cria um IME que converte letras digitadas em maiúsculas.

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

Tipos

AssistiveWindowButton

Chrome 85 ou mais recente

ID dos botões na janela assistiva.

Tipo enumerado

"addToDictionary"

AssistiveWindowProperties

Chrome 85 ou mais recente

Propriedades da janela assistiva.

Propriedades

  • announceString

    string opcional

    Strings que serão anunciadas pelo ChromeVox.

  • Tipo

  • visível

    boolean

    Define "true" para mostrar a AssistiveWindow, define "false" para ocultar.

AssistiveWindowType

Chrome 85 ou mais recente

Tipo de janela assistiva.

Valor

AutoCapitalizeType

Chrome 69 ou versões mais recentes

O tipo de letras maiúsculas automaticamente do campo de texto.

Tipo enumerado

InputContext

Descreve um contexto de entrada

Propriedades

  • autoCapitalize

    AutoCapitalizeType

    Chrome 69 ou versões mais recentes

    O tipo de letras maiúsculas automaticamente do campo de texto.

  • autoComplete

    boolean

    Indica se o campo de texto precisa ser preenchido automaticamente.

  • autoCorrect

    boolean

    Indica se o campo de texto precisa de correção automática.

  • contextID

    number

    É usado para especificar destinos de operações de campo de texto. Esse ID se torna inválido assim que o onBlur é chamado.

  • shouldDoLearning

    boolean

    Chrome 68 ou versões mais recentes

    Define se o texto inserido no campo de texto deve ser usado para melhorar as sugestões de digitação para o usuário.

  • spellCheck

    boolean

    Indica se o campo de texto precisa de verificação ortográfica.

  • Tipo de valor que este campo de texto edita (texto, número, URL etc.)

InputContextType

Chrome 44 ou superior

Tipo de valor que este campo de texto edita (texto, número, URL etc.)

Tipo enumerado

"tel"

"url"

"null"

KeyboardEvent

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

Propriedades

  • altKey

    booleano opcional

    Se a tecla ALT está ou não pressionada.

  • altgrKey

    booleano opcional

    Chrome 79 ou versão mais recente

    Se a tecla ALTGR está ou não pressionada.

  • capsLock

    booleano opcional

    Se CAPS_LOCK está ativado ou não.

  • código

    string

    Valor da tecla física que está sendo pressionada. O valor não é afetado pelo layout atual do teclado nem pelo estado do modificador.

  • ctrlKey

    booleano opcional

    Se a tecla CTRL está ou não pressionada.

  • extensionId

    string opcional

    O ID da extensão do remetente desse evento de tecla.

  • chave

    string

    Valor da tecla pressionada

  • keyCode

    número opcional

    O keyCode HTML descontinuado, que é o código numérico que depende do sistema e da implementação, significando o identificador não modificado associado à tecla pressionada.

  • requestId

    string opcional

    (Descontinuado) O ID da solicitação. Use o parâmetro requestId do evento onKeyEvent.

  • shiftKey

    booleano opcional

    Se a tecla SHIFT está ou não pressionada.

  • Um keyup ou keydown.

KeyboardEventType

Chrome 44 ou superior

Tipo enumerado

"keyup"

"keydown"

MenuItem

Item de menu usado por um método de entrada para interagir com o usuário no menu de idiomas.

Propriedades

  • marcado

    booleano opcional

    Indica que este item deve ser desenhado com uma marca de seleção.

  • ativado

    booleano opcional

    Indica que o item está ativado.

  • id

    string

    String que será transmitida para callbacks que fazem referência a esse MenuItem.

  • o rótulo.

    string opcional

    Texto exibido no menu deste item.

  • estilo

    MenuItemStyle opcional

    Tipo de item de menu.

  • visível

    booleano opcional

    Indica que o item está visível.

MenuItemStyle

Chrome 44 ou superior

Tipo de item de menu. Os botões de opção entre separadores são considerados agrupados.

Tipo enumerado

MenuParameters

Chrome 88 ou mais recente

Propriedades

  • engineID

    string

    ID do mecanismo a ser usado.

  • items

    MenuItem[]

    MenuItems para adicionar ou atualizar. Eles serão adicionados na ordem em que estiverem na matriz.

MouseButton

Chrome 44 ou superior

Quais botões do mouse foram clicados.

Tipo enumerado

ScreenType

Chrome 44 ou superior

O tipo de tela em que o IME é ativado.

Tipo enumerado

"normal"

UnderlineStyle

Chrome 44 ou superior

O tipo de sublinhado para modificar este segmento.

Tipo enumerado

WindowPosition

Chrome 44 ou superior

Onde exibir a janela do candidato. Se definida como "cursor", a janela seguirá o cursor. Se definida como "composição", a janela será bloqueada para o início da composição.

Tipo enumerado

"cursor"

Métodos

clearComposition()

Promessa 
chrome.input.ime.clearComposition(
  parameters: object,
  callback?: function,
)

Limpar a composição atual. Se essa extensão não for proprietária do IME ativo, ocorrerá uma falha.

Parâmetros

  • parâmetros

    objeto

    • contextID

      number

      ID do contexto em que a composição será apagada

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      boolean

Retorna

  • Promise<boolean>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

commitText()

Promessa 
chrome.input.ime.commitText(
  parameters: object,
  callback?: function,
)

Confirma o texto fornecido na entrada atual.

Parâmetros

  • parâmetros

    objeto

    • contextID

      number

      ID do contexto em que o texto será confirmado

    • texto

      string

      O texto a ser confirmado

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      boolean

Retorna

  • Promise<boolean>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

deleteSurroundingText()

Promessa 
chrome.input.ime.deleteSurroundingText(
  parameters: object,
  callback?: function,
)

Exclui o texto ao redor do cursor.

Parâmetros

  • parâmetros

    objeto

    • contextID

      number

      ID do contexto em que o texto ao redor será excluído.

    • engineID

      string

      ID do mecanismo que recebe o evento.

    • length

      number

      O número de caracteres a serem excluídos

    • offset

      number

      O deslocamento da posição do acento circunflexo em que a exclusão começará. Esse valor pode ser negativo.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

hideInputView()

chrome.input.ime.hideInputView()

Oculta a janela de visualização de entrada, que é aberta automaticamente pelo sistema. Se a janela de visualização de entrada já estiver oculta, essa função não terá efeito.

keyEventHandled()

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

Indica que o evento principal recebido pelo onKeyEvent é processado. Só será chamado se o listener onKeyEvent for assíncrono.

Parâmetros

  • requestId

    string

    ID da solicitação do evento que foi processado. Deve vir de keyEvent.requestId

  • resposta

    boolean

    Verdadeiro se o pressionamento de tecla tiver sido processado, falso se não for

sendKeyEvents()

Promessa 
chrome.input.ime.sendKeyEvents(
  parameters: object,
  callback?: function,
)

Envia os eventos principais. Espera-se que essa função seja usada por teclados virtuais. Quando um usuário pressiona teclas em um teclado virtual, essa função é usada para propagar esse evento para o sistema.

Parâmetros

  • parâmetros

    objeto

    • contextID

      number

      ID do contexto para onde os eventos principais vão ser enviados ou zero para enviar eventos principais a um campo que não é de entrada.

    • keyData

      KeyboardEvent[]

      Dados sobre o evento principal.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

setAssistiveWindowButtonHighlighted()

Promessa Chrome 86+ 
chrome.input.ime.setAssistiveWindowButtonHighlighted(
  parameters: object,
  callback?: function,
)

Realiza/refaz o destaque de um botão em uma janela assistiva.

Parâmetros

  • parâmetros

    objeto

    • announceString

      string opcional

      O texto a ser anunciado pelo leitor de tela.

    • O ID do botão

    • contextID

      number

      ID do contexto que tem a janela assistiva.

    • em destaque

      boolean

      Indica se o botão deve ser destacado.

    • windowType

      O tipo de janela a que o botão pertence.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

setAssistiveWindowProperties()

Promessa Chrome 85+ 
chrome.input.ime.setAssistiveWindowProperties(
  parameters: object,
  callback?: function,
)

Mostra/oculta uma janela assistiva com as propriedades fornecidas.

Parâmetros

  • parâmetros

    objeto

    • contextID

      number

      ID do contexto que tem a janela assistiva.

    • Propriedades da janela assistiva.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      boolean

Retorna

  • Promise<boolean>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

setCandidates()

Promessa 
chrome.input.ime.setCandidates(
  parameters: object,
  callback?: function,
)

Define a lista de candidatos atual. Isso falhará se a extensão não for proprietária do IME ativo

Parâmetros

  • parâmetros

    objeto

    • candidatos

      objeto[]

      Lista de candidatos a serem mostrados na janela correspondente

      • annotation

        string opcional

        Texto adicional que descreve o candidato

      • candidato

        string

        O candidato

      • id

        number

        O ID do candidato

      • o rótulo.

        string opcional

        String curta exibida ao lado do candidato, geralmente a tecla de atalho ou índice

      • parentId

        número opcional

        O ID ao qual adicionar esses candidatos

      • utilização

        objeto opcional

        O uso ou a descrição detalhada da palavra.

        • body

          string

          A string do corpo da descrição de detalhes.

        • title

          string

          A string do título da descrição dos detalhes.

    • contextID

      number

      ID do contexto proprietário da janela candidata.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      boolean

Retorna

  • Promise<boolean>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

setCandidateWindowProperties()

Promessa 
chrome.input.ime.setCandidateWindowProperties(
  parameters: object,
  callback?: function,
)

Define as propriedades da janela candidata. Isso falhará se a extensão não for proprietária do IME ativo

Parâmetros

  • parâmetros

    objeto

    • engineID

      string

      ID do mecanismo em que as propriedades serão definidas.

    • properties

      objeto

      • auxiliaryText

        string opcional

        Texto mostrado na parte de baixo da janela de candidatos.

      • auxiliaryTextVisible

        booleano opcional

        Verdadeiro para exibir o texto auxiliar, falso para ocultá-lo.

      • currentCandidateIndex

        número opcional

        Chrome 84 ou mais recente

        O índice do candidato escolhido atualmente em relação ao total de candidatos.

      • cursorVisible

        booleano opcional

        "True" para mostrar o cursor, "false" para ocultá-lo.

      • pageSize

        número opcional

        O número de candidatos a serem exibidos por página.

      • totalCandidates

        número opcional

        Chrome 84 ou mais recente

        O número total de candidatos para a janela de candidatos.

      • categoria

        booleano opcional

        "True", se a janela candidata precisa ser renderizada na vertical, "false" para torná-la horizontal.

      • visível

        booleano opcional

        True para mostrar a janela Candidate, false para ocultá-la.

      • windowPosition

        WindowPosition opcional

        Onde exibir a janela do candidato.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      boolean

Retorna

  • Promise<boolean>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

setComposition()

Promessa 
chrome.input.ime.setComposition(
  parameters: object,
  callback?: function,
)

Define a composição atual. Se essa extensão não for proprietária do IME ativo, ocorrerá uma falha.

Parâmetros

  • parâmetros

    objeto

    • contextID

      number

      ID do contexto em que o texto de composição será definido

    • cursor

      number

      Posição no texto do cursor.

    • segmentos

      objeto[] opcional

      Lista de segmentos e seus tipos associados.

      • end

        number

        Índice do caractere para terminar este segmento depois.

      • início

        number

        Índice do caractere no qual iniciar este segmento

      • O tipo de sublinhado para modificar este segmento.

    • selectionEnd

      número opcional

      Posição no texto em que a seleção termina.

    • selectionStart

      número opcional

      Posição no texto em que a seleção começa.

    • texto

      string

      Texto a ser definido

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      boolean

Retorna

  • Promise<boolean>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

setCursorPosition()

Promessa 
chrome.input.ime.setCursorPosition(
  parameters: object,
  callback?: function,
)

Defina a posição do cursor na janela candidata. Este será um ambiente autônomo se esta extensão não for proprietária do IME ativo.

Parâmetros

  • parâmetros

    objeto

    • candidateID

      number

      ID do candidato a ser selecionado.

    • contextID

      number

      ID do contexto proprietário da janela candidata.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (success: boolean) => void

    • sucesso

      boolean

Retorna

  • Promise<boolean>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

setMenuItems()

Promessa 
chrome.input.ime.setMenuItems(
  parameters: MenuParameters,
  callback?: function,
)

Adiciona os itens de menu fornecidos ao menu de idiomas quando este IME está ativo.

Parâmetros

  • parâmetros

    MenuParameters

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

updateMenuItems()

Promessa 
chrome.input.ime.updateMenuItems(
  parameters: MenuParameters,
  callback?: function,
)

Atualiza o estado dos MenuItems especificados

Parâmetros

  • parâmetros

    MenuParameters

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 111 ou versões mais recentes

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado para o callback.

Eventos

onActivate

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

Esse evento é enviado quando um IME é ativado. Sinaliza que o IME receberá eventos onKeyPress.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

onAssistiveWindowButtonClicked

Chrome 85 ou mais recente 
chrome.input.ime.onAssistiveWindowButtonClicked.addListener(
  callback: function,
)

Este evento é enviado quando um botão em uma janela assistiva é clicado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (details: object) => void

onBlur

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

Este evento é enviado quando o foco sai de uma caixa de texto. Ele é enviado a todas as extensões que estão detectando esse evento e ativado pelo usuário.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (contextID: number) => void

    • contextID

      number

onCandidateClicked

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

Este evento é enviado se esta extensão for proprietária do IME ativo.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • engineID

      string

    • candidateID

      number

    • botão

      MouseButton

onDeactivated

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

Esse evento é enviado quando um IME é desativado. Ele sinaliza que o IME não receberá mais eventos onKeyPress.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (engineID: string) => void

    • engineID

      string

onFocus

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

Esse evento é enviado quando o foco entra em uma caixa de texto. Ele é enviado a todas as extensões que estão detectando esse evento e ativado pelo usuário.

Parâmetros

onInputContextUpdate

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

Esse evento é enviado quando as propriedades do InputContext atual mudam, como o tipo. Ele é enviado a todas as extensões que estão detectando esse evento e ativado pelo usuário.

Parâmetros

onKeyEvent

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

Disparado quando um evento de tecla é enviado do sistema operacional. O evento será enviado para a extensão se ela for proprietária do IME ativo. A função do listener deve retornar verdadeiro se o evento tiver sido tratado como falso, se não foi. Se o evento for avaliado de forma assíncrona, essa função deverá retornar "undefined" e o IME precisará chamar keyEventHandled() com o resultado.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • retorna

      booleano | indefinido

onMenuItemActivated

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

Chamado quando o usuário seleciona um item de menu.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • engineID

      string

    • nome

      string

onReset

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

Este evento é enviado quando o Chrome encerra a sessão de entrada de texto em andamento.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (engineID: string) => void

    • engineID

      string

onSurroundingTextChanged

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

Chamado quando a string editável ao redor do cursor é alterada ou quando a posição do cursor é movida. O tamanho do texto é limitado a 100 caracteres para cada direção.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • engineID

      string

    • surroundingInfo

      objeto

      • âncora

        number

        Posição inicial da seleção. Esse valor indica a posição do cursor de texto se não houver seleção.

      • foco

        number

        A posição final da seleção. Esse valor indica a posição do cursor de texto se não houver seleção.

      • offset

        number

        Chrome 46 ou versão mais recente

        A posição de deslocamento de text. Como text inclui apenas um subconjunto de texto ao redor do cursor, o deslocamento indica a posição absoluta do primeiro caractere de text.

      • texto

        string

        O texto ao redor do cursor. Esse é apenas um subconjunto de todo o texto no campo de entrada.