chrome.input.ime

Важно: этот API работает только на ChromeOS .

Описание

Используйте API chrome.input.ime для реализации пользовательского IME для Chrome OS. Это позволит вашему расширению обрабатывать нажатия клавиш, устанавливать параметры композиции и управлять окнами-кандидатами.

Разрешения

input

Доступность

Только для ChromeOS

Манифест

Для использования API input.ime необходимо указать разрешение "input" в манифесте расширения . Например:

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

Примеры

Следующий код создает IME, который преобразует набранные буквы в верхний регистр.

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

Типы

AssistiveWindowButton

Chrome 85+

Идентификаторы кнопок в окне помощи.

Перечисление

"отменить"

"addToDictionary"

AssistiveWindowProperties

Chrome 85+

Свойства вспомогательного окна.

Характеристики

• announceString

  строка необязательный

  Строки для озвучивания в ChromeVox.

• тип

  "отменить"
  

• видимый

  логический

  Устанавливает значение true для отображения AssistiveWindow, устанавливает значение false для его скрытия.

AssistiveWindowType

Chrome 85+

Тип вспомогательного окна.

Ценить

"отменить"

AutoCapitalizeType

Chrome 69+

Тип автоматического преобразования регистра в текстовом поле.

Перечисление

"персонажи"

"слова"

«предложения»

InputContext

Описывает контекст ввода.

Характеристики

• автокапитализация

  AutoCapitalizeType

  Chrome 69+

  Тип автоматического преобразования регистра в текстовом поле.

• автозаполнение

  логический

  Указывается, требуется ли автозаполнение в текстовом поле.

• автокоррекция

  логический

  Указывает, требуется ли автокоррекция для текстового поля.

• contextID

  число

  Этот идентификатор используется для указания целей операций с текстовым полем. Он становится недействительным сразу после вызова функции onBlur.

• shouldDoLearning

  логический

  Chrome 68+

  Следует ли использовать текст, введенный в текстовое поле, для улучшения подсказок при наборе текста для пользователя?

• проверка орфографии

  логический

  Указывает, требуется ли проверка орфографии для текстового поля.

• тип

  InputContextType

  Тип значения, которое редактирует это текстовое поле (текст, число, URL и т. д.)

InputContextType

Chrome 44+

Тип значения, которое редактирует это текстовое поле (текст, число, URL и т. д.)

Перечисление

"текст"

"поиск"

"тел"

"url"

"электронная почта"

"число"

"пароль"

"нулевой"

KeyboardEvent

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

Характеристики

• altKey

  логический необязательный

  Нажата ли клавиша ALT или нет.

• altgrKey

  логический необязательный

  Chrome 79+

  Нажата ли клавиша ALTGR или нет.

• capsLock

  логический необязательный

  Включена ли клавиша CAPS_LOCK.

• код

  нить

  Значение нажимаемой физической клавиши. Это значение не зависит от текущей раскладки клавиатуры или состояния клавиши-модификатора.

• Ctrl

  логический необязательный

  Нажата ли клавиша CTRL или нет.

• extensionId

  строка необязательный

  Идентификатор расширения отправителя данного события нажатия клавиши.

• ключ

  нить

  Значение нажатой клавиши

• keyCode

  число необязательно

  Устаревший HTML-код keyCode, представляющий собой зависящий от системы и реализации числовой код, обозначающий неизмененный идентификатор, связанный с нажатой клавишей.

• requestId

  строка необязательный

  (Устарело) Идентификатор запроса. Вместо него используйте параметр requestId из события onKeyEvent .

• клавиша Shift

  логический необязательный

  Нажата ли клавиша SHIFT или нет.

• тип

  KeyboardEventType

  Одно из значений keyup или keydown.

KeyboardEventType

Chrome 44+

Перечисление

"keyup"

"нажатие клавиши"

MenuItem

Пункт меню, используемый методом ввода для взаимодействия с пользователем из языкового меню.

Характеристики

• проверено

  логический необязательный

  Указывает, что этот пункт следует отметить галочкой.

• включено

  логический необязательный

  Указывает на то, что этот элемент включен.

• идентификатор

  нить

  Строка, которая будет передана в функции обратного вызова, ссылающиеся на этот пункт меню.

• этикетка

  строка необязательный

  Текст, отображаемый в меню для этого пункта.

• стиль

  MenuItemStyle optional

  Тип пункта меню.

• видимый

  логический необязательный

  Указывает на то, что этот элемент виден.

