chrome.omnibox

refresh date: 2026-09-25 robots: noindex

Description

L'API Omnibox vous permet d'enregistrer un mot clé dans la barre d'adresse de Google Chrome, également appelée "omnibox".

Capture d'écran montrant des suggestions liées au mot clé "Recherche Chromium"

Lorsque l'utilisateur saisit le mot clé de votre extension, il commence à interagir uniquement avec votre extension. Chaque frappe est envoyée à votre extension, et vous pouvez fournir des suggestions en réponse.

Les suggestions peuvent être mises en forme de différentes manières. Lorsque l'utilisateur accepte une suggestion, votre extension est avertie et peut agir.

Fichier manifeste

Vous devez inclure un champ omnibox keyword dans le manifeste pour utiliser l'API Omnibox. Vous devez également spécifier une icône de 16 x 16 pixels, qui s'affichera dans la barre d'adresse lorsque vous suggérerez aux utilisateurs de passer en mode mot clé.

Exemple :

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

Exemples

Pour essayer cette API, installez l'exemple d'API Omnibox à partir du dépôt chrome-extension-samples.

Types

DefaultSuggestResult

Résultat de suggestion.

Propriétés

  • description

    chaîne

    Texte affiché dans le menu déroulant de l'URL. Peut contenir un balisage de style XML. Les balises acceptées sont "url" (pour une URL littérale), "match" (pour mettre en surbrillance le texte correspondant à la requête de l'utilisateur) et "dim" (pour atténuer le texte d'aide). Les styles peuvent être imbriqués, par exemple "correspondance atténuée".

DescriptionStyleType

Chrome 44 et versions ultérieures

Type de style.

Énumération

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 et versions ultérieures

Disposition de la fenêtre pour la requête de la barre d'adresse. Il s'agit du contexte recommandé pour afficher les résultats. Par exemple, si la commande de la barre d'adresse est de naviguer vers une URL spécifique, une disposition "newForegroundTab" signifie que la navigation doit avoir lieu dans un nouvel onglet sélectionné.

Énumération

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Suggestion de résultat.

Propriétés

  • contenu

    chaîne

    Texte saisi dans la barre d'URL et envoyé à l'extension lorsque l'utilisateur choisit cette entrée.

  • supprimable

    booléen facultatif

    Chrome 63 et versions ultérieures

    Indique si le résultat de la suggestion peut être supprimé par l'utilisateur.

  • description

    chaîne

    Texte affiché dans le menu déroulant de l'URL. Peut contenir un balisage de style XML. Les balises acceptées sont "url" (pour une URL littérale), "match" (pour mettre en surbrillance le texte correspondant à la requête de l'utilisateur) et "dim" (pour atténuer le texte d'aide). Les styles peuvent être imbriqués, par exemple "correspondance atténuée". Vous devez utiliser des caractères d'échappement pour les cinq entités prédéfinies afin de les afficher sous forme de texte : stackoverflow.com/a/1091953/89484.

Méthodes

setDefaultSuggestion()

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

Définit la description et le style de la suggestion par défaut. La suggestion par défaut est le texte affiché dans la première ligne de suggestions sous la barre d'URL.

Paramètres

  • Objet SuggestResult partiel, sans le paramètre "content".

  • callback

    function facultatif

    Chrome 100 et versions ultérieures

    Le paramètre callback se présente comme suit : 

    () => void

Renvoie

  • Promise<void>

    Chrome 100 et versions ultérieures

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Événements

onDeleteSuggestion

Chrome 63 et versions ultérieures 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

L'utilisateur a supprimé un résultat suggéré.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (text: string) => void

    • texte

      chaîne

onInputCancelled

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

L'utilisateur a mis fin à la session de saisie de mots clés sans accepter la saisie.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    () => void

onInputChanged

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

L'utilisateur a modifié ce qu'il a saisi dans l'omnibox.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

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

    • texte

      chaîne

    • suggest

      fonction

      Le paramètre suggest se présente comme suit : 

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

        Tableau des résultats de suggestion

onInputEntered

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

L'utilisateur a accepté ce qui a été saisi dans l'omnibox.

Paramètres

onInputStarted

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

L'utilisateur a démarré une session de saisie de mots clés en saisissant le mot clé de l'extension. Il est garanti qu'il sera envoyé exactement une fois par session d'entrée et avant tout événement onInputChanged.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    () => void