chrome.browserAction

Opis

Za pomocą działań przeglądarki możesz umieścić ikony na głównym pasku narzędzi przeglądarki Google Chrome, po prawej stronie paska adresu. Oprócz ikony działanie w przeglądarce może mieć etykietkę, plakietkę i wyskakujące okienko.

Dostępność

≤ MV2

Na ilustracji wielokolorowy kwadrat na prawo od paska adresu jest ikoną działania przeglądarki. Pod ikoną pojawi się wyskakujące okienko.

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

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 udostępnić ikonę w dowolnym rozmiarze, która będzie używana w Chrome. Chrome wybierze najbliższą z nich i przeskaluje ją do odpowiedniego rozmiaru, wypełniając obszar o szerokości 16 dip. Jeśli jednak nie podasz dokładnego rozmiaru, takie skalowanie może spowodować utratę szczegółów lub niewyraźny wygląd ikony.

Coraz częściej używane są urządzenia o rzadszych współczynnikach skali, takich jak 1,5x czy 1,2x, dlatego zalecamy podawanie ikon w wielu rozmiarach. Dzięki temu nawet jeśli zmieni się rozmiar wyświetlanej ikony, nie trzeba będzie więcej wprowadzać zmian.

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

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

Części interfejsu użytkownika

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

Ikona

Ikony czynności w przeglądarce Chrome mają szerokość i wysokość 16 pikseli niezależnych od urządzenia. Większe ikony są dopasowywane, ale najlepiej jest użyć kwadratowej ikony o 16 dipach.

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

Obrazy statyczne mogą mieć dowolny format możliwy do wyświetlenia 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 parametru default_icon w pliku manifestu lub wywołaj metodę browserAction.setIcon.

Aby ikona była prawidłowo wyświetlana, gdy gęstość pikseli ekranu (współczynnik size_in_pixel / size_in_dip) jest inna niż 1, można ją zdefiniować jako zbiór obrazów o różnych rozmiarach. Obraz do wyświetlenia zostanie wybrany z zestawu, aby jak najlepiej dopasować go do rozmiaru 16 pikseli. Zestaw ikon może zawierać ikony o dowolnym rozmiarze, a Chrome wybierze najodpowiedniejszą.

Etykietka

Aby ustawić etykietkę, użyj pola default_title parametru default_title w pliku manifestu lub wywołaj metodę browserAction.setTitle. W polu default_title możesz podać ciągi znaków zależne od regionu. Szczegółowe informacje znajdziesz w sekcji Internacjonalizacja.

Plakietka

Czynności wykonywane przez przeglądarkę mogą opcjonalnie powodować wyświetlanie plakietki – fragmentu tekstu nałożonego na ikonę. Plakietki ułatwiają aktualizowanie działania przeglądarki, aby wyświetlać niewielką ilość informacji o stanie rozszerzenia.

Liczba znaków na plakietce jest ograniczona, dlatego nie powinna przekraczać 4 znaków.

Ustaw tekst i kolor plakietki odpowiednio za pomocą browserAction.setBadgeText i browserAction.setBadgeBackgroundColor.

Jeśli działanie w przeglądarce zawiera wyskakujące okienko, pojawia się ono, gdy użytkownik kliknie ikonę rozszerzenia. Wyskakujące okienko może zawierać dowolną treść HTML i automatycznie dopasowuje się do jego zawartości. Wyskakujące okienko nie może być mniejsze niż 25 x 25 ani większe niż 800 x 600.

Aby dodać wyskakujące okienko do działania przeglądarki, utwórz plik HTML z jego zawartością. Wskaż plik HTML w polu default_popup parametru default_popup w pliku manifestu lub wywołaj metodę browserAction.setPopup.

Wskazówki

Aby uzyskać najlepszy efekt wizualny, przestrzegaj tych wytycznych:

  • Używaj działań przeglądarki w przypadku funkcji, które sprawdzają się na większości stron.
  • Nie używaj działań przeglądarki w przypadku funkcji, które mają zastosowanie tylko na kilku stronach. Zamiast tego używaj działań na stronie.
  • Używaj dużych, kolorowych ikon, które w pełni wykorzystują przestrzeń 16 x 16 dip. Ikony działań przeglądarki powinny być większe i cięższe od ikon działań na stronie.
  • Nie naśladuj monochromatycznej ikony menu Google Chrome. Nie pasuje to do motywów, a w każdym przypadku rozszerzenia powinny się trochę wyróżnić.
  • Używaj przezroczystości alfa, aby dodać miękkie krawędzie do ikony. Wiele osób używa motywów, dlatego Twoja ikona powinna wyglądać ładnie na różnych kolorach tła.
  • Nie animuj ikony stale. 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 oraz pomoc dotyczącą wyświetlania kodu źródłowego znajdziesz w artykule Przykłady.

Typy

ColorArray

Typ

[liczba,liczba,liczba,liczba]

ImageDataType

Dane obrazu na Pixelu. Musi to być obiekt ImageData, np. z elementu canvas.

Typ

ImageData

TabDetails

Chrome 88 i nowsze wersje

