chrome.browserAction

refresh date: 2026-09-25 robots: noindex

Opis

Użyj działań przeglądarki, aby umieścić ikony na głównym pasku narzędzi Google Chrome, na prawo od paska adresu. Oprócz ikony działanie przeglądarki może mieć etykietkę, plakietkę i wyskakujące okienko.

Dostępność

≤ MV2

Na poniższym rysunku wielokolorowy kwadrat po prawej stronie paska adresu to ikona działania przeglądarki. Pod ikoną jest wyskakujące okienko.

Jeśli chcesz utworzyć ikonę, która nie zawsze jest aktywna, zamiast działania przeglądarki użyj działania strony.

Plik manifestu

Zarejestruj działanie przeglądarki w pliku manifestu rozszerzenia w ten sposób:

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

Możesz podać dowolny rozmiar ikony, która ma być używana w Chrome, a Chrome wybierze najbliższy i przeskaluje go do odpowiedniego rozmiaru, aby wypełnić przestrzeń 16 dip. Jeśli jednak nie podasz dokładnego rozmiaru, skalowanie może spowodować, że ikona straci szczegóły lub będzie wyglądać na rozmytą.

Urządzenia z mniej popularnymi współczynnikami skalowania, takimi jak 1,5x lub 1,2x, stają się coraz bardziej powszechne, dlatego zalecamy udostępnianie ikon w różnych rozmiarach. Dzięki temu, jeśli rozmiar wyświetlanej ikony ulegnie zmianie, nie musisz wykonywać żadnych dodatkowych czynności, aby udostępnić inne ikony.

Stara składnia do rejestrowania domyślnej ikony jest nadal obsługiwana:

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

Elementy interfejsu

Działanie przeglądarki może mieć ikonę, etykietkę, plakietkę i wyskakujące okienko.

Ikona

Ikony działań przeglądarki w Chrome mają szerokość i wysokość 16 dipów (pikseli niezależnych od urządzenia). Większe ikony są odpowiednio zmniejszane, ale najlepsze wyniki uzyskasz, używając kwadratowej ikony o rozmiarze 16 dip.

Ikonę możesz ustawić na 2 sposoby: za pomocą obrazu statycznego lub elementu canvas HTML5. Używanie obrazów statycznych jest łatwiejsze w przypadku prostych aplikacji, ale za pomocą elementu canvas można tworzyć bardziej dynamiczne interfejsy użytkownika, np. płynne animacje.

Obrazy statyczne mogą być w dowolnym formacie, który może wyświetlać WebKit, w tym BMP, GIF, ICO, JPEG lub PNG. W przypadku rozpakowanych rozszerzeń obrazy muszą być w formacie PNG.

Aby ustawić ikonę, użyj pola default_icon w browser_action w pliku manifestu lub wywołaj metodę browserAction.setIcon.

Aby ikona wyświetlała się prawidłowo, gdy gęstość pikseli ekranu (współczynnik size_in_pixel / size_in_dip) jest inna niż 1, można ją zdefiniować jako zestaw obrazów o różnych rozmiarach. Rzeczywisty obraz do wyświetlenia zostanie wybrany ze zbioru tak, aby najlepiej pasował do rozmiaru piksela wynoszącego 16 dip. Zestaw ikon może zawierać specyfikację ikony o dowolnym rozmiarze, a Chrome wybierze najbardziej odpowiednią.

Etykietka

Aby ustawić etykietkę, użyj pola default_title w browser_action w pliku manifestu lub wywołaj metodę browserAction.setTitle. W polu default_title możesz określić ciągi znaków dla konkretnych języków. Szczegółowe informacje znajdziesz w artykule o internacjonalizacji.

Plakietka

Działania w przeglądarce mogą opcjonalnie wyświetlać plakietkę – krótki tekst nałożony na ikonę. Plakietki ułatwiają aktualizowanie działania przeglądarki, aby wyświetlać niewielką ilość informacji o stanie rozszerzenia.

Ze względu na ograniczoną ilość miejsca plakietka powinna mieć maksymalnie 4 znaki.

Ustaw tekst i kolor plakietki, używając odpowiednio browserAction.setBadgeText i browserAction.setBadgeBackgroundColor.

