chrome.pageAction

refresh date: 2026-09-25 robots: noindex

Opis

Użyj interfejsu API chrome.pageAction, aby umieścić ikony na głównym pasku narzędzi Google Chrome, na prawo od 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 reprezentuje działanie na stronie, które umożliwia zasubskrybowanie kanału RSS dla 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 rozważ użycie działania przeglądarki, aby użytkownicy zawsze mogli korzystać z rozszerzenia.

Plik manifestu

Zarejestruj działanie na stronie 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 lub 1,2x, stają się coraz bardziej powszechne, dlatego zalecamy udostępnianie ikon w różnych rozmiarach. Chrome wybierze najbliższy rozmiar i przeskaluje go, aby wypełnić przestrzeń 16 dip. Dzięki temu, jeśli rozmiar wyświetlanej ikony ulegnie zmianie, 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ć, że ikona straci szczegóły lub będzie rozmyta.

Stara składnia do 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 strony mogą mieć ikonę, etykietkę i wyskakujące okienko, ale nie mogą mieć plakietek. Ponadto działania na stronie mogą być wyszarzone. Informacje o ikonach, etykietkach i wyskakujących okienkach znajdziesz w artykule o interfejsie działań przeglądarki.

Aby wyświetlić działanie na stronie i je wyszarzyć, użyj odpowiednio metod pageAction.show i pageAction.hide. Domyślnie działanie na stronie jest wyszarzone. Gdy ją wyświetlasz, określasz kartę, na której ma się pojawić. Ikona pozostaje widoczna, dopóki karta nie zostanie zamknięta lub nie zacznie wyświetlać innego adresu URL (np. po kliknięciu linku przez użytkownika).

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 na większości stron. Zamiast tego użyj działań w przeglądarce.
  • 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 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

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

    function opcjonalne

    Parametr callback wygląda tak:

    (result: string) => void

    • wynik

      tekst

Zwroty

  • Promise<string>

    Chrome 101 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.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

Pobiera tytuł działania na stronie.

Parametry

  • szczegóły

    TabDetails

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    (result: string) => void

    • wynik

      tekst

Zwroty

  • Promise<string>

    Chrome 101 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.

hide()

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

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

Parametry

  • tabId

    liczba

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

  • callback

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 101 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.pageAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

Ustawia ikonę działania na stronie. Ikonę można określić jako ścieżkę do pliku graficznego lub jako dane pikseli z elementu canvas albo jako słownik jednego z nich. Należy określić właściwość path lub imageData.

Parametry

  • szczegóły

    obiekt

    • iconIndex

      number optional

      Wycofano. Ten argument jest ignorowany.

    • imageData

      ImageData | obiekt opcjonalny

      Obiekt ImageData lub słownik {size -> ImageData} reprezentujący ikonę, która ma zostać ustawiona. Jeśli ikona jest określona jako słownik, rzeczywisty obraz, który zostanie użyty, jest wybierany na podstawie gęstości pikseli ekranu. Jeśli liczba pikseli obrazu, które mieszczą 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ó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, rzeczywisty obraz, który zostanie użyty, jest wybierany na podstawie gęstości pikseli ekranu. Jeśli liczba pikseli obrazu, które mieszczą 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 odpowiednikiem „details.path = {'16': foo}”.

    • tabId

      liczba

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

  • callback

    function opcjonalne

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 101 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.pageAction.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 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 jest ustawiona na pusty ciąg znaków (''), wyskakujące okienko nie jest wyświetlane.

    • tabId

      liczba

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

  • callback

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 101 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.pageAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

Ustawia tytuł działania na stronie. Wyświetla się ona 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

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 101 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.

show()

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

Pokazuje działanie na stronie. Działanie na stronie jest wyświetlane po wybraniu karty.

Parametry

  • tabId

    liczba

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

  • callback

    function opcjonalne

    Chrome 67 lub nowsza wersja

    Parametr callback wygląda tak:

    () => void

Zwroty

  • thought Promise<void>

    Chrome 101 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.pageAction.onClicked.addListener(
  callback: function,
)

Uruchamiane 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