Właściwości

  • tabId

    Liczba opcjonalnie

    Identyfikator karty, której stan ma zostać objęty zapytaniem. Jeśli nie określisz żadnej karty, zwracany jest stan niezwiązany z daną kartą.

Metody

disable()

Obietnica 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

Wyłącza działanie przeglądarki w przypadku danej karty.

Parametry

  • tabId

    Liczba opcjonalnie

    Identyfikator karty, której działanie w przeglądarce chcesz zmienić.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 88 i nowsze wersje

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

enable()

Obietnica 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

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

Parametry

  • tabId

    Liczba opcjonalnie

    Identyfikator karty, której działanie w przeglądarce chcesz zmienić.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 88 i nowsze wersje

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

getBadgeBackgroundColor()

Obietnica 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

Parametry

Akcje powrotne

  • Promise<ColorArray>

    Chrome 88 i nowsze wersje

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

getBadgeText()

Obietnica 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

Pobiera tekst plakietki działania przeglądarki. Jeśli nie określisz tabulacji, zwracany jest tekst plakietki, który nie jest związany z konkretną kartą.

Parametry

  • szczegóły

    TabDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (result: string)=>void

    • wynik

      string,

Akcje powrotne

  • Obietnica<string>

    Chrome 88 i nowsze wersje

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

getPopup()

Obietnica 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

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

Parametry

  • szczegóły

    TabDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (result: string)=>void

    • wynik

      string,

Akcje powrotne

  • Obietnica<string>

    Chrome 88 i nowsze wersje

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

getTitle()

Obietnica 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

Pobiera nazwę działania przeglądarki.

Parametry

  • szczegóły

    TabDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (result: string)=>void

    • wynik

      string,

Akcje powrotne

  • Obietnica<string>

    Chrome 88 i nowsze wersje

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

setBadgeBackgroundColor()

Obietnica 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

Ustawia kolor tła plakietki.

Parametry

  • szczegóły

    obiekt

    • kolor

      string|ColorArray

      Tablica 4 liczb całkowitych z zakresu 0–255, które składają się na kolor RGBA plakietki. Może to być też ciąg znaków z szesnastkową wartością koloru CSS, np. #FF0000 lub #F00 (czerwony). Renderuje kolory przy pełnej nieprzezroczystości.

    • tabId

      Liczba opcjonalnie

      Ogranicza zmianę do momentu wyboru określonej karty. Karta jest automatycznie resetowana po zamknięciu karty.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 88 i nowsze wersje

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

setBadgeText()

Obietnica 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

Ustawia tekst plakietki dla czynności w przeglądarce. Plakietka wyświetla się nad ikoną.

Parametry

  • szczegóły

    obiekt

    • tabId

      Liczba opcjonalnie

      Ogranicza zmianę do momentu wyboru określonej karty. Karta jest automatycznie resetowana po zamknięciu karty.

    • plik tekstowy,

      ciąg znaków opcjonalny

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 88 i nowsze wersje

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

setIcon()

Obietnica 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

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

Parametry

  • szczegóły

    obiekt

    • imageData

      ImageData|object opcjonalnie

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

    • ścieżka

      ciąg|obiekt opcjonalny

      Albo względna ścieżka obrazu, albo słownik {size ->appropriate image path} wskazujące ikonę do ustawienia. Jeśli ikona jest określona jako słownik, wybrany obraz jest wybierany na podstawie gęstości pikseli ekranu. Jeśli liczba pikseli obrazu, które mieszczą się w jednej jednostce obszaru na ekranie, równa się scale, wybrany jest obraz o rozmiarze scale * n, gdzie n to rozmiar ikony w interfejsie. Musisz określić co najmniej jeden obraz. Pamiętaj, że adres „details.path = foo” jest odpowiednikiem „details.path = {'16': foo}”.

    • tabId

      Liczba opcjonalnie

      Ogranicza zmianę do momentu wyboru określonej karty. Karta jest automatycznie resetowana po zamknięciu karty.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 116 i nowsze wersje

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

setPopup()

Obietnica 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

Ustawia dokument HTML jako wyskakujące okienko, gdy użytkownik kliknie ikonę działania przeglądarki.

Parametry

  • szczegóły

    obiekt

    • wyskakujące okienko

      string,

      Ścieżka względna do pliku HTML wyświetlana w wyskakującym okienku. Jeśli zasada jest ustawiona na pusty ciąg (''), wyskakujące okienko nie jest wyświetlane.

    • tabId

      Liczba opcjonalnie

      Ogranicza zmianę do momentu wyboru określonej karty. Karta jest automatycznie resetowana po zamknięciu karty.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 88 i nowsze wersje

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

setTitle()

Obietnica 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

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

Parametry

  • szczegóły

    obiekt

    • tabId

      Liczba opcjonalnie

      Ogranicza zmianę do momentu wyboru określonej karty. Karta jest automatycznie resetowana po zamknięciu karty.

    • title

      string,

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 88 i nowsze wersje

    Obietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą 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 zawiera wyskakujące okienko.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (tab: tabs.Tab)=>void