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 en Chromium"

Cuando el usuario ingresa la palabra clave de tu extensión, comienza a interactuar únicamente con tu . 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.

Manifiesto

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

"omnibox"

Debes incluir un campo "omnibox.keyword" en el manifiesto para usar la API del cuadro multifunción. Tú también debes especificar un ícono de 16 por 16 píxeles, que aparecerá en la barra de direcciones cuando se realicen sugerencias 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 del cuadro multifunción de chrome-extension-samples en un repositorio de confianza.

Tipos

DefaultSuggestResult

Un resultado sugerido.

Propiedades

  • descripción

    string

    El texto que se muestra en el menú desplegable de la URL. Puede contener lenguaje de marcado de estilo XML para darle estilo. Las etiquetas admitidas son "url" (para una URL literal), 'match' (para destacar el texto que coincidió con la consulta del usuario) y “dim” (para atenuar el texto auxiliar). Los estilos se pueden anidar, p. ej., fósforo atenuado.

DescriptionStyleType

Chrome 44 y versiones posteriores

Es el tipo de estilo.

Enum

"url"

"match"

“dim”

OnInputEnteredDisposition

Chrome 44 y versiones posteriores

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

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

Un resultado sugerido.

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.

  • borrable

    booleano opcional

    Chrome 63 y versiones posteriores

    Si el usuario puede borrar el resultado sugerido

  • descripción

    string

    El texto que se muestra en el menú desplegable de la URL. Puede contener lenguaje de marcado de estilo XML para darle estilo. Las etiquetas admitidas son "url" (para una URL literal), 'match' (para destacar el texto que coincidió con la consulta del usuario) y “dim” (para atenuar el texto auxiliar). Los estilos se pueden anidar, p. ej., fósforo atenuado. 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 SuggestedResult parcial, sin el "contenido" parámetro.

  • callback

    función opcional

    Chrome 100 y versiones posteriores

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

    () => void

Muestra

  • Promesa<void>

    Chrome 100 y versiones posteriores

    Las promesas son compatibles con Manifest V3 y versiones posteriores, pero se proporcionan devoluciones de llamada para retrocompatibilidad. No puedes usar ambos en la misma llamada a función. El 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 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 la palabra clave sin aceptarla.

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

        Rango de resultados de sugerencias

onInputEntered

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

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

Parámetros

onInputStarted

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