chrome.omnibox

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é "Chromium Search"

Lorsque l'utilisateur saisit le mot clé de votre extension, il commence à interagir uniquement avec celle-ci. 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 reçoit une notification et peut effectuer une action.

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 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 Omnibox. Il s'agit du contexte recommandé pour afficher les résultats. Par exemple, si la commande de la barre d'adresse consiste à accéder à 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

Résultat de suggestion.

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 l'utilisateur peut supprimer le résultat de la suggestion.

  • 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 qui s'affiche 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 l'entrée.

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 commencé 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