MenuItemStyle

Chrome 44+

Тип пункта меню. Переключатели между разделителями считаются сгруппированными.

Перечисление

"проверять"

"радио"

«разделитель»

MenuParameters

Chrome 88+

Характеристики

• engineID

  нить

  Идентификатор используемого двигателя.

• предметы

  Пункт меню []

  Пункты меню для добавления или обновления. Они будут добавлены в том порядке, в котором они находятся в массиве.

MouseButton

Chrome 44+

Какие кнопки мыши были нажаты?

Перечисление

"левый"

"середина"

"верно"

ScreenType

Chrome 44+

Тип экрана, при котором активируется IME.

Перечисление

"нормальный"

"авторизоваться"

"замок"

"вторичный вход в систему"

UnderlineStyle

Chrome 44+

Тип подчеркивания для изменения данного сегмента.

Перечисление

«подчеркнуть»

"двойное подчеркивание"

"noUnderline"

WindowPosition

Chrome 44+

Где отображать окно-кандидат. Если установлено значение «курсор», окно следует за курсором. Если установлено значение «композиция», окно привязывается к началу композиции.

Перечисление

"курсор"

"композиция"

Методы

clearComposition()

Обещать

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

Очистить текущую композицию. Если это расширение не владеет активным IME, операция завершится неудачей.

Параметры

• параметры

  объект

  • contextID

    число

    Идентификатор контекста, в котором будет удалена композиция.

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  (success: boolean) => void

  • успех

    логический

Возвраты

• Promise<boolean>

  Chrome 111+

  Результатом выполнения операции является логическое значение, указывающее, был ли текст принят или нет. В случае неудачи обещание будет отклонено.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

commitText()

Обещать

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

Подтверждает ввод предоставленного текста в текущее поле ввода.

Параметры

• параметры

  объект

  • contextID

    число

    Идентификатор контекста, в котором будет зафиксирован текст.

  • текст

    нить

    Текст для подтверждения

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  (success: boolean) => void

  • успех

    логический

Возвраты

• Promise<boolean>

  Chrome 111+

  Результатом выполнения операции является логическое значение, указывающее, был ли текст принят или нет. В случае неудачи обещание будет отклонено.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

deleteSurroundingText()

Обещать

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

Удаляет текст вокруг курсора.

Параметры

• параметры

  объект

  • contextID

    число

    Идентификатор контекста, из которого будет удален окружающий текст.

  • engineID

    нить

    Идентификатор двигателя, получившего событие.

  • длина

    число

    Количество символов для удаления

  • компенсировать

    число

    Смещение относительно позиции курсора, с которой начнется удаление. Это значение может быть отрицательным.

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Обещание<пустота>

  Chrome 111+

  Проблема решается после завершения операции.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

hideInputView()

chrome.input.ime.hideInputView(): void

Скрывает окно ввода, которое автоматически открывается системой. Если окно ввода уже скрыто, эта функция ничего не сделает.

keyEventHandled()

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

Указывает, что событие нажатия клавиши, полученное через onKeyEvent, обрабатывается. Этот метод следует вызывать только в том случае, если обработчик onKeyEvent является асинхронным.

Параметры

• requestId

  нить

  Идентификатор запроса обработанного события. Он должен быть получен из keyEvent.requestId.

• ответ

  логический

  Возвращает true, если нажатие клавиши было обработано, false — если нет.

sendKeyEvents()

Обещать

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

Отправляет события нажатия клавиш. Предполагается, что эта функция будет использоваться виртуальными клавиатурами. Когда пользователь нажимает одну или несколько клавиш на виртуальной клавиатуре, эта функция используется для распространения этого события в систему.

Параметры

• параметры

  объект

  • contextID

    число

    Идентификатор контекста, куда будут отправляться события нажатия клавиш, или ноль для отправки событий нажатия клавиш в поле, не являющееся полем ввода.

  • keyData

    KeyboardEvent []

    Данные о ключевом событии.

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Обещание<пустота>

  Chrome 111+

  Проблема решается после завершения операции.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setAssistiveWindowButtonHighlighted()

Promise Chrome 86+

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

Выделяет/снимает выделение с кнопки во вспомогательном окне.

Параметры

