chrome.omnibox

Description

L'API du champ polyvalent 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 pour le mot clé "Recherche Chromium"

Lorsqu'il 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 enrichies de différentes façons. Lorsque l'utilisateur accepte une suggestion, votre extension en est informée et peut prendre des mesures.

Manifest

Les clés suivantes doivent être déclarées dans le fichier manifeste pour utiliser cette API.

"omnibox"

Vous devez inclure un champ "omnibox.keyword" dans le fichier manifeste pour utiliser l'API de l'omnibox. Vous devez également spécifier une icône de 16 x 16 pixels, qui s'affichera dans la barre d'adresse lorsque les utilisateurs seront invités à 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 de l'omnibox à partir du dépôt chrome-extension-samples.

Types

DefaultSuggestResult

Suggestion de résultat.

Propriétés

  • description

    chaîne

    Texte affiché dans la liste déroulante des URL. Peut contenir un balisage XML pour l'application des styles. Les balises acceptées sont "url" (pour une URL littérale), "match" (pour mettre en surbrillance du texte correspondant à la requête de l'utilisateur) et "dim" (pour un texte d'aide sombre). Les styles peuvent être imbriqués (ils sont grisés, par exemple).

DescriptionStyleType

Chrome 44 ou version ultérieure

Type de style.

Enum

"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 permet d'accéder à une URL donnée, la mention "newForegroundTab" signifie que la navigation doit s'effectuer dans un nouvel onglet sélectionné.

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Suggestion de résultat.

Propriétés

  • de qualité, inédits, adaptés et variés

    chaîne

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

  • supprimer

    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 la liste déroulante des URL. Peut contenir un balisage XML pour l'application des styles. Les balises acceptées sont "url" (pour une URL littérale), "match" (pour mettre en surbrillance du texte correspondant à la requête de l'utilisateur) et "dim" (pour un texte d'aide sombre). Les styles peuvent être imbriqués (ils sont grisés, par exemple). 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()

Promesse 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
)

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 suggestion sous la barre d'adresse.

Paramètres

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

  • rappel

    fonction facultative

    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 sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.

É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

  • rappel

    function

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

    (text: string)=>void

    • text

      chaîne

onInputCancelled

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

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

Paramètres

  • rappel

    function

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

    ()=>void

onInputChanged

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

L'utilisateur a modifié le texte saisi dans l'omnibox.

Paramètres

  • rappel

    function

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

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

    • text

      chaîne

    • suggest

      function

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

      (suggestResults: SuggestResult[])=>void

      • suggestResults

        SuggestResult[]

        Tableau de résultats des suggestions

onInputEntered

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

L'utilisateur a accepté le texte 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. L'envoi est garanti exactement une fois par session d'entrée, et avant tout événement onInputChanged.

Paramètres

  • rappel

    function

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

    ()=>void