chrome.omnibox

refresh date: 2026-09-25 robots: noindex

Opis

Interfejs API omniboksu umożliwia zarejestrowanie słowa kluczowego na pasku adresu Google Chrome, który jest też nazywany omniboksem.

Zrzut ekranu przedstawiający sugestie związane ze słowem kluczowym „Wyszukiwanie w Chromium”.

Gdy użytkownik wpisze słowo kluczowe rozszerzenia, zacznie wchodzić w interakcję wyłącznie z Twoim rozszerzeniem. Każde naciśnięcie klawisza jest wysyłane do rozszerzenia, a Ty możesz w odpowiedzi podać sugestie.

Sugestie mogą być bogato sformatowane na różne sposoby. Gdy użytkownik zaakceptuje sugestię, rozszerzenie otrzyma powiadomienie i może podjąć odpowiednie działanie.

Plik manifestu

Aby korzystać z interfejsu API omniboksu, musisz umieścić w pliku manifestu pole omnibox keyword. Należy też podać ikonę o rozmiarze 16 x 16 pikseli, która będzie wyświetlana na pasku adresu podczas sugerowania użytkownikom przejścia do trybu słów kluczowych.

Na przykład:

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

Przykłady

Aby wypróbować ten interfejs API, zainstaluj przykład interfejsu API paska adresu z repozytorium chrome-extension-samples.

Typy

DefaultSuggestResult

Sugerowany wynik.

Właściwości

  • opis

    tekst

    Tekst wyświetlany w menu URL. Może zawierać znaczniki w stylu XML do formatowania. Obsługiwane tagi to „url” (dla dosłownego adresu URL), „match” (do wyróżniania tekstu, który pasuje do zapytania użytkownika) i „dim” (do przyciemniania tekstu pomocniczego). Style można zagnieżdżać, np. przyciemnione dopasowanie.

DescriptionStyleType

Chrome 44 lub nowsza

Typ stylu.

Typ wyliczeniowy

"url"

„match”

„dim”

OnInputEnteredDisposition

Chrome 44 lub nowsza

Sposób wyświetlania okna zapytania w omniboksie. Jest to zalecany kontekst wyświetlania wyników. Jeśli np. polecenie w omniboksie ma spowodować przejście do określonego adresu URL, wartość „newForegroundTab” oznacza, że nawigacja powinna odbyć się w nowej, wybranej karcie.

Typ wyliczeniowy

„currentTab”

"newForegroundTab"

„newBackgroundTab”

SuggestResult

Sugerowany wynik.

Właściwości

  • treść

    tekst

    Tekst, który jest wpisywany na pasku adresu URL i wysyłany do rozszerzenia, gdy użytkownik wybierze ten wpis.

  • można usunąć,

    wartość logiczna opcjonalna

    Chrome 63 lub nowsza

    Czy użytkownik może usunąć wynik sugestii.

  • opis

    tekst

    Tekst wyświetlany w menu URL. Może zawierać znaczniki w stylu XML do formatowania. Obsługiwane tagi to „url” (dla dosłownego adresu URL), „match” (do wyróżniania tekstu, który pasuje do zapytania użytkownika) i „dim” (do przyciemniania tekstu pomocniczego). Style można zagnieżdżać, np. przyciemnione dopasowanie. Aby wyświetlić 5 wstępnie zdefiniowanych encji jako tekst, musisz poprzedzić je znakiem zmiany znaczenia: stackoverflow.com/a/1091953/89484

Metody

setDefaultSuggestion()

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

Ustawia opis i styl domyślnej sugestii. Domyślna sugestia to tekst wyświetlany w pierwszym wierszu sugestii pod paskiem adresu URL.

Parametry

  • Częściowy obiekt SuggestResult bez parametru „content”.

  • callback

    funkcja opcjonalna

    Chrome 100 lub nowsza

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 100 lub nowsza

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Inne platformy muszą używać wywołań zwrotnych.

Wydarzenia

onDeleteSuggestion

Chrome 63 lub nowsza 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

Użytkownik usunął sugerowany wynik.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (text: string) => void

    • tekst

      tekst

onInputCancelled

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

Użytkownik zakończył sesję wpisywania słów kluczowych bez zaakceptowania wprowadzonych danych.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void

onInputChanged

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

Użytkownik zmienił tekst wpisany w omniboksie.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

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

    • tekst

      tekst

    • sugerować,

      funkcja

      Parametr suggest wygląda tak:

      (suggestResults: SuggestResult[]) => void

onInputEntered

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

Użytkownik zaakceptował tekst wpisany w omniboksie.

Parametry

onInputStarted

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

Użytkownik rozpoczął sesję wpisywania słowa kluczowego, wpisując słowo kluczowe rozszerzenia. Jest on wysyłany dokładnie raz na sesję wprowadzania danych i przed wszystkimi zdarzeniami onInputChanged.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    () => void