Jeśli działanie przeglądarki ma wyskakujące okienko, pojawia się ono, gdy użytkownik kliknie ikonę rozszerzenia. Wyskakujące okienko może zawierać dowolną treść HTML i jest automatycznie dopasowywane do jej rozmiaru. Wyskakujące okienko nie może być mniejsze niż 25 x 25 i nie może być większe niż 800 x 600.

Aby dodać wyskakujące okienko do działania przeglądarki, utwórz plik HTML z zawartością wyskakującego okienka. Określ plik HTML w polu default_popup elementu browser_action w pliku manifestu lub wywołaj metodę browserAction.setPopup.

Wskazówki

Aby uzyskać najlepszy efekt wizualny, postępuj zgodnie z tymi wskazówkami:

  • Używaj działań przeglądarki w przypadku funkcji, które mają sens na większości stron.
  • Nie używaj działań przeglądarki w przypadku funkcji, które mają sens tylko na kilku stronach. Zamiast tego użyj działań na stronie.
  • Używaj dużych, kolorowych ikon, które maksymalnie wykorzystują przestrzeń 16 x 16 dip. Ikony działań w przeglądarce powinny wydawać się nieco większe i cięższe niż ikony działań na stronie.
  • Nie próbuj naśladować monochromatycznej ikony menu Google Chrome. Nie wygląda to dobrze z motywami, a poza tym rozszerzenia powinny się trochę wyróżniać.
  • Używaj przezroczystości alfa, aby dodać miękkie krawędzie do ikony. Wiele osób używa motywów, dlatego ikona powinna dobrze wyglądać na różnych kolorach tła.
  • Nie animuj ikony w sposób ciągły. To po prostu irytujące.

Przykłady

Proste przykłady użycia działań przeglądarki znajdziesz w katalogu examples/api/browserAction. Inne przykłady i pomoc w wyświetlaniu kodu źródłowego znajdziesz w sekcji Przykłady.

Typy

TabDetails

Chrome 88 lub nowsza wersja

Właściwości

  • tabId

    number optional

    Identyfikator karty, której stan chcesz sprawdzić. Jeśli nie określono karty, zwracany jest stan niezwiązany z kartą.

Metody

disable()

Obietnica 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

Wyłącza działanie przeglądarki na karcie.

Parametry

  • tabId

    number optional

    Identyfikator karty, dla której chcesz zmodyfikować działanie przeglądarki.

  • callback

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

enable()

Obietnica 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

Włącza działanie przeglądarki na karcie. Domyślnie jest włączona.

Parametry

  • tabId

    number optional

    Identyfikator karty, dla której chcesz zmodyfikować działanie przeglądarki.

  • callback

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getBadgeBackgroundColor()

Obietnica 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

Pobiera kolor tła działania przeglądarki.

Parametry

Zwroty

  • Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getBadgeText()

Obietnica 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

Pobiera tekst plakietki działania przeglądarki. Jeśli nie podano karty, zwracany jest tekst plakietki, który nie jest powiązany z kartą.

Parametry

  • szczegóły

    TabDetails

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (result: string) => void

    • wynik

      tekst

Zwroty

  • Promise<string>

    Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getPopup()

Obietnica 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

Pobiera dokument HTML ustawiony jako wyskakujące okienko dla tego działania przeglądarki.

Parametry

  • szczegóły

    TabDetails

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (result: string) => void

    • wynik

      tekst

Zwroty

  • Promise<string>

    Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

getTitle()

Obietnica 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

Pobiera tytuł działania w przeglądarce.

Parametry

  • szczegóły

    TabDetails

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (result: string) => void

    • wynik

      tekst

Zwroty

  • Promise<string>

    Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

setBadgeBackgroundColor()

Obietnica 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

Ustawia kolor tła plakietki.

Parametry

  • szczegóły

    obiekt

    • kolor

      string | ColorArray

      Tablica 4 liczb całkowitych z zakresu 0–255, które tworzą kolor RGBA plakietki. Może to być też ciąg znaków z szesnastkowym kodem koloru CSS, np. #FF0000 lub #F00 (czerwony). Renderuje kolory z pełnym kryciem.

    • tabId

      number optional

      Zmiana jest ograniczona do momentu wybrania określonej karty. Automatycznie resetuje się po zamknięciu karty.

  • callback

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

