chrome.omnibox

Descripción

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

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 combinación de teclas se envía a tu extensión, y puedes proporcionar sugerencias como respuesta.

Las sugerencias pueden tener un formato enriquecido de diversas maneras. Cuando el usuario acepta una sugerencia, tu extensión recibe una notificación y puede tomar medidas.

Manifest

Para usar esta API, se deben declarar las siguientes claves en el manifiesto.

"omnibox"

Para usar la API del cuadro multifunción, debes incluir un campo "omnibox.keyword" en el manifiesto. 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 en el 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 del cuadro multifunción del repositorio chrome-extension-samples.

Tipos

DefaultSuggestResult

Un resultado sugerido.

Propiedades

  • descripción

    cadena

    El texto que se muestra en el menú desplegable de la URL. Puede incluir lenguaje de marcado de estilo XML para aplicar estilos. Las etiquetas admitidas son 'url' (para una URL literal), 'match' (para destacar texto que coincidió con la consulta del usuario) y 'dim' (para texto auxiliar atenuado). Los estilos pueden estar anidados, p. ej., mediante la coincidencia atenuada.

DescriptionStyleType

Chrome 44 y versiones posteriores

Es el tipo de estilo.

Enum

"url"

"match"

OnInputEnteredDisposition

Chrome 44 y versiones posteriores

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

Enum

"currentTab"

"newForegroundTab"

SuggestResult

Un resultado sugerido.

Propiedades

  • contenido

    cadena

    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.

  • eliminable

    booleano opcional

    Chrome 63 y versiones posteriores

    Indica si el usuario puede borrar el resultado sugerido.

  • descripción

    cadena

    El texto que se muestra en el menú desplegable de la URL. Puede incluir lenguaje de marcado de estilo XML para aplicar estilos. Las etiquetas admitidas son 'url' (para una URL literal), 'match' (para destacar texto que coincidió con la consulta del usuario) y 'dim' (para texto auxiliar atenuado). Los estilos pueden estar anidados, p. ej., mediante la coincidencia atenuada. 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,
)

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

  • 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

Devuelve

  • Promise<void>

    Chrome 100 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para brindar retrocompatibilidad. No puedes usar ambos en la misma llamada a función. La promesa se resuelve con el mismo tipo que se pasa a la devolución de llamada.

Eventos

onDeleteSuggestion

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

El usuario ha eliminado un resultado sugerido.

Parámetros

  • callback

    la función

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

    (text: string)=>void

    • text

      cadena

onInputCancelled

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

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

Parámetros

  • callback

    la 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 se escribió en el cuadro multifunción.

Parámetros

  • callback

    la función

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

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

    • text

      cadena

    • suggest

      la función

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

      (suggestResults: SuggestResult[])=>void

onInputEntered

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

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

Parámetros

onInputStarted

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

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

Parámetros

  • callback

    la función

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

    ()=>void