chrome.omnibox

Descrição

A API omnibox permite que você registre uma palavra-chave na barra de endereço do Google Chrome, que também é conhecida como omnibox.

Captura de tela mostrando sugestões relacionadas à palavra-chave "Pesquisa do Chromium"

Quando o usuário insere a palavra-chave da sua extensão, o usuário começa a interagir apenas com ela. Cada tecla pressionada é enviada para sua extensão, e você pode fornecer sugestões em resposta.

As sugestões podem ser ricamente formatadas de várias maneiras. Quando o usuário aceita uma sugestão, a extensão é notificada e pode agir.

Manifesto

As chaves a seguir precisam ser declaradas no manifesto para o uso dessa API.

"omnibox"

É necessário incluir um campo "omnibox.keyword" no manifesto para usar a API omnibox. Também é necessário especificar um ícone de 16 por 16 pixels, que será exibido na barra de endereço ao sugerir que os usuários entrem no modo de palavra-chave.

Exemplo:

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

Exemplos

Para testar essa API, instale o exemplo da API omnibox no repositório chrome-extension-samples.

Tipos

DefaultSuggestResult

Um resultado sugerido.

Propriedades

  • descrição

    string

    O texto que é exibido no menu suspenso de URL. Pode conter marcação no estilo XML para estilo. As tags aceitas são "url" (para um URL literal), "match" (para destacar texto que corresponde à consulta do usuário) e "dim" (para texto auxiliar esmaecido). Os estilos podem ser aninhados, por exemplo, correspondência esmaecida.

DescriptionStyleType

Chrome 44 ou mais recente

Tipo de estilo.

Tipo enumerado

"url"

OnInputEnteredDisposition

Chrome 44 ou mais recente

A disposição da janela para a consulta da omnibox. Esse é o contexto recomendado para mostrar os resultados. Por exemplo, se o comando da omnibox é navegar para um determinado URL, uma disposição de "newForegroundTab" significa que a navegação deve ocorrer em uma nova guia selecionada.

Tipo enumerado

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Um resultado sugerido.

Propriedades

  • conteúdo

    string

    O texto colocado na barra de URL e enviado para a extensão quando o usuário escolhe essa entrada.

  • excluir

    booleano opcional

    Chrome 63 ou mais recente

    Define se o resultado da sugestão pode ser excluído pelo usuário.

  • descrição

    string

    O texto que é exibido no menu suspenso de URL. Pode conter marcação no estilo XML para estilo. As tags aceitas são "url" (para um URL literal), "match" (para destacar texto que corresponde à consulta do usuário) e "dim" (para texto auxiliar esmaecido). Os estilos podem ser aninhados, por exemplo, correspondência esmaecida. É necessário fazer o escape das cinco entidades predefinidas para exibi-las como texto: stackoverflow.com/a/1091953/89484

Métodos

setDefaultSuggestion()

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

Define a descrição e o estilo da sugestão padrão. A sugestão padrão é o texto exibido na primeira linha de sugestão abaixo da barra de URL.

Parâmetros

  • Um objeto SuggestionResult parcial, sem o parâmetro "content".

  • callback

    função optional

    Chrome 100 ou mais recente

    O parâmetro callback tem esta aparência: 

    ()=>void

Retorna

  • Promise<void>

    Chrome 100 ou mais recente

    Promessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo que é passado para o callback.

Eventos

onDeleteSuggestion

Chrome 63 ou mais recente 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

O usuário excluiu um resultado sugerido.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (text: string)=>void

    • texto

      string

onInputCancelled

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

O usuário encerrou a sessão de entrada de palavra-chave sem aceitar a entrada.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    ()=>void

onInputChanged

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

O usuário alterou o que é digitado na omnibox.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

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

    • texto

      string

    • suggest

      função

      O parâmetro suggest tem esta aparência: 

      (suggestResults: SuggestResult[])=>void

onInputEntered

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

O usuário aceitou o que está digitado na omnibox.

Parâmetros

onInputStarted

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

O usuário iniciou uma sessão de entrada de palavra-chave digitando a palavra-chave da extensão. Ele será enviado exatamente uma vez por sessão de entrada e antes de qualquer evento onInputChanged.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    ()=>void