хром.омнибокс

дата обновления: 2026-09-25 robots: noindex

Описание

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

Скриншот с подсказками, связанными с ключевым словом «Chromium Search».

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

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

Манифест

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

Например:

{
  "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

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

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

  • описание

    нить

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

DescriptionStyleType

Chrome 44+

Тип стиля.

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

"url"

"соответствовать"

"тусклой"

OnInputEnteredDisposition

Chrome 44+

Контекст отображения результатов запроса в адресной строке. Это рекомендуемый контекст для отображения результатов. Например, если команда адресной строки предназначена для перехода по определенному URL-адресу, значение «newForegroundTab» означает, что навигация должна происходить в новой выбранной вкладке.

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

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

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

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

  • содержание

    нить

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

  • удаляемый

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

    Chrome 63+

    Можно ли пользователю удалить предложенный результат?

  • описание

    нить

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

Методы

setDefaultSuggestion()

Обещать
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
): Promise<void>

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

Параметры

  • предположение

    DefaultSuggestResult

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

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

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

    Chrome 100+

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

    () => void

Возвраты

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

    Chrome 100+

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

События

onDeleteSuggestion

Chrome 63+
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

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

Параметры

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

    функция

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

    (text: string) => void

    • текст

      нить

onInputCancelled

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

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

Параметры

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

    функция

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

    () => void

onInputChanged

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

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

Параметры

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

    функция

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

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

    • текст

      нить

    • предлагать

      функция

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

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult []

        Массив предлагаемых результатов

onInputEntered

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

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

Параметры

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

    функция

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

    (text: string, disposition: OnInputEnteredDisposition) => void

onInputStarted

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

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

Параметры

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

    функция

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

    () => void