chrome.omnibox

Descripción

La API de Omnibox te permite registrar una palabra clave en la barra de direcciones de Google Chrome, también conocida como Omnibox.

Captura de pantalla que muestra sugerencias relacionadas con la palabra clave "Chromium Search"

Cuando el usuario ingresa la palabra clave de tu extensión, comienza a interactuar solo con ella. Cada pulsación de tecla se envía a tu extensión, y puedes proporcionar sugerencias en respuesta.

Las sugerencias pueden tener un formato enriquecido de varias maneras. Cuando el usuario acepta una sugerencia, se notifica a tu extensión, que puede tomar medidas.

Manifiesto

Debes incluir un campo omnibox keyword en el manifiesto para usar la API de Omnibox. También debes especificar un ícono de 16 x 16 píxeles, que se mostrará en la barra de direcciones cuando se sugiera que los usuarios ingresen al modo de palabras clave.

Por ejemplo:

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

Ejemplos

Para probar esta API, instala el ejemplo de la API de la barra de direcciones del repositorio chrome-extension-samples.

Tipos

DefaultSuggestResult

Es un resultado de sugerencia.

Propiedades

  • descripción

    string

    Es el texto que se muestra en el menú desplegable de URL. Puede contener lenguaje de marcado de estilo XML. Las etiquetas admitidas son "url" (para una URL literal), "match" (para destacar el texto que coincidió con la búsqueda del usuario) y "dim" (para texto de ayuda atenuado). Los estilos se pueden anidar, p. ej., coincidencias atenuadas.

DescriptionStyleType

Chrome 44 y versiones posteriores

Es el tipo de diseño.

Enum

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 y versiones posteriores

Es la disposición de la ventana para la búsqueda en el cuadro multifunción. Este es el contexto recomendado para mostrar los resultados. Por ejemplo, si el comando de la barra de direcciones es para navegar a una URL determinada, una disposición de "newForegroundTab" significa que la navegación debe realizarse en una pestaña nueva seleccionada.

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Es un resultado de sugerencia.

Propiedades

  • contenido

    string

    Es el texto que se ingresa en la barra de URL y que se envía a la extensión cuando el usuario elige esta entrada.

  • Se puede borrar

    booleano opcional

    Chrome 63 y versiones posteriores

    Indica si el usuario puede borrar el resultado de la sugerencia.

  • descripción

    string

    Es el texto que se muestra en el menú desplegable de URL. Puede contener lenguaje de marcado de estilo XML. Las etiquetas admitidas son "url" (para una URL literal), "match" (para destacar el texto que coincidió con la búsqueda del usuario) y "dim" (para texto de ayuda atenuado). Los estilos se pueden anidar, p. ej., coincidencias atenuadas. Debes escapar las cinco entidades predefinidas para mostrarlas como texto: stackoverflow.com/a/1091953/89484

Métodos

setDefaultSuggestion()

Promesa 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
): Promise<void>

Establece la descripción y el diseño de la sugerencia predeterminada. La sugerencia predeterminada es el texto que se muestra en la primera fila de sugerencias debajo de la barra de URL.

Parámetros

  • Es un objeto SuggestResult parcial, sin el parámetro "content".

  • callback

    función opcional

    Chrome 100 y versiones posteriores

    El parámetro callback se ve de la siguiente manera: 

    () => void

Muestra

  • Promise<void>

    Chrome 100 y versiones posteriores

    Las promesas solo se admiten en Manifest V3 y versiones posteriores. Otras plataformas deben usar devoluciones de llamada.

Eventos

onDeleteSuggestion

Chrome 63 y versiones posteriores 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

El usuario borró un resultado sugerido.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    (text: string) => void

    • texto

      string

onInputCancelled

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

El usuario finalizó la sesión de entrada de palabras clave sin aceptar la entrada.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    () => void

onInputChanged

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

El usuario cambió lo que escribió en la barra de direcciones.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

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

    • texto

      string

    • suggest

      función

      El parámetro suggest se ve de la siguiente manera: 

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

        Es un array de resultados de sugerencias.

onInputEntered

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

El usuario aceptó lo que escribió en la barra de direcciones.

Parámetros

onInputStarted

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

El usuario comenzó una sesión de entrada de palabras clave escribiendo la palabra clave de la extensión. Se garantiza que se enviará exactamente una vez por sesión de entrada y antes de cualquier evento onInputChanged.

Parámetros

  • callback

    función

    El parámetro callback se ve de la siguiente manera: 

    () => void