chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Opis

Używaj interfejsu API chrome.declarativeContent, aby podejmować działania w zależności od zawartości strony, bez konieczności uzyskiwania uprawnień do odczytu jej zawartości.

Uprawnienia

declarativeContent

.

Wykorzystanie

Interfejs Declarative Content API umożliwia włączenie działania rozszerzenia w zależności od adresu URL strony internetowej lub dopasowania selektora CSS do elementu na stronie bez konieczności dodawania uprawnień hosta lub wstrzykiwania skryptu treści.

Użyj uprawnienia activeTab, aby umożliwić interakcję ze stroną po kliknięciu przez użytkownika działania rozszerzenia.

Reguły

Reguły składają się z warunków i działań. Jeśli którykolwiek z warunków zostanie spełniony, zostaną wykonane wszystkie działania. Dostępne działania to setIcon i showAction.

PageStateMatcher dopasowuje strony internetowe tylko wtedy, gdy spełnione są wszystkie wymienione kryteria. Może on pasować do adresu URL strony, złożonego selektora CSS lub stanu dodania strony do zakładek. Ta reguła włącza działanie rozszerzenia na stronach Google, gdy obecne 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() ]
};

Aby włączyć działanie rozszerzenia również w przypadku witryn Google z filmem, możesz dodać drugi warunek, ponieważ każdy warunek wystarczy 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 wykonuje działania. Reguły są zachowywane między sesjami przeglądania, dlatego podczas instalowania rozszerzenia należy najpierw użyć metody removeRules, aby usunąć wcześniej zainstalowane reguły, a następnie metody addRules, aby zarejestrować nowe.

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

Dzięki uprawnieniu activeTab rozszerzenie nie będzie wyświetlać żadnych ostrzeżeń o uprawnieniach, a gdy użytkownik kliknie działanie rozszerzenia, będzie ono działać tylko na odpowiednich stronach.

Dopasowanie adresu URL strony

PageStateMatcher.pageurl jest dopasowywany, gdy spełnione są kryteria adresu URL. Najczęstsze kryteria to konkatenacja hosta, ścieżki lub adresu URL, po której następuje „Zawiera”, „Równa się”, „Prefiks” lub „Sufiks”. W tabeli poniżej znajdziesz kilka przykładów:

Kryteria Dopasowania
{ hostSuffix: 'google.com' } Wszystkie adresy URL Google
{ pathPrefix: '/docs/extensions' } Adresy URL dokumentacji rozszerzenia
{ urlContains: 'developer.chrome.com' } Wszystkie adresy URL dokumentacji dla deweloperów Chrome

We wszystkich kryteriach wielkość liter ma znaczenie. Pełną listę kryteriów znajdziesz w artykule UrlFilter.

Dopasowywanie usługi porównywania cen

Warunki PageStateMatcher.css muszą być selektorami złożonymi, co oznacza, że w selektorach nie można uwzględniać kombinatorów, takich jak odstępy lub „>”. Dzięki temu Chrome może 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 pasują tylko do wyświetlanych elementów: jeśli element pasujący do selektora ma wartość display:none lub jeden z jego elementów nadrzędnych ma wartość display:none, nie powoduje to dopasowania warunku. Elementy stylizowane za pomocą visibility:hidden, umieszczone poza ekranem lub ukryte przez inne elementy mogą nadal spełniać warunek.

Dopasowanie stanu dodanego do zakładek

Warunek PageStateMatcher.isBookmarked umożliwia dopasowanie stanu bieżącego adresu URL zapisanego w zakładkach w profilu użytkownika. Aby użyć tego warunku, w pliku manifestu rozszerzenia należy zadeklarować uprawnienie „bookmarks”.

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

    unieważnienie,

    Funkcja constructor wygląda tak:

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

  • css

    string[] opcjonalne

    Warunek jest spełniony, jeśli wszystkie selektory arkusza 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: podanie setek selektorów CSS lub selektorów CSS, które pasują do setek elementów na stronie, może spowolnić działanie witryn.

  • isBookmarked

    boolean opcjonalne

    Chrome 45 lub nowsza wersja

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

  • pageUrl

    UrlFilter opcjonalny

    Dopasowanie występuje, jeśli warunki UrlFilter są spełnione w przypadku adresu URL najwyższego poziomu strony.