setBadgeText()

Obietnica 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

Ustawia tekst plakietki dla działania przeglądarki. Plakietka jest wyświetlana nad ikoną.

Parametry

  • szczegóły

    obiekt

    • tabId

      number optional

      Zmiana jest ograniczona do momentu wybrania określonej karty. Automatycznie resetuje się po zamknięciu karty.

    • tekst

      ciąg znaków opcjonalny

      Można przekazać dowolną liczbę znaków, ale w miejscu na nie zmieszczą się tylko około 4 znaki. Jeśli przekazany zostanie pusty ciąg znaków (''), tekst plakietki zostanie wyczyszczony. Jeśli określono parametr tabId, a parametr text ma wartość null, tekst na określonej karcie zostanie wyczyszczony i domyślnie zostanie użyty tekst globalnej plakietki.

  • callback

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

setIcon()

Obietnica 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

Ustawia ikonę działania przeglądarki. Ikonę można określić jako ścieżkę do pliku graficznego, dane pikseli z elementu canvas lub słownik jednego z tych elementów. Należy określić właściwość path lub imageData.

Parametry

  • szczegóły

    obiekt

    • imageData

      ImageData | obiekt opcjonalny

      Obiekt ImageData lub słownik {size -> ImageData} reprezentujący ikonę do ustawienia. Jeśli ikona jest określona jako słownik, używany obraz jest wybierany w zależności od gęstości pikseli ekranu. Jeśli liczba pikseli obrazu, które mieszczą się w jednej jednostce przestrzeni ekranu, wynosi scale, wybierany jest obraz o rozmiarze scale * n, gdzie n to rozmiar ikony w interfejsie. Musisz określić co najmniej 1 obraz. Pamiętaj, że „details.imageData = foo” jest równoważne „details.imageData = {'16': foo}”

    • ścieżka

      string | object opcjonalny

      Względna ścieżka obrazu lub słownik {rozmiar -> względna ścieżka obrazu} wskazujący ikonę, która ma zostać ustawiona. Jeśli ikona jest określona jako słownik, używany obraz jest wybierany w zależności od gęstości pikseli ekranu. Jeśli liczba pikseli obrazu, które mieszczą się w jednej jednostce przestrzeni ekranu, wynosi scale, wybierany jest obraz o rozmiarze scale * n, gdzie n to rozmiar ikony w interfejsie. Musisz określić co najmniej 1 obraz. Pamiętaj, że „details.path = foo” jest odpowiednikiem „details.path = {'16': foo}”.

    • tabId

      number optional

      Zmiana jest ograniczona do momentu wybrania określonej karty. Automatycznie resetuje się po zamknięciu karty.

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 116 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

setPopup()

Obietnica 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

Ustawia dokument HTML, który ma zostać otwarty jako wyskakujące okienko, gdy użytkownik kliknie ikonę działania przeglądarki.

Parametry

  • szczegóły

    obiekt

    • wyskakujące okienko

      tekst

      Ścieżka względna do pliku HTML, który ma się wyświetlać w wyskakującym okienku. Jeśli zasada jest ustawiona na pusty ciąg znaków (''), wyskakujące okienko nie jest wyświetlane.

    • tabId

      number optional

      Zmiana jest ograniczona do momentu wybrania określonej karty. Automatycznie resetuje się po zamknięciu karty.

  • callback

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

setTitle()

Obietnica 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

Ustawia tytuł działania przeglądarki. Ten tytuł pojawia się w etykietce.

Parametry

  • szczegóły

    obiekt

    • tabId

      number optional

      Zmiana jest ograniczona do momentu wybrania określonej karty. Automatycznie resetuje się po zamknięciu karty.

    • tytuł

      tekst

      Ciąg znaków, który powinien wyświetlać się po najechaniu kursorem na działanie dotyczące przeglądarki.

  • callback

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 88 lub nowsza wersja

    Obiekty Promise są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych. Na innych platformach należy używać wywołań zwrotnych.

Wydarzenia

onClicked

chrome.browserAction.onClicked.addListener(
  callback: function,
)

Uruchamiane po kliknięciu ikony działania przeglądarki. Nie uruchamia się, jeśli działanie przeglądarki ma wyskakujące okienko.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (tab: tabs.Tab) => void