• параметры

  объект

  • announceString

    строка необязательный

    Текст для озвучивания программой чтения с экрана.

  • buttonID

    Вспомогательная кнопка окна

    Идентификатор кнопки

  • contextID

    число

    Идентификатор контекста, которому принадлежит вспомогательное окно.

  • выделенный

    логический

    Следует ли выделить кнопку?

  • windowType

    "отменить"
    

    Тип окна, к которому относится кнопка.

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Обещание<пустота>

  Chrome 111+

  Завершается после окончания операции. В случае неудачи обещание будет отклонено.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setAssistiveWindowProperties()

Promise Chrome 85+

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

Отображает/скрывает вспомогательное окно с заданными свойствами.

Параметры

• параметры

  объект

  • contextID

    число

    Идентификатор контекста, которому принадлежит вспомогательное окно.

  • характеристики

    AssistiveWindowProperties

    Свойства вспомогательного окна.

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  (success: boolean) => void

  • успех

    логический

Возвраты

• Promise<boolean>

  Chrome 111+

  Проблема решается после завершения операции.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setCandidates()

Обещать

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

Устанавливает текущий список кандидатов. Эта функция не сработает, если данное расширение не является владельцем активного IME.

Параметры

• параметры

  объект

  • кандидаты

    объект[]

    Список кандидатов для отображения в окне кандидата

    • аннотация

      строка необязательный

      Дополнительный текст с описанием кандидата

    • кандидат

      нить

      Кандидат

    • идентификатор

      число

      Идентификационный номер кандидата

    • этикетка

      строка необязательный

      Рядом с кандидатом отображается короткая строка, часто это сочетание клавиш или индекс.

    • parentId

      число необязательно

      Идентификатор для добавления этих кандидатов в разделе

    • использование

      объект необязательный

      Употребление или подробное описание слова.

      • тело

        нить

        Основной текст описания.

      • заголовок

        нить

        Строка заголовка с подробным описанием.

  • contextID

    число

    Идентификатор контекста, которому принадлежит окно выбора кандидата.

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  (success: boolean) => void

  • успех

    логический

Возвраты

• Promise<boolean>

  Chrome 111+

  Проблема решается после завершения операции.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setCandidateWindowProperties()

Обещать

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

Устанавливает свойства окна-кандидата. Это не сработает, если расширение не владеет активным IME.

Параметры

• параметры

  объект

  • engineID

    нить

    Идентификатор движка, для которого необходимо установить свойства.

  • характеристики

    объект

    • вспомогательный текст

      строка необязательный

      Текст, отображаемый в нижней части окна выбора кандидата.

    • auxiliaryTextVisible

      логический необязательный

      Значение True отображает вспомогательный текст, значение False скрывает его.

    • текущийИндексКандидатов

      число необязательно

      Chrome 84+

      Индекс текущего выбранного кандидата среди всех кандидатов.

    • cursorVisible

      логический необязательный

      Значение True отображает курсор, значение False скрывает его.

    • размер страницы

      число необязательно

      Количество кандидатов, отображаемых на странице.

    • общее количество кандидатов

      число необязательно

      Chrome 84+

      Общее количество кандидатов в течение этого периода.

    • вертикальный

      логический необязательный

      Значение True указывает на необходимость вертикального отображения окна-кандидата, значение False — на горизонтальное.

    • видимый

      логический необязательный

      Значение True отображает окно с кандидатами, значение False скрывает его.

    • windowPosition

      WindowPosition ( необязательно)

      Где отобразить окно с кандидатами.

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  (success: boolean) => void

  • успех

    логический

Возвраты

• Promise<boolean>

  Chrome 111+

  Проблема решается после завершения операции.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setComposition()

Обещать

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

Установите текущий состав. Если это расширение не владеет активным IME, установка не удастся.

Параметры

• параметры

  объект

  • contextID

    число

    Идентификатор контекста, в котором будет установлен текст композиции.

  • курсор

    число

    Укажите положение курсора в тексте.

  • сегменты

    объект[] необязательный

    Список сегментов и соответствующих им типов.

    • конец

      число

      Указатель символов, после которых следует завершать этот сегмент.

    • начинать

      число

      Указатель символа, с которого начинается этот сегмент.

    • стиль

      UnderlineStyle

      Тип подчеркивания для изменения данного сегмента.

  • selectionEnd

    число необязательно

    Место в тексте, где заканчивается выделенный фрагмент.

  • selectionStart

    число необязательно

    Позиция в тексте, с которой начинается выделение.

  • текст

    нить

    Текст для установки

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  (success: boolean) => void

  • успех

    логический

Возвраты

• Promise<boolean>

  Chrome 111+

  Результатом выполнения операции является логическое значение, указывающее, был ли текст принят или нет. В случае неудачи обещание будет отклонено.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setCursorPosition()