RequestContentScript

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

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

Właściwości

  • konstruktor

    unieważnienie,

    Funkcja constructor wygląda tak:

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

  • allFrames

    boolean opcjonalne

    Określa, czy skrypt treści jest uruchamiany we wszystkich ramkach strony z dopasowaniem czy tylko w górnej ramce. Wartość domyślna to false.

  • css

    string[] opcjonalne

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

  • js

    string[] opcjonalne

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

  • matchAboutBlank

    boolean opcjonalne

    Określa, czy skrypt treści ma być wstawiany na stronach about:blank i about:srcdoc. Wartość domyślna to false.

SetIcon

Deklaratywne działanie zdarzenia, które ustawia kwadratową ikonę n-dip dla działania na stronie lub działania w przeglądarce rozszerzenia, gdy spełnione są odpowiednie warunki. Z tego działania można korzystać bez uprawnień hosta, ale rozszerzenie musi mieć działanie na stronie lub w przeglądarce.

Należy podać tylko jedną z tych wartości: imageData lub path. Oba są słownikami mapującymi liczbę pikseli na reprezentację obrazu. Reprezentacja obrazu w imageData to obiekt ImageData, na przykład z elementu canvas, a reprezentacja obrazu w path to ścieżka do pliku graficznego względem pliku manifestu rozszerzenia. Jeśli scale pikseli ekranu mieści się w pikselu niezależnym od urządzenia, używana jest ikona scale * n. Jeśli brakuje obrazu w wymaganym rozmiarze, inny obraz jest skalowany do wymaganego rozmiaru.

Właściwości

  • konstruktor

    unieważnienie,

    Funkcja constructor wygląda tak:

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

  • 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, używany obraz jest wybierany w zależności od gęstości pikseli ekranu. Jeśli liczba pikseli obrazu, które mieszczą się w jednej jednostce przestrzeni ekranu, wynosi scale, wybierany jest 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 odpowiada details.imageData = {'16': foo}.

ShowAction

Chrome 97 lub nowsza wersja

Deklaratywne działanie zdarzenia, które ustawia działanie paska narzędzi rozszerzenia na stan włączony, gdy spełnione są odpowiednie warunki. Z tego działania można korzystać bez uprawnień hosta. Jeśli rozszerzenie ma uprawnienie activeTab, kliknięcie działania na stronie przyznaje dostęp do aktywnej karty.

Na stronach, na których warunki nie są spełnione, działanie paska narzędzi rozszerzenia będzie wyświetlane w odcieniach szarości, a kliknięcie go spowoduje otwarcie menu kontekstowego, a nie wywołanie działania.

Właściwości

ShowPageAction

Wycofane w Chrome 97

Użyj declarativeContent.ShowAction.

Deklaratywne działanie zdarzenia, które ustawia działanie na stronie rozszerzenia na stan włączony, gdy spełnione są odpowiednie warunki. Z tego działania można korzystać bez uprawnień hosta, ale rozszerzenie musi mieć działanie na stronie. Jeśli rozszerzenie ma uprawnienie activeTab, kliknięcie działania na stronie przyznaje dostęp do aktywnej karty.

Na stronach, na których warunki nie są spełnione, działanie paska narzędzi rozszerzenia będzie wyświetlane w odcieniach szarości, a kliknięcie go spowoduje otwarcie menu kontekstowego, a nie wywołanie działania.

Właściwości

Wydarzenia

onPageChanged

Udostępnia interfejs Declarative Event API, który składa się z addRules, removeRules i getRules.

Warunki

PageStateMatcher

Działania

RequestContentScript

SetIcon

ShowPageAction

ShowAction