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 fichier 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 pour suggérer aux utilisateurs d'activer le 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 d'une suggestion.

Propriétés

  • description

    chaîne

    Texte affiché dans le menu déroulant de l'URL. Peut contenir un balisage de style XML pour le style. 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 le texte d'aide estompé). Les styles peuvent être imbriqués, par exemple "dimmed match".

DescriptionStyleType

Chrome 44 ou version ultérieure

Type de style.

Énumération

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 ou version ultérieure

Disposition de la fenêtre pour la requête de l'omnibox. Il s'agit du contexte recommandé pour afficher les résultats. Par exemple, si la commande de l'omnibox consiste à accéder à une certaine URL, une disposition "newForegroundTab" signifie que la navigation doit s'effectuer dans un nouvel onglet sélectionné.

Énumération

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Résultat d'une suggestion.

Propriétés

  • contenu

    chaîne

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

  • deletable

    boolean facultatif

    Chrome 63 ou version ultérieure

    Indique si le résultat suggéré 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 pour le style. 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 le texte d'aide estompé). Les styles peuvent être imbriqués, par exemple "dimmed match". Vous devez échapper les cinq entités prédéfinies pour 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 qui s'affiche sur la première ligne de suggestion sous la barre d'URL.

Paramètres

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

  • callback

    function facultatif

    Chrome 100 ou version ultérieure

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

    () => void

Renvoie

  • Promise<void>

    Chrome 100 ou version ultérieure

    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 ou version ultérieure 
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 qui est 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 est saisi dans l'omnibox.

Paramètres

onInputStarted

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

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

Paramètres

  • callback

    fonction

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

    () => void