chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Deskripsi

Gunakan chrome.declarativeContent API untuk melakukan tindakan bergantung pada konten halaman, tanpa memerlukan izin untuk membaca konten halaman.

Izin

declarativeContent

Penggunaan

Declarative Content API memungkinkan Anda mengaktifkan tindakan ekstensi, bergantung pada URL halaman web, atau jika pemilih CSS cocok dengan elemen di halaman, tanpa perlu menambahkan izin host atau menyuntikkan skrip konten.

Gunakan izin activeTab untuk berinteraksi dengan halaman setelah pengguna mengklik tindakan ekstensi.

Aturan

Aturan terdiri dari kondisi dan tindakan. Jika salah satu kondisi terpenuhi, semua tindakan akan dieksekusi. Tindakannya adalah setIcon dan showAction.

PageStateMatcher cocok dengan halaman web jika dan hanya jika semua kriteria yang tercantum terpenuhi. Dapat cocok dengan URL halaman, pemilih gabungan CSS atau status bookmark halaman. Aturan berikut mengaktifkan tindakan ekstensi di halaman Google saat ada kolom sandi:

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

Untuk mengaktifkan tindakan ekstensi untuk situs Google dengan video, Anda dapat menambahkan kondisi kedua, karena setiap kondisi sudah cukup untuk memicu semua tindakan yang ditentukan:

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() ]
};

Peristiwa onPageChanged menguji apakah ada aturan yang memiliki setidaknya satu kondisi yang terpenuhi dan menjalankan tindakan. Aturan tetap ada di seluruh sesi penjelajahan; oleh karena itu, selama waktu penginstalan ekstensi, Anda harus menggunakan removeRules terlebih dahulu untuk menghapus aturan yang sebelumnya diinstal, lalu menggunakan addRules untuk mendaftarkan aturan baru.

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

Dengan izin activeTab, ekstensi Anda tidak akan menampilkan peringatan izin apa pun dan saat pengguna mengklik tindakan ekstensi, ekstensi hanya akan berjalan di halaman yang relevan.

Pencocokan URL Halaman

PageStateMatcher.pageurl cocok saat kriteria URL terpenuhi. Kriteria yang paling umum adalah penggabungan host, jalur, atau URL, diikuti dengan Berisi, Sama dengan, Awalan, atau Akhiran. Tabel berikut berisi beberapa contoh:

Kriteria Kecocokan
{ hostSuffix: 'google.com' } Semua URL Google
{ pathPrefix: '/docs/extensions' } URL dokumen ekstensi
{ urlContains: 'developer.chrome.com' } Semua URL dokumen developer Chrome

Semua kriteria peka huruf besar/kecil. Untuk daftar lengkap kriteria, lihat UrlFilter.

Pencocokan CSS

Kondisi PageStateMatcher.css harus berupa pemilih gabungan, artinya Anda tidak dapat menyertakan kombinator seperti spasi kosong atau ">" dalam pemilih. Hal ini membantu Chrome mencocokkan pemilih secara lebih efisien.

Pemilih Gabungan (OK) Pemilih Kompleks (Tidak Oke)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

Kondisi CSS hanya cocok dengan elemen yang ditampilkan: jika elemen yang cocok dengan pemilih Anda adalah display:none atau salah satu elemen induknya adalah display:none, kondisi tersebut tidak akan cocok. Elemen yang diberi gaya dengan visibility:hidden, diposisikan di luar layar, atau disembunyikan oleh elemen lain masih dapat membuat kondisi Anda cocok.

Pencocokan Status yang Di-bookmark

Kondisi PageStateMatcher.isBookmarked memungkinkan pencocokan status URL saat ini yang di-bookmark di profil pengguna. Untuk menggunakan kondisi ini, izin "bookmarks" harus dideklarasikan dalam manifes ekstensi.

Jenis

Jenis

ImageData

PageStateMatcher

Mencocokkan status halaman web berdasarkan berbagai kriteria.

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti: 

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

  • css

    string[] opsional

    Cocok jika semua pemilih CSS dalam array cocok dengan elemen yang ditampilkan dalam frame dengan asal yang sama dengan frame utama halaman. Semua pemilih dalam array ini harus berupa pemilih gabungan untuk mempercepat pencocokan. Catatan: Mencantumkan ratusan pemilih CSS atau mencantumkan pemilih CSS yang cocok ratusan kali per halaman dapat memperlambat situs web.

  • isBookmarked

    boolean opsional

    Chrome 45+

    Cocok jika status halaman yang di-bookmark sama dengan nilai yang ditentukan. Memerlukan izin bookmark.

  • pageUrl

    UrlFilter opsional

    Cocok jika kondisi UrlFilter terpenuhi untuk URL tingkat teratas halaman.

