browser.omnibox

Descripción

La API de omnibox te permite registrar una palabra clave en la barra de direcciones de Google Chrome, que también se conoce como cuadro multifunción.

Una captura de pantalla que muestra sugerencias relacionadas con la palabra clave "Búsqueda de Chromium"

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 se pueden formatear de varias maneras. Cuando el usuario acepta una sugerencia, se notifica a tu extensión y esta puede tomar medidas.

Manifiesto

Las siguientes claves se deben declarar en el manifiesto para usar esta API.

"omnibox"

Debes incluir un campo "omnibox.keyword" en el manifiesto para usar la API de omnibox. También debes especificar un ícono de 16 por 16 píxeles, que se mostrará en la barra de direcciones cuando se sugiera que los usuarios ingresen al modo de palabra 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 omnibox 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 la URL. Puede contener lenguaje de marcado de estilo XML para aplicar diseño. 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 el texto de ayuda atenuado). Los estilos se pueden anidar, p. ej., coincidencia atenuada.

DescriptionStyleType

Chrome 44 y versiones posteriores browser.* desde Chrome 148

Es el tipo de estilo.

Enum

"url"

"match"

"dim"

OnInputEnteredDisposition

Chrome 44 y versiones posteriores browser.* desde Chrome 148

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

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Es un resultado de sugerencia.

Propiedades

  • contenido

    string

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

  • deletable

    booleano opcional

    Chrome 63 y versiones posteriores browser.* desde Chrome 148

    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 la URL. Puede contener lenguaje de marcado de estilo XML para aplicar diseño. 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 el texto de ayuda atenuado). Los estilos se pueden anidar, p. ej., coincidencia atenuada. Debes usar caracteres de escape para las cinco entidades predefinidas para mostrarlas como texto: stackoverflow.com/a/1091953/89484

Métodos

setDefaultSuggestion()

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

Establece la descripción y el estilo 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

Muestra

  • Promise<void>

    Chrome 100 y versiones posteriores del navegador* desde Chrome 148

Eventos

onDeleteSuggestion

Chrome 63 y versiones posteriores browser.* desde Chrome 148 
browser.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

browser.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

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

El usuario cambió lo que se escribe en el cuadro multifunción.

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[]

        Array de resultados de sugerencias

onInputEntered

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

El usuario aceptó lo que se escribió en el cuadro multifunción.

Parámetros

onInputStarted

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

El usuario inició 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