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 suggerimenti correlati alla parola chiave "Ricerca Chromium"

Quando l'utente inserisce la parola chiave dell'estensione, inizia a interagire esclusivamente con l'estensione. Ogni sequenza di tasti viene inviata all'estensione e tu puoi fornire suggerimenti in risposta.

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

Manifest

Per poter utilizzare questa API, le seguenti chiavi devono essere dichiarate nel manifest.

"omnibox"

Per utilizzare l'API omnibox, devi includere un campo "omnibox.keyword" nel manifest. Devi anche specificare un'icona di 16 x 16 pixel che verrà visualizzata nella barra degli indirizzi suggerendo agli utenti di attivare la modalità parola 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 dell'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 l'applicazione di stili. I tag supportati sono "url" (per un URL letterale), "match" (per evidenziare il testo che corrisponde alla query dell'utente) e "attenua" (per il testo di supporto sfumato). Gli stili possono essere nidificati, ad esempio con corrispondenza in grigio.

DescriptionStyleType

Chrome 44 e versioni successive

Il tipo di stile.

Enum

"url"

OnInputEnteredDisposition

Chrome 44 e versioni successive

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

Enum

"newBackgroundTab"

SuggestResult

Un risultato suggerito.

Proprietà

  • nuovi, di alta qualità, pertinenti e variegati

    stringa

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

  • eliminabile

    booleano 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 l'applicazione di stili. I tag supportati sono "url" (per un URL letterale), "match" (per evidenziare il testo che corrisponde alla query dell'utente) e "attenua" (per il testo di supporto sfumato). Gli stili possono essere nidificati, ad esempio con corrispondenza in grigio. Devi eseguire l'escape delle cinque entità predefinite per visualizzarle come testo: stackoverflow.com/a/1091953/89484

Metodi

setDefaultSuggestion()

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

Imposta la descrizione e lo stile per il suggerimento predefinito. Il suggerimento predefinito è il testo visualizzato nella prima riga di suggerimento sotto la barra dell'URL.

Parametri

  • suggerimento

    DefaultSuggestResult

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

  • callback

    funzione facoltativa

    Chrome 100 e versioni successive

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 100 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al 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 parola 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 il testo digitato nella omnibox.

Parametri

onInputStarted

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

L'utente ha avviato una sessione di inserimento parola chiave digitando la parola chiave dell'estensione. Deve essere 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