RequestContentScript

Tindakan peristiwa deklaratif yang menyuntikkan skrip konten.

PERINGATAN: Tindakan ini masih bersifat eksperimental dan tidak didukung pada build Chrome yang stabil.

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti: 

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

  • allFrames

    boolean opsional

    Apakah skrip konten berjalan di semua frame halaman yang cocok, atau hanya di frame teratas. Default-nya adalah false.

  • css

    string[] opsional

    Nama file CSS yang akan disisipkan sebagai bagian dari skrip konten.

  • js

    string[] opsional

    Nama file JavaScript yang akan disisipkan sebagai bagian dari skrip konten.

  • matchAboutBlank

    boolean opsional

    Apakah akan menyisipkan skrip konten di about:blank dan about:srcdoc. Jumlah defaultnya adalah false

SetIcon

Tindakan peristiwa deklaratif yang menetapkan ikon persegi n-dip untuk tindakan halaman atau tindakan browser ekstensi saat kondisi yang sesuai terpenuhi. Tindakan ini dapat digunakan tanpa izin host, tetapi ekstensi harus memiliki tindakan halaman atau browser.

Tepatnya salah satu dari imageData atau path harus ditentukan. Keduanya adalah kamus yang memetakan sejumlah piksel ke representasi gambar. Representasi gambar di imageData adalah objek ImageData; misalnya, dari elemen canvas, sedangkan representasi gambar di path adalah jalur ke file gambar relatif terhadap manifes ekstensi. Jika piksel layar scale cocok dengan piksel yang tidak bergantung pada perangkat, ikon scale * n akan digunakan. Jika skala tersebut tidak ada, gambar lain akan diubah ukurannya menjadi ukuran yang diperlukan.

Properti

  • konstruktor

    void

    Fungsi constructor akan terlihat seperti: 

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

  • imageData

    ImageData | object opsional

    Objek ImageData atau kamus {size -> ImageData} yang merepresentasikan ikon yang akan ditetapkan. Jika ikon ditentukan sebagai kamus, gambar yang digunakan akan dipilih berdasarkan kepadatan piksel layar. Jika jumlah piksel gambar yang sesuai dengan satu unit ruang layar sama dengan scale, maka gambar dengan ukuran scale * n akan dipilih, dengan n adalah ukuran ikon di UI. Setidaknya satu gambar harus ditentukan. Perhatikan bahwa details.imageData = foo setara dengan details.imageData = {'16': foo}.

ShowAction

Chrome 97+

Tindakan peristiwa deklaratif yang menyetel tindakan toolbar ekstensi ke status aktif saat kondisi yang sesuai terpenuhi. Tindakan ini dapat digunakan tanpa izin host. Jika ekstensi memiliki izin activeTab, mengklik tindakan halaman akan memberikan akses ke tab aktif.

Di halaman yang tidak memenuhi kondisi, tindakan toolbar ekstensi akan berwarna abu-abu, dan mengkliknya akan membuka menu konteks, bukan memicu tindakan.

Properti

ShowPageAction

Tidak digunakan lagi sejak Chrome 97

Gunakan declarativeContent.ShowAction.

Tindakan peristiwa deklaratif yang menetapkan tindakan halaman ekstensi ke status aktif saat kondisi yang sesuai terpenuhi. Tindakan ini dapat digunakan tanpa izin host, tetapi ekstensi harus memiliki tindakan halaman. Jika ekstensi memiliki izin activeTab, mengklik tindakan halaman akan memberikan akses ke tab aktif.

Di halaman yang tidak memenuhi kondisi, tindakan toolbar ekstensi akan berwarna abu-abu, dan mengkliknya akan membuka menu konteks, bukan memicu tindakan.

Properti

Acara

onPageChanged

Menyediakan Declarative Event API yang terdiri dari addRules, removeRules, dan getRules.

Kondisi

PageStateMatcher

Tindakan

RequestContentScript

SetIcon

ShowPageAction

ShowAction