chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Opis

Używaj interfejsu chrome.declarativeContent API do wykonywania działań w zależności od treści strony bez konieczności uzyskiwania uprawnień do odczytywania treści strony.

Uprawnienia

declarativeContent

Wykorzystanie

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

Użyj uprawnienia activeTab, aby wchodzić w 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, wszystkie działania zostaną wykonane. Działania to setIcon i showAction.

Symbol PageStateMatcher pasuje do stron internetowych tylko wtedy, gdy zostaną spełnione wszystkie wymienione kryteria. Może on odpowiadać adresowi URL strony, złożonemu selektorowi CSS lub stanowi strony po dodaniu do zakładek. Ta reguła umożliwia działanie rozszerzenia na stronach Google, gdy występuje 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 w przypadku witryn Google z filmem, możesz dodać drugi warunek, ponieważ każdy warunek wystarczy, aby wywołać wszystkie określone działania:

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 któraś reguła ma co najmniej 1 spełniony warunek, i wykonuje działania. Reguły są zachowywane w różnych sesjach przeglądania, dlatego podczas instalacji rozszerzenia najpierw użyj funkcji removeRules, aby wyczyścić wcześniej zainstalowane reguły, a potem użyj funkcji 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ń dotyczących uprawnień, a gdy użytkownik kliknie działanie rozszerzenia, będzie ono działać tylko na odpowiednich stronach.

Dopasowywanie adresów URL stron

Symbol PageStateMatcher.pageurl pasuje, gdy spełnione są kryteria adresu URL. Najczęstsze kryteria to połączenie hosta, ścieżki lub adresu URL, po którym 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 dokumentów rozszerzenia
{ urlContains: 'developer.chrome.com' } Wszystkie adresy URL dokumentacji dla deweloperów Chrome

Wszystkie kryteria uwzględniają wielkość liter. Pełną listę kryteriów znajdziesz w sekcji UrlFilter.

Dopasowywanie usług 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 białe znaki czy „>”. 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 jest display:none lub jeden z jego elementów nadrzędnych jest display:none, nie powoduje to dopasowania warunku. Elementy, które mają styl visibility:hidden, są umieszczone poza ekranem lub zasłaniają je inne elementy, nadal mogą spełniać warunek.

Dopasowywanie stanu dodania do zakładek

Warunek PageStateMatcher.isBookmarked umożliwia dopasowanie stanu bieżącego adresu URL w zakładkach w profilu użytkownika. Aby korzystać z tego warunku, w manifeście rozszerzenia musi być zadeklarowane 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,

    pusty

    Funkcja constructor wygląda tak:

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

  • css

    string[] opcjonalnie

    Warunek jest spełniony, jeśli wszystkie selektory CSS w tablicy pasują do wyświetlanych elementów w ramce o tym samym pochodzeniu 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

    wartość logiczna opcjonalna

    Chrome 45 lub nowszy

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

  • pageUrl

    UrlFilter opcjonalny

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

RequestContentScript

Deklaratywna czynność zdarzenia, która wstawia skrypt treści.

OSTRZEŻENIE: ta czynność jest nadal eksperymentalna i nie jest obsługiwana w stabilnych wersjach Chrome.

Właściwości

  • konstruktor,

    pusty

    Funkcja constructor wygląda tak:

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

  • allFrames

    wartość logiczna opcjonalna

    Określa, czy skrypt treści ma być uruchamiany we wszystkich ramkach pasującej strony, czy tylko w ramce najwyższego poziomu. Wartość domyślna to false.

  • css

    string[] opcjonalnie

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

  • js

    string[] opcjonalnie

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

  • matchAboutBlank

    wartość logiczna opcjonalna

    Czy wstawić skrypt treści na stronach about:blank i about:srcdoc. Wartość domyślna to false.

SetIcon

Deklaratywne działanie zdarzenia, które ustawia ikonę kwadratową o rozdzielczości n-dip dla działania na stronie lub działania przeglądarki rozszerzenia, gdy spełnione są odpowiednie warunki. Tego działania można używać bez uprawnień hosta, ale rozszerzenie musi mieć stronę lub działanie przeglądarki.

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, np. z elementu canvas, a reprezentacja obrazu w path to ścieżka do pliku obrazu 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 tym rozmiarze, inny obraz zostanie przeskalowany do wymaganego rozmiaru.

Właściwości

  • konstruktor,

    pusty

    Funkcja constructor wygląda tak:

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

  • 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, użyty obraz 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, 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 jest równoznaczne z details.imageData = {'16': foo}.

ShowAction

Chrome 97 lub nowszy

Deklaratywne działanie zdarzenia, które ustawia działanie paska narzędzi rozszerzenia w stanie włączonym, gdy spełnione są odpowiednie warunki. Tego działania można używać 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 w skali szarości, a kliknięcie go spowoduje otwarcie menu kontekstowego zamiast wywołania działania.

Właściwości

ShowPageAction

Wycofane w Chrome 97

Użyj declarativeContent.ShowAction.

Deklaratywne działanie związane ze zdarzeniem, które ustawia działanie na stronie rozszerzenia w stan włączony, gdy spełnione są odpowiednie warunki. Tego działania można używać 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 w skali szarości, a kliknięcie go spowoduje otwarcie menu kontekstowego zamiast wywołania działania.

Właściwości

Wydarzenia

onPageChanged

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

Warunki

PageStateMatcher

Działania

RequestContentScript

SetIcon

ShowPageAction

ShowAction