browser.input.ime

Важно! Этот API работает только в ChromeOS.

Описание

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

Разрешения

input

Чтобы использовать input.ime API, необходимо объявить разрешение input в манифесте расширения. Пример:

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

Доступность

Только для ChromeOS

Примеры

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

var context_id = -1;

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

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

Типы

AssistiveWindowButton

Chrome 85 и более поздних версий browser.* начиная с Chrome 148

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

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

"undo"

"addToDictionary"

AssistiveWindowProperties

Chrome 85 и более поздних версий browser.* начиная с Chrome 148

Свойства окна помощника.

Свойства

• announceString

  Строка (необязательно)

  Строки, которые озвучивает ChromeVox.

• тип

  "undo"
  

• отображается

  Логическое значение

  Если задано значение True, окно AssistiveWindow будет показываться, а если False – нет.

AssistiveWindowType

Chrome 85 и более поздних версий browser.* начиная с Chrome 148

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

Значение

"undo"

AutoCapitalizeType

Chrome 69 и более поздних версий browser.* начиная с Chrome 148

Тип автоматического использования заглавных букв в текстовом поле.

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

"characters"

"слова"

"sentences"

InputContext

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

Свойства

• autoCapitalize

  AutoCapitalizeType

  Chrome 69 и более поздних версий browser.* начиная с Chrome 148

  Тип автоматического использования заглавных букв в текстовом поле.

• autoComplete

  Логическое значение

  Нужно ли автозаполнение для текстового поля.

• autoCorrect

  Логическое значение

  Нужна ли автозамена для текстового поля.

• contextID

  число

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

• shouldDoLearning

  Логическое значение

  Chrome 68 и более поздние версии browser.* начиная с Chrome 148

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

• spellCheck

  Логическое значение

  Нужна ли проверка правописания в текстовом поле.

• тип

  InputContextType

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

InputContextType

Chrome 44+ browser.* начиная с Chrome 148

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

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

"text"

"search"

"tel"

"url"

"email"

"number"

"password"

"null"

KeyboardEvent

Подробную информацию можно найти на странице http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent.

Свойства

• altKey

  Логическое значение (необязательно)

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

• altgrKey

  Логическое значение (необязательно)

  Chrome 79+ browser.* начиная с Chrome 148

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

• capsLock

  Логическое значение (необязательно)

  Включен ли режим Caps Lock.

• код

  string

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

• ctrlKey

  Логическое значение (необязательно)

  Нажата ли клавиша Ctrl.

• extensionId

  Строка (необязательно)

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

• клавиша

  string

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

• keyCode

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

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

• requestId

  Строка (необязательно)

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

• shiftKey

  Логическое значение (необязательно)

  Нажата ли клавиша Shift.

• тип

  KeyboardEventType

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

KeyboardEventType

Chrome 44+ browser.* начиная с Chrome 148

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

"keyup"

"keydown"

MenuItem

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

Свойства

• выбрано

  Логическое значение (необязательно)

  Указывает, что этот элемент должен быть нарисован с флажком.

• включено

  Логическое значение (необязательно)

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

• id

  string

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

• ярлык

  Строка (необязательно)

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

• стиль

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

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

• отображается

  Логическое значение (необязательно)

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

MenuItemStyle

Chrome 44+ browser.* начиная с Chrome 148

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

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

"check"

"radio"

"separator"

MenuParameters

Chrome 88+ browser.* начиная с Chrome 148

Свойства

• engineID

  string

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

• items

  MenuItem[]

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

MouseButton

Chrome 44+ browser.* начиная с Chrome 148

Какая кнопка мыши была нажата.

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

"left"

"middle"

"right"

ScreenType

Chrome 44+ browser.* начиная с Chrome 148

Тип экрана, на котором активирован редактор метода ввода.

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

"normal"

"login"

"lock"

"secondary-login"

UnderlineStyle

Chrome 44+ browser.* начиная с Chrome 148

Тип подчеркивания, который нужно применить к этому сегменту.

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

"underline"

"doubleUnderline"

"noUnderline"

