browser.omnibox

Descrição

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

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

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

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

Manifesto

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

"omnibox"

É preciso incluir um campo "omnibox.keyword" no manifesto para usar a API Omnibox. Você também precisa especificar um ícone de 16 por 16 pixels, que vai aparecer 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 do repositório chrome-extension-samples.

Tipos

DefaultSuggestResult

Um resultado de sugestão.

Propriedades

  • descrição

    string

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

DescriptionStyleType

Chrome 44+ browser.* desde o Chrome 148

O tipo de estilo.

Enumeração

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44+ browser.* desde o Chrome 148

A disposição da janela para a consulta da omnibox. Esse é o contexto recomendado para exibir resultados. Por exemplo, se o comando da omnibox for 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 de sugestão.

Propriedades

  • conteúdo

    string

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

  • excluível

    booleano opcional

    Chrome 63+ browser.* desde o Chrome 148

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

  • descrição

    string

    O texto que aparece no menu suspenso do URL. Pode conter marcação no estilo XML para estilização. As tags aceitas são "url" (para um URL literal), "match" (para destacar o texto que corresponde à consulta do usuário) e "dim" (para texto de ajuda esmaecido). Os estilos podem ser aninhados, por exemplo, correspondência esmaecida. É preciso usar caracteres de escape nas cinco entidades predefinidas para que elas sejam mostradas como texto: stackoverflow.com/a/1091953/89484

Métodos

setDefaultSuggestion()

browser.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
): Promise<void>

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

Retorna

  • Promessa<void>

    Chrome 100+ browser.* desde o Chrome 148

Eventos

onDeleteSuggestion

Chrome 63+ browser.* desde o Chrome 148 
browser.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

O usuário excluiu um resultado sugerido.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    (text: string) => void

    • texto

      string

onInputCancelled

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

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

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

    () => void

onInputChanged

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

O usuário mudou o que foi digitado na omnibox.

Parâmetros

  • callback

    função

    O parâmetro callback é semelhante a: 

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

    • texto

      string

    • suggest

      função

      O parâmetro suggest é semelhante a: 

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

        Matriz de resultados de sugestão

onInputEntered

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

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

Parâmetros

onInputStarted

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

O usuário iniciou uma sessão de entrada de palavra-chave digitando a palavra-chave da extensão. É garantido que 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 é semelhante a: 

    () => void