chrome.omnibox

refresh date: 2026-09-25 robots: noindex

Описание

Omnibox API позволяет зарегистрировать ключевое слово в адресной строке Google Chrome, которая также называется омнибоксом.

Скриншот с подсказками, связанными с ключевым словом "Поиск в Chromium"

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

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

Манифест

Чтобы использовать API омнибокса, в манифест нужно добавить поле omnibox keyword. Также необходимо указать значок размером 16 x 16 пикселей, который будет отображаться в адресной строке, когда пользователям предлагается ввести ключевое слово.

Пример:

{
  "name": "Aaron's omnibox extension",
  "version": "1.0",
  "omnibox": { "keyword" : "aaron" },
  "icons": {
    "16": "16-full-color.png"
  },
  "background": {
    "persistent": false,
    "scripts": ["background.js"]
  }
}

Примеры

Чтобы попробовать этот API, установите пример omnibox API из репозитория chrome-extension-samples.

Типы

DefaultSuggestResult

Результат подсказки.

Свойства

  • описание

    string

    Текст, который показывается в раскрывающемся списке URL. Может содержать разметку в стиле XML для оформления. Поддерживаются теги url (для URL), match (для выделения текста, соответствующего запросу пользователя) и dim (для вспомогательного текста). Стили могут быть вложенными, например затемненное совпадение.

DescriptionStyleType

Chrome 44 и более поздних версий;

Тип стиля.

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

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 и более поздних версий;

Расположение окна для запроса в омнибоксе. Это рекомендуемый контекст для показа результатов. Например, если команда омнибокса заключается в переходе по определенному URL, то значение newForegroundTab означает, что переход должен произойти в новой выбранной вкладке.

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

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Результат подсказки.

Свойства

  • контент

    string

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

  • удаляемый

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

    Chrome 63 и более поздних версий;

    Может ли пользователь удалить результат подсказки.

  • описание

    string

    Текст, который показывается в раскрывающемся списке URL. Может содержать разметку в стиле XML для оформления. Поддерживаются теги url (для URL), match (для выделения текста, соответствующего запросу пользователя) и dim (для вспомогательного текста). Стили могут быть вложенными, например затемненное совпадение. Чтобы пять предопределенных объектов отображались как текст, их нужно экранировать: stackoverflow.com/a/1091953/89484.

Методы

setDefaultSuggestion()

Promise 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
): Promise<void>

Задает описание и стиль для подсказки по умолчанию. Подсказка по умолчанию – это текст, который показывается в первой строке подсказок под адресной строкой.

Параметры

  • подсказка

    DefaultSuggestResult

    Частичный объект SuggestResult без параметра content.

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

    function необязательно

    Chrome 100+

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

    () => void

Возвраты

  • Promise<void>

    Chrome 100+

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onDeleteSuggestion

Chrome 63 и более поздних версий; 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

Пользователь удалил предложенный результат.

Параметры

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

    function

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

    (text: string) => void

    • Текст

      string

onInputCancelled

chrome.omnibox.onInputCancelled.addListener(
  callback: function,
)

Пользователь завершил сеанс ввода ключевых слов, не приняв введенные данные.

Параметры

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

    function

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

    () => void

onInputChanged

chrome.omnibox.onInputChanged.addListener(
  callback: function,
)

Пользователь изменил текст в омнибоксе.

Параметры

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

    function

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

    (text: string, suggest: function) => void

    • Текст

      string

    • подсказки

      function

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

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

        Массив результатов подсказок

onInputEntered

chrome.omnibox.onInputEntered.addListener(
  callback: function,
)

Пользователь принял то, что введено в омнибокс.

Параметры

onInputStarted

chrome.omnibox.onInputStarted.addListener(
  callback: function,
)

Пользователь начал сеанс ввода ключевого слова, введя ключевое слово расширения. Это событие гарантированно отправляется ровно один раз за сеанс ввода и до любых событий onInputChanged.

Параметры

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

    function

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

    () => void