chrome.browserAction

refresh date: 2026-09-25 robots: noindex

Opis

Dostępność

Na ilustracji poniżej wielokolorowy kwadrat po prawej stronie paska adresu to ikona działania przeglądarki. Pod ikoną pojawi się wyskakujące okienko.

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

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 do użycia w Chrome, a Chrome wybierze najbliższy rozmiar i skaluje go do odpowiedniego rozmiaru, aby wypełnić przestrzeń 16 dip. Jeśli jednak dokładny rozmiar nie zostanie podany, skalowanie może spowodować utratę szczegółów lub rozmycie ikony.

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

Stara składnia 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łania przeglądarki w Chrome mają szerokość i wysokość 16 dips (pikseli niezależnych od urządzenia). Większe ikony są dopasowywane, ale aby uzyskać najlepsze wyniki, używaj kwadratowej ikony o rozmiarze 16 dipów.

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

Obrazy statyczne mogą być w dowolnym formacie obsługiwanym przez WebKit, w tym BMP, GIF, ICO, JPEG lub PNG. W przypadku rozszerzeń bez pakietu obrazy muszą być w formacie PNG.

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

Aby prawidłowo wyświetlać ikonę, gdy gęstość pikseli ekranu (stosunek size_in_pixel / size_in_dip) jest inna niż 1, ikonę można zdefiniować jako zestaw obrazów o różnych rozmiarach. Rzeczywisty obraz do wyświetlenia zostanie wybrany z zestawu tak, aby jak najlepiej pasował do rozmiaru piksela 16 dip. Zestaw ikon może zawierać specyfikacje ikon o dowolnym rozmiarze, a Chrome wybierze najbardziej odpowiednią.

Etykietka

Aby ustawić etykietkę, użyj pola default_title w sekcji browser_action w pliku manifestu lub wywołaj metodę browserAction.setTitle. W polu default_title możesz podać ciągi znaków w różnych językach. Więcej informacji znajdziesz w artykule o internacjonalizacji.

Plakietka

Działania przeglądarki mogą opcjonalnie wyświetlać plakietkę, czyli fragment tekstu nałożony na ikonę. Odznaki ułatwiają aktualizowanie działania przeglądarki, aby wyświetlać niewielką ilość informacji o stanie rozszerzenia.

Odznaka ma ograniczoną ilość miejsca, więc powinna zawierać maksymalnie 4 znaki.

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

Wyskakujące okienko

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

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 w sekcji browser_action w manifeście 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 parametru page actions.
• Używaj dużych, kolorowych ikon, które w pełni wykorzystują przestrzeń 16 x 16 dp. Ikony działania przeglądarki powinny być nieco większe i bardziej wyraziste niż ikony działania na stronie.
• Nie próbuj naśladować monochromatycznej ikony menu Google Chrome. Nie sprawdza się to w przypadku motywów, a poza tym rozszerzenia powinny się nieco wyróżniać.
• Używaj przezroczystości alfa, aby dodać do ikony miękkie krawędzie. Wiele osób używa motywów, więc 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. Więcej przykładów i pomoc w wyświetlaniu kodu źródłowego znajdziesz w sekcji Przykłady.

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

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

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

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

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

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

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

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

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

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

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

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