Обещать

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

Установите положение курсора в окне выбора варианта. Это действие не выполняется, если данное расширение не владеет активным IME.

Параметры

• параметры

  объект

  • идентификатор кандидата

    число

    Идентификационный номер кандидата для выбора.

  • contextID

    число

    Идентификатор контекста, которому принадлежит окно выбора кандидата.

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  (success: boolean) => void

  • успех

    логический

Возвраты

• Promise<boolean>

  Chrome 111+

  Завершается после окончания операции.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setMenuItems()

Обещать

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

Добавляет указанные пункты меню в языковое меню, когда этот IME активен.

Параметры

• параметры

  Параметры меню

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Обещание<пустота>

  Chrome 111+

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

updateMenuItems()

Обещать

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

Обновляет состояние указанных пунктов меню.

Параметры

• параметры

  Параметры меню

• перезвонить

  функция необязательна

  Параметр callback выглядит следующим образом:

  () => void

Возвраты

• Обещание<пустота>

  Chrome 111+

  Завершается после окончания операции.

  Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

События

onActivate

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

Это событие отправляется при активации IME. Оно сигнализирует о том, что IME будет получать события onKeyPress.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

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

  • engineID

    нить

  • экран

    ScreenType

onAssistiveWindowButtonClicked

Chrome 85+

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

Это событие отправляется при нажатии кнопки во вспомогательном окне.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

  (details: object) => void

  • подробности

    объект

    • buttonID

      Вспомогательная кнопка окна

      Идентификатор нажатой кнопки.

    • windowType

      AssistiveWindowType

      Тип вспомогательного окна.

onBlur

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

Это событие отправляется, когда фокус покидает текстовое поле. Оно отправляется всем расширениям, которые прослушивают это событие и активированы пользователем.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

  (contextID: number) => void

  • contextID

    число

onCandidateClicked

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

Это событие отправляется, если данное расширение владеет активным IME.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

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

  • engineID

    нить

  • идентификатор кандидата

    число

  • кнопка

    Кнопка мыши

onDeactivated

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

Это событие отправляется при деактивации IME. Оно сигнализирует о том, что IME больше не будет получать события onKeyPress.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

  (engineID: string) => void

  • engineID

    нить

onFocus

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

Это событие отправляется, когда фокус попадает в текстовое поле. Оно отправляется всем расширениям, которые прослушивают это событие и активированы пользователем.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

  (context: InputContext) => void

  • контекст

    InputContext

onInputContextUpdate

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

Это событие отправляется при изменении свойств текущего InputContext, например, его типа. Оно отправляется всем расширениям, которые прослушивают это событие и активированы пользователем.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

  (context: InputContext) => void

  • контекст

    InputContext

onKeyEvent

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

Событие срабатывает при отправке события нажатия клавиши из операционной системы. Событие будет отправлено расширению, если это расширение владеет активным IME. Функция прослушивания должна возвращать true, если событие было обработано, и false, если нет. Если событие будет обрабатываться асинхронно, эта функция должна возвращать undefined, и IME должен позже вызвать keyEventHandled() с результатом.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

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

  • engineID

    нить

  • keyData

    KeyboardEvent

  • requestId

    нить

  • возвраты

    логическое значение | неопределенное

onMenuItemActivated

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

Вызывается, когда пользователь выбирает пункт меню.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

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

  • engineID

    нить

  • имя

    нить

onReset

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

Это событие отправляется, когда Chrome завершает текущую сессию ввода текста.

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

  (engineID: string) => void

  • engineID

    нить

onSurroundingTextChanged

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

Вызывается при изменении редактируемой строки вокруг курсора или при перемещении курсора. Длина текста ограничена 100 символами для каждого направления (вперед и назад).

Параметры

• перезвонить

  функция

  Параметр callback выглядит следующим образом:

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

  • engineID

    нить

  • окружающая информация

    объект

    • якорь

      число

      Начальная позиция выделенного фрагмента. Это значение указывает позицию курсора, если выделение отсутствует.

    • фокус

      число

      Конечная позиция выделенного фрагмента. Это значение указывает позицию курсора, если выделение отсутствует.

    • компенсировать

      число

      Chrome 46+

      Смещение text . Поскольку text включает только часть текста вокруг курсора, смещение указывает абсолютное положение первого символа text .

    • текст

      нить

      Текст вокруг курсора. Это лишь часть всего текста в поле ввода.