chrome.omnibox

refresh date: 2026-09-25 robots: noindex

Descrizione

L'API omnibox ti consente di registrare una parola chiave nella barra degli indirizzi di Google Chrome, nota anche come omnibox.

Uno screenshot che mostra i suggerimenti relativi alla parola chiave "Ricerca Chromium"

Quando l'utente inserisce la parola chiave dell'estensione, inizia a interagire esclusivamente con l'estensione. Ogni pressione di un tasto viene inviata alla tua estensione e puoi fornire suggerimenti in risposta.

I suggerimenti possono essere formattati in vari modi. Quando l'utente accetta un suggerimento, la tua estensione riceve una notifica e può intervenire.

Manifest

Per utilizzare l'API omnibox, devi includere un campo keyword omnibox nel manifest. Devi anche specificare un'icona di 16 x 16 pixel, che verrà visualizzata nella barra degli indirizzi quando viene suggerito agli utenti di attivare la modalità di ricerca per parole chiave.

Ad esempio:

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

Esempi

Per provare questa API, installa l'esempio di API omnibox dal repository chrome-extension-samples.

Tipi

DefaultSuggestResult

Un risultato suggerito.

Proprietà

  • descrizione

    stringa

    Il testo visualizzato nel menu a discesa dell'URL. Può contenere markup in stile XML per lo stile. I tag supportati sono "url" (per un URL letterale), "match" (per evidenziare il testo corrispondente alla query dell'utente) e "dim" (per il testo di aiuto con luminosità ridotta). Gli stili possono essere nidificati, ad esempio corrispondenza con luminosità ridotta.

DescriptionStyleType

Chrome 44 e versioni successive

Il tipo di stile.

Enum

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 e versioni successive

La disposizione della finestra per la query della omnibox. Questo è il contesto consigliato per visualizzare i risultati. Ad esempio, se il comando della omnibox è di andare a un determinato URL, una disposizione "newForegroundTab" indica che la navigazione deve avvenire in una nuova scheda selezionata.

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Un risultato suggerito.

Proprietà

  • contenuti

    stringa

    Il testo che viene inserito nella barra degli URL e che viene inviato all'estensione quando l'utente sceglie questa voce.

  • eliminabile

    boolean facoltativo

    Chrome 63 e versioni successive

    Indica se il risultato del suggerimento può essere eliminato dall'utente.

  • descrizione

    stringa

    Il testo visualizzato nel menu a discesa dell'URL. Può contenere markup in stile XML per lo stile. I tag supportati sono "url" (per un URL letterale), "match" (per evidenziare il testo corrispondente alla query dell'utente) e "dim" (per il testo di aiuto con luminosità ridotta). Gli stili possono essere nidificati, ad esempio corrispondenza con luminosità ridotta. Devi eseguire l'escape delle cinque entità predefinite per visualizzarle come testo: stackoverflow.com/a/1091953/89484

Metodi

setDefaultSuggestion()

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

Imposta la descrizione e lo stile del suggerimento predefinito. Il suggerimento predefinito è il testo visualizzato nella prima riga di suggerimenti sotto la barra degli URL.

Parametri

  • suggerimento

    DefaultSuggestResult

    Un oggetto SuggestResult parziale, senza il parametro "content".

  • callback

    funzione elemento facoltativo

    Chrome 100+

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 100+

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Eventi

onDeleteSuggestion

Chrome 63 e versioni successive 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

L'utente ha eliminato un risultato suggerito.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (text: string) => void

    • testo

      stringa

onInputCancelled

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

L'utente ha terminato la sessione di inserimento delle parole chiave senza accettare l'input.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onInputChanged

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

L'utente ha modificato il testo digitato nella omnibox.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

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

    • testo

      stringa

    • suggest

      funzione

      Il parametro suggest ha il seguente aspetto: 

      (suggestResults: SuggestResult[]) => void

onInputEntered

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

L'utente ha accettato ciò che è stato digitato nella omnibox.

Parametri

onInputStarted

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

L'utente ha avviato una sessione di inserimento di parole chiave digitando la parola chiave dell'estensione. Questo evento viene inviato esattamente una volta per sessione di input e prima di qualsiasi evento onInputChanged.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void