chrome.omnibox

Descrizione

L'API omnibox ti consente di registrare una parola chiave con la 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 la tua estensione. Ogni tasto premuto viene inviato all'estensione e tu 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 omnibox keyword nel manifest. Devi anche specificare un'icona di 16x16 pixel, che verrà visualizzata nella barra degli indirizzi quando suggerisci agli utenti di attivare la modalità 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 della omnibox dal repository chrome-extension-samples.

Tipi

DefaultSuggestResult

Un risultato di suggerimento.

Proprietà

  • descrizione

    stringa

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

DescriptionStyleType

Chrome 44+

Il tipo di stile.

Enum

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44+

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 di suggerimento.

Proprietà

  • contenuti

    stringa

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

  • eliminabile

    booleano facoltativo

    Chrome 63+

    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 la formattazione. I tag supportati sono "url" (per un URL letterale), "match" (per evidenziare il testo che corrisponde alla query dell'utente) e "dim" (per il testo di aiuto attenuato). Gli stili possono essere nidificati, ad esempio la corrispondenza attenuata. Devi utilizzare l'interpretazione letterale delle cinque entità predefinite per visualizzarle come testo: stackoverflow.com/a/1091953/89484

Metodi

setDefaultSuggestion()

Promessa 
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 facoltativa

    Chrome 100+

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 100+

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

Eventi

onDeleteSuggestion

Chrome 63+ 
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

      • suggestResults

        SuggestResult[]

        Array di risultati dei suggerimenti

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. È garantito che venga 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