chrome.declarativeContent

Opis

Interfejs API chrome.declarativeContent umożliwia wykonywanie działań w zależności od zawartości strony bez konieczności uzyskiwania uprawnień do odczytywania jej zawartości.

Uprawnienia

declarativeContent

Pojęcia i zastosowanie

Kluczowy termin: działanie rozszerzenia steruje jego ikoną na pasku narzędzi.

Interfejs deklaratywnego interfejsu Content API umożliwia włączenie działania rozszerzenia w zależności od adresu URL strony internetowej lub od tego, czy selektor arkusza CSS pasuje do elementu na stronie, bez konieczności dodawania uprawnień hosta ani wstawiania skryptu treści.

Uprawnienie activeTab umożliwia interakcję ze stroną po kliknięciu działania rozszerzenia przez użytkownika.

Reguły

Reguły składają się z warunków i działań. Jeśli dowolny z warunków zostanie spełniony, wszystkie działania są wykonywane. Działania to setIcon() i showAction().

Element PageStateMatcher dopasowuje strony internetowe tylko wtedy, gdy spełnione są wszystkie wymienione kryteria. Może pasować do adresu URL strony, złożonego selektora CSS lub stanu zakładki strony. Poniższa reguła umożliwia działanie rozszerzenia na stronach Google, gdy dostępne jest pole hasła:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Sukces: wszystkie warunki i działania są tworzone za pomocą konstruktora tak jak w poprzednim przykładzie.

Aby umożliwić działanie rozszerzenia w witrynach Google z filmem, możesz dodać drugi warunek, który wystarcza do wywołania wszystkich określonych działań:

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Zdarzenie onPageChanged sprawdza, czy jakakolwiek reguła ma co najmniej 1 spełniony warunek, i wykona działania. Reguły są nieustanne w trakcie sesji przeglądania, dlatego podczas instalacji rozszerzenia należy najpierw użyć removeRules, aby wyczyścić wcześniej zainstalowane reguły, a potem zarejestrować nowe za pomocą polecenia addRules.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

Uwaga: zawsze rejestruj lub wyrejestruj reguły zbiorczo, ponieważ każda z tych operacji odtwarza wewnętrzne struktury danych. Odtwarzanie tego typu jest kosztowne, ale ułatwia szybsze generowanie algorytmu dopasowywania.

Rozszerzenie z uprawnieniami activeTab nie będzie wyświetlać żadnych ostrzeżeń o uprawnieniach, a gdy użytkownik kliknie to działanie, będzie ono działać tylko na odpowiednich stronach.

Dopasowywanie adresu URL strony

Wartość PageStateMatcher.pageurl pasuje do momentu, gdy kryteria adresu URL są spełnione. Najpopularniejsze kryteria to połączenie hosta, ścieżki lub adresu URL, po którym następuje ciąg Zawiera, Równa się, Prefiks lub Sufiks. Poniższa tabela zawiera kilka przykładów:

Kryteria	Odpowiada
{ hostSuffix: 'google.com' }	Wszystkie adresy URL Google
{ pathPrefix: '/docs/extensions' }	Adresy URL dokumentacji rozszerzeń
{ urlContains: 'developer.chrome.com' }	Adresy URL wszystkich dokumentów dla deweloperów Chrome

We wszystkich kryteriach rozróżniana jest wielkość liter. Pełną listę kryteriów znajdziesz w sekcji UrlFilter.

Dopasowywanie CSS

Warunki PageStateMatcher.css muszą być selektorami złożonymi, co oznacza, że w selektorach nie możesz uwzględnić kombinatorów, takich jak odstępy czy „>”. Dzięki temu Chrome będzie skuteczniej dopasowywać selektory.

Selektory złożone (OK)	Złożone selektory (nieprawidłowe)
a	div p
iframe.special[src^='http']	p>span.highlight
ns|*	p + ol
#abcd:checked	p::first-line

Warunki CSS dopasowują tylko wyświetlane elementy: jeśli element pasujący do selektora to display:none lub jeden z jego elementów nadrzędnych to display:none, nie powoduje to spełnienia warunku. Elementy, które mają styl visibility:hidden, są umieszczone poza ekranem lub ukryte przez inne elementy, nadal mogą spełniać Twój warunek.

Dopasowywanie stanu dodanego do zakładek

Warunek PageStateMatcher.isBookmarked umożliwia dopasowanie stanu bieżącego adresu URL dodanego do zakładek w profilu użytkownika. Aby skorzystać z tego warunku, w pliku manifestu rozszerzenia musisz zadeklarować uprawnienie „zakładki”.

Typy

ImageDataType

Więcej informacji znajdziesz na stronie https://developer.mozilla.org/en-US/docs/Web/API/ImageData.

Typ

ImageData

PageStateMatcher

Dopasowuje stan strony internetowej na podstawie różnych kryteriów.

Właściwości

• konstruktor

  void

  Funkcja constructor wygląda tak:

  (arg: PageStateMatcher)=> {...}

  • arg

    PageStateMatcher

  • returns

    PageStateMatcher

