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

É necessário incluir um campo omnibox keyword no manifesto para usar a API da omnibox. Você também deve especificar um ícone de 16 x 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

    As promessas só têm suporte no Manifesto V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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