chrome.omnibox

Descrição

A API da omnibox permite registrar 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 inserir a palavra-chave da sua extensão, ele começará a interagir apenas com sua . Cada tecla pressionada é enviada para a 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, sua extensão será notificada e poderá realizar ações.

Manifesto

As chaves a seguir precisam ser declaradas no manifesto para usar essa API.

"omnibox"

É necessário incluir um campo "omnibox.keyword" no manifesto para usar a API da omnibox. Você também deve especificar um ícone de 16 por 16 pixels, que será exibido na barra de endereço ao sugerir para 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 da omnibox em chrome-extension-samples repositório de dados.

Tipos

DefaultSuggestResult

Um resultado sugerido.

Propriedades

  • descrição

    string

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

DescriptionStyleType

Chrome 44 ou superior

O tipo de estilo.

Enumeração

"url"

"match"

"diminuir"

OnInputEnteredDisposition

Chrome 44 ou superior

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

Enumeração

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Um resultado sugerido.

Propriedades

  • conteúdo

    string

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

  • excluível

    booleano opcional

    Chrome 63 ou superior

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

  • descrição

    string

    O texto exibido no menu suspenso de URL. Pode conter marcação de estilo XML. As tags aceitas são "url" (para um URL literal), "match" (para destacar o texto que corresponde à consulta do usuário) e "escurecer" (para escurecer o texto auxiliar). 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ões abaixo da barra de URL.

Parâmetros

  • Um objeto SuggestResult parcial, sem o "content" .

  • callback

    função opcional

    Chrome 100 ou mais recente

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 100 ou mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onDeleteSuggestion

Chrome 63 ou superior 
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 é 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