chrome.pageAction

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu chrome.pageAction API, aby umieścić ikony na głównym pasku narzędzi Google Chrome po prawej stronie paska adresu. Działania na stronie to działania, które można wykonać na bieżącej stronie, ale nie mają zastosowania do wszystkich stron. Działania na stronie są wyszarzone, gdy są nieaktywne.

Dostępność

≤ MV2

Oto kilka przykładów:

  • Subskrybuj kanał RSS tej strony
  • Utwórz pokaz slajdów ze zdjęć na tej stronie

Ikona RSS na zrzucie ekranu poniżej przedstawia działanie na stronie, które umożliwia subskrybowanie kanału RSS bieżącej strony.

Ukryte działania na stronie są wyszarzone. Na przykład kanał RSS poniżej jest wyszarzony, ponieważ nie możesz zasubskrybować kanału dla bieżącej strony:

Zamiast tego użyj działania przeglądarki, aby użytkownicy mogli zawsze korzystać z rozszerzenia.

Plik manifestu

Zarejestruj działanie strony w pliku manifestu rozszerzenia w ten sposób:

{
  "name": "My extension",
  ...
  "page_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
  },
  ...
}

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. Chrome wybierze najbliższą i skaluje ją, aby wypełnić przestrzeń o wielkości 16 dipów. Dzięki temu, jeśli rozmiar wyświetlania ikony kiedykolwiek się zmieni, nie musisz wykonywać żadnych dodatkowych czynności, aby udostępnić inne ikony. Jeśli jednak różnica rozmiarów jest zbyt duża, skalowanie może spowodować utratę szczegółów lub rozmycie ikony.

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

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

Elementy interfejsu

Podobnie jak działania przeglądarki, działania na stronie mogą mieć ikonę, etykietkę i wyskakujące okienko, ale nie mogą mieć plakietek. Działania na stronie mogą być też wyszarzone. Informacje o ikonach, etykietkach i wyskakujących okienkach znajdziesz w sekcji dotyczącej interfejsu działania przeglądarki.

Działanie na stronie możesz wyświetlić i wyszarzyć za pomocą metod pageAction.show i pageAction.hide. Domyślnie działanie na stronie jest wyszarzone. Gdy wyświetlasz ikonę, musisz określić kartę, na której ma się ona pojawić. Ikona pozostaje widoczna, dopóki karta nie zostanie zamknięta lub nie zacznie wyświetlać innego adresu URL (np. gdy użytkownik kliknie link).

Wskazówki

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

  • Używaj działań na stronie w przypadku funkcji, które mają sens tylko na kilku stronach.
  • Nie używaj działań na stronie w przypadku funkcji, które mają sens w większości stron. Zamiast tego użyj działań przeglądarki.
  • Nie animuj ikony w sposób ciągły. To po prostu irytujące.

Typy

ImageDataType

Dane pikseli obrazu. Musi to być obiekt ImageData (np. z elementu canvas).

Typ

ImageData

TabDetails

Chrome 88 lub nowsza

Właściwości

  • tabId

    number opcjonalny

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

Metody

getPopup()

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

Pobiera dokument HTML ustawiony jako wyskakujące okienko dla tego działania na stronie.

Parametry

  • szczegóły

    TabDetails

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (result: string) => void

    • wynik

      tekst

Zwroty

  • Promise<string>

    Chrome 101 lub nowsza

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

getTitle()

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

Pobiera tytuł działania na stronie.

Parametry

  • szczegóły

    TabDetails

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    (result: string) => void

    • wynik

      tekst

Zwroty

  • Promise<string>

    Chrome 101 lub nowsza

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

hide()

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

Ukrywa działanie na stronie. Ukryte działania na stronie nadal pojawiają się na pasku narzędzi Chrome, ale są wyszarzone.

Parametry

  • tabId

    liczba

    Identyfikator karty, dla której chcesz zmodyfikować działanie na stronie.

  • callback

    funkcja opcjonalna

    Chrome 67 lub nowsza

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 101 lub nowsza

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

setIcon()

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

Ustawia ikonę działania na stronie. Ikonę można określić jako ścieżkę do pliku obrazu, dane pikseli z elementu canvas lub słownik zawierający jedną z tych wartości. Należy określić właściwość path lub imageData.

Parametry

  • szczegóły

    obiekt

    • iconIndex

      number opcjonalny

      Wycofano. Ten argument jest ignorowany.

    • imageData

      ImageData | object opcjonalny

      Obiekt ImageData lub słownik {size -> ImageData} reprezentujący ikonę do ustawienia. Jeśli ikona jest określona jako słownik, rzeczywisty obraz do użycia jest wybierany w zależności od gęstości pikseli ekranu. Jeśli liczba pikseli obrazu mieszczących się w jednej jednostce przestrzeni ekranu wynosi scale, zostanie wybrany 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ównoznaczne z „details.imageData = {'16': foo}”.

    • ścieżka

      string | object opcjonalny

      Względna ścieżka do obrazu lub słownik {rozmiar –> względna ścieżka do obrazu} wskazujący ikonę do ustawienia. Jeśli ikona jest określona jako słownik, rzeczywisty obraz do użycia jest wybierany w zależności od gęstości pikseli ekranu. Jeśli liczba pikseli obrazu mieszczących się w jednej jednostce przestrzeni ekranu wynosi scale, zostanie wybrany 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 równoważne „details.path = {'16': foo}”.

    • tabId

      liczba

      Identyfikator karty, dla której chcesz zmodyfikować działanie na stronie.

  • callback

    funkcja opcjonalna

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 101 lub nowsza

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

setPopup()

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

Ustawia dokument HTML, który ma być otwierany jako wyskakujące okienko, gdy użytkownik kliknie ikonę działania na stronie.

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 ma wartość pustego ciągu znaków (''), nie będzie się wyświetlać żadne wyskakujące okienko.

    • tabId

      liczba

      Identyfikator karty, dla której chcesz zmodyfikować działanie na stronie.

  • callback

    funkcja opcjonalna

    Chrome 67 lub nowsza

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 101 lub nowsza

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

setTitle()

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

Ustawia tytuł działania na stronie. Wyświetla się w etykietce nad działaniem na stronie.

Parametry

  • szczegóły

    obiekt

    • tabId

      liczba

      Identyfikator karty, dla której chcesz zmodyfikować działanie na stronie.

    • tytuł

      tekst

      Ciąg tekstowy etykietki.

  • callback

    funkcja opcjonalna

    Chrome 67 lub nowsza

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 101 lub nowsza

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

show()

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

Wyświetla działanie na stronie. Działanie na stronie jest widoczne, gdy karta jest wybrana.

Parametry

  • tabId

    liczba

    Identyfikator karty, dla której chcesz zmodyfikować działanie na stronie.

  • callback

    funkcja opcjonalna

    Chrome 67 lub nowsza

    Parametr callback wygląda tak:

    () => void

Zwroty

  • Promise<void>

    Chrome 101 lub nowsza

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

Wydarzenia

onClicked

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

Wywoływane po kliknięciu ikony działania na stronie. To zdarzenie nie zostanie wywołane, jeśli działanie na stronie ma wyskakujące okienko.

Parametry

  • callback

    funkcja

    Parametr callback wygląda tak:

    (tab: tabs.Tab) => void