chrome.pageAction

Opis

Przy użyciu interfejsu API chrome.pageAction umieść 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 dotyczą one wszystkich stron. Czynności wykonywane na stronie są wyszarzone, gdy są nieaktywne.

Dostępność

≤ MV2

Oto kilka przykładów:

  • Zasubskrybuj kanał RSS tej strony
  • Utwórz pokaz slajdów ze zdjęć z tej strony

Ikona RSS na zrzucie ekranu poniżej symbolizuje działanie na stronie, które umożliwia zasubskrybowanie kanału RSS z bieżącą stroną.

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

Zamiast tego rozważ użycie działania przeglądarki, aby użytkownicy mogli zawsze 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
  },
  ...
}

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. Chrome wybierze najbliższy i przeskaluje go, aby wypełnić 16-dipową przestrzeń. Dzięki temu nawet jeśli rozmiar ikony się zmieni, nie będzie trzeba wprowadzać żadnych innych ikon. Jeśli jednak różnica w rozmiarze jest zbyt duża, to skalowanie może spowodować utratę szczegółów lub niewyraźne obrazy.

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

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

Części interfejsu użytkownika

Tak jak w przypadku działań w przeglądarce, działania na stronie mogą mieć ikonę, etykietkę i wyskakujące okienko, ale nie mogą mieć plakietek. Dodatkowo czynności wykonywane na stronie mogą być wyszarzone. Informacje o ikonach, etykietkach i wyskakujących okienkach znajdziesz w artykule o interfejsie działań przeglądarki.

Działania na stronie są wyświetlane i wyszarzone za pomocą metod pageAction.show i pageAction.hide. Domyślnie czynności wykonywane na stronie są wyszarzone. Podczas wyświetlania ikony określasz kartę, na której ma się ona pojawić. Ikona pozostaje widoczna do czasu zamknięcia karty lub do momentu, gdy użytkownik kliknie inny adres URL (np. dlatego, że użytkownik kliknie link).

Wskazówki

Aby uzyskać najlepszy efekt wizualny, przestrzegaj tych wytycznych:

  • Używaj działań na stronach, jeśli działają one tylko na kilku stronach.
  • Nie stosuj działań związanych ze stroną w przypadku funkcji, które są przydatne dla większości stron. Użyj zamiast tego działań w przeglądarce.
  • Nie animuj ikony stale. To po prostu irytujące.

Typy

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

getPopup()

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

Pobiera zestaw dokumentu HTML jako wyskakujące okienko dla tego działania na stronie.

Parametry

  • szczegóły

    TabDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (result: string)=>void

    • wynik

      string,

Akcje powrotne

  • Obietnica<string>

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

Pobiera tytuł działania na stronie.

Parametry

  • szczegóły

    TabDetails

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    (result: string)=>void

    • wynik

      string,

Akcje powrotne

  • Obietnica<string>

    Chrome 101 i nowsze wersje

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

hide()

Obietnica 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
)

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

Parametry

  • tabId

    Liczba

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

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

Ustawia ikonę działania na stronie. 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

    • iconIndex

      Liczba opcjonalnie

      Wycofano. Ten argument jest ignorowany.

    • 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, rzeczywisty obraz do użycia jest wybierany w zależności od gęstości pikseli na ekranie. Jeśli liczba pikseli obrazu, które mieszczą się w jednej jednostce obszaru na ekranie, równa się scale, zostanie wybrany 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 -> preferred image path} 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 na ekranie. Jeśli liczba pikseli obrazu, które mieszczą się w jednej jednostce obszaru na ekranie, równa się scale, zostanie wybrany 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

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

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

Otwiera dokument HTML jako wyskakujące okienko, gdy użytkownik kliknie ikonę działania na stronie.

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

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

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

Określa tytuł działania na stronie. Informacje te wyświetlają się w etykietce nad działaniem strony.

Parametry

  • szczegóły

    obiekt

    • tabId

      Liczba

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

    • title

      string,

      Ciąg etykietki.

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

    Chrome 101 i nowsze wersje

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

show()

Obietnica 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
)

Pokazuje działanie na stronie. Czynność na stronie jest widoczna po każdym wybraniu karty.

Parametry

  • tabId

    Liczba

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

  • wywołanie zwrotne

    funkcja opcjonalnie

    Chrome 67 i nowsze wersje

    Parametr callback wygląda tak: 

    ()=>void

Akcje powrotne

  • Promise<void>

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

Uruchamiane po kliknięciu ikony działania na stronie. To zdarzenie nie zostanie uruchomione, jeśli działanie na stronie zawiera wyskakujące okienko.

Parametry

  • wywołanie zwrotne

    funkcja

    Parametr callback wygląda tak: 

    (tab: tabs.Tab)=>void