WindowPosition

Chrome 44+ browser.* начиная с Chrome 148

Где показывать окно кандидатов. Если выбрано значение cursor, окно будет перемещаться за курсором. Если задано значение composition, окно привязано к началу композиции.

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

"cursor"

"composition"

Методы

clearComposition()

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

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

Параметры

• Параметры

  Объект

  • contextID

    число

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

Возвраты

• Promise<boolean>

  Chrome 111+ browser.* начиная с Chrome 148

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

commitText()

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

Добавляет указанный текст в текущее поле ввода.

Параметры

• Параметры

  Объект

  • contextID

    число

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

  • Текст

    string

    Текст, который нужно зафиксировать.

Возвраты

• Promise<boolean>

  Chrome 111+ browser.* начиная с Chrome 148

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

deleteSurroundingText()

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

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

Параметры

• Параметры

  Объект

  • contextID

    число

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

  • engineID

    string

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

  • длина

    число

    Количество символов, которые нужно удалить.

  • вычесть

    число

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

Возвраты

• Promise<void>

  Chrome 111+ browser.* начиная с Chrome 148

  Выполняется после завершения операции.

hideInputView()

browser.input.ime.hideInputView(): void

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

keyEventHandled()

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

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

Параметры

• requestId

  string

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

• Ответ

  Логическое значение

  True, если нажатие клавиши было обработано; false, если нет

sendKeyEvents()

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

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

Параметры

• Параметры

  Объект

  • contextID

    число

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

  • keyData

    KeyboardEvent[]

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

Возвраты

• Promise<void>

  Chrome 111+ browser.* начиная с Chrome 148

  Выполняется после завершения операции.

setAssistiveWindowButtonHighlighted()

Chrome 86+ browser.* начиная с Chrome 148

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

Выделяет или снимает выделение с кнопки в окне специальных возможностей.

Параметры

• Параметры

  Объект

  • announceString

    Строка (необязательно)

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

  • buttonID

    AssistiveWindowButton

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

  • contextID

    число

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

  • выделенное

    Логическое значение

    Должна ли кнопка быть выделена.

  • windowType

    "undo"
    

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

Возвраты

• Promise<void>

  Chrome 111+ browser.* начиная с Chrome 148

  Выполняется после завершения операции. В случае сбоя объект Promise будет отклонен.

setAssistiveWindowProperties()

Chrome 85 и более поздних версий browser.* начиная с Chrome 148

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

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

Параметры

• Параметры

  Объект

  • contextID

    число

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

  • объекты

    AssistiveWindowProperties

    Свойства окна помощника.

Возвраты

• Promise<boolean>

  Chrome 111+ browser.* начиная с Chrome 148

  Выполняется после завершения операции.

setCandidates()

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

Задает текущий список кандидатов. Если расширение не владеет активным редактором метода ввода, произойдет сбой.

Параметры

• Параметры

  Объект

  • кандидатов

    object[]

    Список кандидатов, которые будут показаны в окне кандидатов.

    • аннотация

      Строка (необязательно)

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

    • вариант

      string

      Кандидат

    • id

      число

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

    • ярлык

      Строка (необязательно)

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

    • parentId

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

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

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

      Объект (необязательно)

      Описание использования или подробное описание слова.

      • body

        string

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

      • название

        string

        Строка заголовка описания.

  • contextID

    число

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

Возвраты

• Promise<boolean>

  Chrome 111+ browser.* начиная с Chrome 148

  Выполняется после завершения операции.

setCandidateWindowProperties()

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

Задает свойства окна кандидатов. Если расширение не владеет активным редактором метода ввода, произойдет сбой.

Параметры