• css

  string[] opcjonalny

  Dopasowuje, jeśli wszystkie selektory CSS w tablicy pasują do wyświetlanych elementów w ramce o tym samym źródle co ramka główna strony. Aby przyspieszyć dopasowywanie, wszystkie selektory w tej tablicy muszą być selektorami złożonymi. Uwaga: wyświetlanie setek selektorów arkusza CSS lub wyświetlanie selektorów arkusza CSS, które pasują setki razy na stronę, może spowolnić działanie stron internetowych.

• isBookmarked

  wartość logiczna opcjonalna

  Chrome 45 i nowsze wersje

  Dopasowuje, jeśli stan strony dodany do zakładek jest równy określonej wartości. Wymaga uprawnień do zakładek.

• pageUrl

  Opcjonalne UrlFilter

  Pasuje do sytuacji, w której spełnione są warunki UrlFilter w przypadku adresu URL najwyższego poziomu strony.

RequestContentScript

Deklaracyjne działanie zdarzenia, które wstrzykuje skrypt treści.

OSTRZEŻENIE: to działanie jest nadal w fazie eksperymentalnej i nie jest obsługiwane w stabilnych wersjach Chrome.

Właściwości

• konstruktor

  void

  Funkcja constructor wygląda tak:

  (arg: RequestContentScript)=> {...}

  • arg

    RequestContentScript

  • returns

    RequestContentScript

• allFrames

  wartość logiczna opcjonalna

  Określa, czy skrypt treści działa we wszystkich ramkach pasującej strony czy tylko w górnej ramce. Wartość domyślna to false.

• css

  string[] opcjonalny

  Nazwy plików CSS, które mają zostać wstawione jako część skryptu treści.

• js

  string[] opcjonalny

  Nazwy plików JavaScript, które mają zostać wstawione jako część skryptu treści.

• matchAboutBlank

  wartość logiczna opcjonalna

  Określa, czy wstawić skrypt treści w przypadku about:blank i about:srcdoc. Wartość domyślna to false.

SetIcon

Deklarowane działanie zdarzenia, które powoduje ustawienie kwadratowej ikony n-dip odpowiadającej działaniu strony lub działaniu przeglądarki rozszerzenia w czasie, gdy są spełnione określone warunki. Tego działania można użyć bez uprawnień hosta, ale rozszerzenie musi mieć działanie dotyczące strony lub przeglądarki.

Należy podać dokładnie jedno z tych elementów: imageData lub path. Oba to słowniki mapujące liczbę pikseli na reprezentację obrazu. Graficzna reprezentacja w elemencie imageData to obiekt ImageData, na przykład pochodzący z elementu canvas, a obraz w elemencie path to ścieżka do pliku graficznego względem pliku manifestu rozszerzenia. Jeśli piksele ekranu scale mieszczą się w pikselu niezależnym od urządzenia, używana jest ikona scale * n. Jeśli brakuje tej skali, kolejny obraz zostaje zmniejszony do wymaganego rozmiaru.

Właściwości

• konstruktor

  void

  Funkcja constructor wygląda tak:

  (arg: SetIcon)=> {...}

  • arg

    SetIcon

  • returns

    SetIcon

• 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}.

ShowAction

Chrome 97 i nowsze wersje

Deklatywne działanie zdarzenia, które powoduje, że działanie na pasku narzędzi rozszerzenia aktywuje się w czasie, gdy spełnione są odpowiednie warunki. Tego działania można użyć bez uprawnień hosta. Jeśli rozszerzenie ma uprawnienie activeTab, kliknięcie działania na stronie powoduje przyznanie dostępu do aktywnej karty.

Na stronach, na których nie zostaną spełnione warunki, pasek narzędzi rozszerzenia zmieni kolor na szary, a jego kliknięcie spowoduje otwarcie menu kontekstowego, a nie wywołanie działania.

Właściwości

• konstruktor

  void

  Funkcja constructor wygląda tak:

  (arg: ShowAction)=> {...}

  • arg

    ShowAction

  • returns

    ShowAction

ShowPageAction

Wycofane od Chrome 97

Użyj adresu declarativeContent.ShowAction.

Deklaratywna akcja zdarzenia, w ramach której włączane jest działanie na stronie rozszerzenia w czasie, gdy spełnione są odpowiednie warunki. Tej czynności można użyć bez uprawnień hosta, ale rozszerzenie musi obsługiwać działanie na stronie. Jeśli rozszerzenie ma uprawnienie activeTab, kliknięcie działania na stronie powoduje przyznanie dostępu do aktywnej karty.

Na stronach, na których nie zostaną spełnione warunki, pasek narzędzi rozszerzenia zmieni kolor na szary, a jego kliknięcie spowoduje otwarcie menu kontekstowego, a nie wywołanie działania.

Właściwości

• konstruktor

  void

  Funkcja constructor wygląda tak:

  (arg: ShowPageAction)=> {...}

  • arg

    ShowPageAction

  • returns

    ShowPageAction

Wydarzenia

onPageChanged

Udostępnia deklaracyjny interfejs API zdarzenia obejmujący addRules, removeRules oraz getRules.

Warunki

PageStateMatcher

Działania

RequestContentScript

SetIcon

ShowPageAction

ShowAction