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ść
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
.
Wyskakujące okienko
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
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()
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 wersjeParametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
enable()
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 wersjeParametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
Pobiera kolor tła działania przeglądarki.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result: ColorArray) => void
-
wynik
-
Zwroty
-
Promise<ColorArray>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getBadgeText()
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
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result: string) => void
-
wynik
string,
-
Zwroty
-
Obietnica<string>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
Pobiera dokument HTML ustawiony jako wyskakujące okienko dla tego działania przeglądarki.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result: string) => void
-
wynik
string,
-
Zwroty
-
Obietnica<string>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
Pobiera nazwę działania przeglądarki.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(result: string) => void
-
wynik
string,
-
Zwroty
-
Obietnica<string>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
setBadgeBackgroundColor()
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 wersjeParametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
setBadgeText()
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ślonotabId
, atext
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 wersjeParametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
setIcon()
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 | obiekt opcjonalny
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 rozmiarzescale
* 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 rozmiarzescale
* 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
Zwroty
-
Promise<void>
Chrome 116 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
setPopup()
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 wersjeParametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 88 i nowsze wersjeObietnice są obsługiwane tylko w przypadku platformy Manifest V3 i nowszych platform. Inne platformy muszą używać wywołań zwrotnych.
setTitle()
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 wersjeParametr
callback
wygląda tak:() => void
Zwroty
-
Promise<void>
Chrome 88 i nowsze wersjeObietnice 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.