• Параметры

  Объект

  • engineID

    string

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

  • объекты

    Объект

    • auxiliaryText

      Строка (необязательно)

      Текст, который показывается в нижней части окна кандидатов.

    • auxiliaryTextVisible

      Логическое значение (необязательно)

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

    • currentCandidateIndex

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

      Chrome 84+ browser.* начиная с Chrome 148

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

    • cursorVisible

      Логическое значение (необязательно)

      True, чтобы показать курсор, false, чтобы скрыть его.

    • pageSize

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

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

    • totalCandidates

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

      Chrome 84+ browser.* начиная с Chrome 148

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

    • вертикальном.

      Логическое значение (необязательно)

      True, если окно кандидатов должно быть вертикальным, и false, если горизонтальным.

    • отображается

      Логическое значение (необязательно)

      True, чтобы показать окно кандидатов, false, чтобы скрыть его.

    • windowPosition

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

      Где показывать окно кандидатов.

Возвраты

• Promise<boolean>

  Chrome 111+ browser.* начиная с Chrome 148

  Выполняется после завершения операции.

setComposition()

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

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

Параметры

• Параметры

  Объект

  • contextID

    число

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

  • курсор

    число

    Позиция курсора в тексте.

  • сегменты

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

    Список сегментов и связанных с ними типов.

    • end

      число

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

    • start

      число

      Индекс символа, с которого начинается сегмент.

    • стиль

      UnderlineStyle

      Тип подчеркивания, который нужно применить к этому сегменту.

  • selectionEnd

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

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

  • selectionStart

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

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

  • Текст

    string

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

Возвраты

• Promise<boolean>

  Chrome 111+ browser.* начиная с Chrome 148

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

setCursorPosition()

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

Установите позицию курсора в окне вариантов. Если расширение не владеет активным IME, ничего не происходит.

Параметры

• Параметры

  Объект

  • candidateID

    число

    Идентификатор кандидата, которого нужно выбрать.

  • contextID

    число

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

Возвраты

• Promise<boolean>

  Chrome 111+ browser.* начиная с Chrome 148

  Разрешается, когда операция завершается.

setMenuItems()

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

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

Параметры

• Параметры

  MenuParameters

Возвраты

• Promise<void>

  Chrome 111+ browser.* начиная с Chrome 148

updateMenuItems()

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

Обновляет статус указанных объектов MenuItems.

Параметры

• Параметры

  MenuParameters

Возвраты

• Promise<void>

  Chrome 111+ browser.* начиная с Chrome 148

  Разрешается, когда операция завершается.

События

onActivate

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

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

Параметры

• обратный вызов

  function

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

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

  • engineID

    string

  • Экран

    ScreenType

onAssistiveWindowButtonClicked

Chrome 85 и более поздних версий browser.* начиная с Chrome 148

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

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

Параметры

• обратный вызов

  function

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

  (details: object) => void

  • подробные сведения

    Объект

    • buttonID

      AssistiveWindowButton

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

    • windowType

      AssistiveWindowType

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

onBlur

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

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

Параметры

• обратный вызов

  function

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

  (contextID: number) => void

  • contextID

    число

onCandidateClicked

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

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

Параметры

• обратный вызов

  function

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

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

  • engineID

    string

  • candidateID

    число

  • кнопка

    MouseButton

onDeactivated

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

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

Параметры

• обратный вызов

  function

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

  (engineID: string) => void

  • engineID

    string

onFocus

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

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

Параметры

• обратный вызов

  function

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

  (context: InputContext) => void

  • context

    InputContext

onInputContextUpdate

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

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

Параметры

• обратный вызов

  function

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

  (context: InputContext) => void

  • context

    InputContext

onKeyEvent

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

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

Параметры

• обратный вызов

  function

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

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

  • engineID

    string

  • keyData

    KeyboardEvent

  • requestId

    string

  • Возвращает

    boolean | undefined

onMenuItemActivated

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

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

Параметры

• обратный вызов

  function

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

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

  • engineID

    string

  • name

    string

onReset

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

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

Параметры

• обратный вызов

  function

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

  (engineID: string) => void

  • engineID

    string

onSurroundingTextChanged

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

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

Параметры

• обратный вызов

  function

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

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

  • engineID

    string

  • surroundingInfo

    Объект

    • anchor

      число

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

    • фокус

      число

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

    • вычесть

      число

      Chrome 46 и более поздних версий browser.* начиная с Chrome 148

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

    • Текст

      string

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