chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Açıklama

Sayfa içeriğini okuma izni gerektirmeden sayfanın içeriğine göre işlem yapmak için chrome.declarativeContent API'yi kullanın.

İzinler

declarativeContent

Kullanım

Declarative Content API, ana makine izinleri eklemenize veya içerik komut dosyası eklemenize gerek kalmadan, bir web sayfasının URL'sine veya bir CSS seçicinin sayfadaki bir öğeyle eşleşmesine bağlı olarak uzantınızın işlemini etkinleştirmenize olanak tanır.

Kullanıcı, uzantının işlemini tıkladıktan sonra bir sayfayla etkileşim kurmak için activeTab iznini kullanın.

Kurallar

Kurallar, koşullardan ve işlemlerden oluşur. Koşullardan herhangi biri karşılanırsa tüm işlemler yürütülür. İşlemler setIcon ve showAction şeklindedir.

PageStateMatcher, yalnızca listelenen tüm ölçütler karşılandığında web sayfalarıyla eşleşir. Bir sayfa URL'si, CSS bileşik seçici veya bir sayfanın yer işareti eklenmiş durumu ile eşleşebilir. Aşağıdaki kural, bir şifre alanı mevcut olduğunda uzantının Google sayfalarındaki işlemini etkinleştirir:

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

Uzantının işlemini videolu Google siteleri için de etkinleştirmek istiyorsanız ikinci bir koşul ekleyebilirsiniz. Her koşul, belirtilen tüm işlemleri tetiklemek için yeterlidir:

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

onPageChanged etkinliği, herhangi bir kuralın en az bir koşulunun karşılanıp karşılanmadığını test eder ve işlemleri yürütür. Kurallar, tarama oturumları boyunca kalıcıdır. Bu nedenle, uzantı yükleme sırasında önceden yüklenmiş kuralları temizlemek için önce removeRules, ardından yenilerini kaydetmek için addRules kullanmanız gerekir.

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

activeTab izniyle uzantınız herhangi bir izin uyarısı göstermez ve kullanıcı uzantı işlemini tıkladığında yalnızca ilgili sayfalarda çalışır.

Sayfa URL'si Eşleştirme

PageStateMatcher.pageurl, URL ölçütleri karşılandığında eşleşir. En yaygın ölçütler; ana makine, yol veya URL'nin birleştirilmesi ve ardından İçerir, Eşittir, Önek veya Sonek'in eklenmesidir. Aşağıdaki tabloda birkaç örnek verilmiştir:

Ölçütler Eşleşmeler
{ hostSuffix: 'google.com' } Tüm Google URL'leri
{ pathPrefix: '/docs/extensions' } Uzantı belgelerinin URL'leri
{ urlContains: 'developer.chrome.com' } Tüm Chrome geliştirici belgeleri URL'leri

Tüm ölçütler büyük/küçük harfe duyarlıdır. Ölçütlerin tam listesi için UrlFilter başlıklı makaleyi inceleyin.

CSS Eşleştirme

PageStateMatcher.css koşulları bileşik seçiciler olmalıdır. Yani seçicilerinize boşluk veya ">" gibi birleştiriciler ekleyemezsiniz. Bu sayede Chrome, seçicileri daha verimli bir şekilde eşleştirebilir.

Bileşik Seçiciler (Tamam) Karmaşık Seçiciler (Uygun Değil)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

CSS koşulları yalnızca görüntülenen öğelerle eşleşir: Seçicinizle eşleşen bir öğe display:none ise veya üst öğelerinden biri display:none ise koşulun eşleşmesine neden olmaz. visibility:hidden ile stillendirilmiş, ekran dışında konumlandırılmış veya diğer öğeler tarafından gizlenmiş öğeler de koşulunuzla eşleşebilir.

Yer İşareti Durumu Eşleştirme

PageStateMatcher.isBookmarked koşulu, kullanıcının profilindeki mevcut URL'nin yer işareti eklenmiş durumunun eşleştirilmesine olanak tanır. Bu koşuldan yararlanmak için uzantı manifest dosyasında "bookmarks" izni belirtilmelidir.

Türler

Tür

ImageData

PageStateMatcher

Çeşitli ölçütlere göre bir web sayfasının durumuyla eşleşir.

Özellikler

  • oluşturucu

    geçersiz

    constructor işlevi şu şekildedir: 

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

  • css

    string[] isteğe bağlı

    Dizideki tüm CSS seçiciler, sayfanın ana çerçevesiyle aynı kaynağa sahip bir çerçevede görüntülenen öğelerle eşleşirse eşleşir. Eşleştirmeyi hızlandırmak için bu dizideki tüm seçiciler bileşik seçici olmalıdır. Not: Yüzlerce CSS seçiciyi listelemek veya sayfa başına yüzlerce kez eşleşen CSS seçicileri listelemek web sitelerini yavaşlatabilir.

  • isBookmarked

    boole isteğe bağlı

    Chrome 45+

    Sayfanın yer işareti eklenmiş durumu belirtilen değere eşitse eşleşir. Yer işaretleri izni gerekir.

  • pageUrl

    UrlFilter isteğe bağlı

    Sayfanın üst düzey URL'si için UrlFilter koşulları karşılanıyorsa eşleşir.

RequestContentScript

İçerik komut dosyası ekleyen açıklayıcı etkinlik işlemi.

UYARI: Bu işlem henüz deneme aşamasındadır ve Chrome'un kararlı sürümlerinde desteklenmez.

Özellikler

  • oluşturucu

    geçersiz

    constructor işlevi şu şekildedir: 

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

  • allFrames

    boole isteğe bağlı

    İçerik komut dosyasının, eşleşen sayfanın tüm çerçevelerinde mi yoksa yalnızca üst çerçevede mi çalıştırılacağı. false varsayılandır.

  • css

    string[] isteğe bağlı

    İçerik komut dosyasının bir parçası olarak yerleştirilecek CSS dosyalarının adları.

  • js

    string[] isteğe bağlı

    İçerik komut dosyasının bir parçası olarak yerleştirilecek JavaScript dosyalarının adları.

  • matchAboutBlank

    boole isteğe bağlı

    İçerik komut dosyasının about:blank ve about:srcdoc adreslerine eklenip eklenmeyeceği. Varsayılan değer: false.

SetIcon

İlgili koşullar karşılandığında uzantının sayfa işlemi veya tarayıcı işlemi için n-dip kare simgesini ayarlayan bildirimsel etkinlik işlemi. Bu işlem, ana makine izinleri olmadan kullanılabilir ancak uzantının bir sayfa veya tarayıcı işlemi olmalıdır.

imageData veya path özelliklerinden yalnızca biri belirtilmelidir. Her ikisi de bir dizi pikseli bir resim gösterimine eşleyen sözlüklerdir. imageData içindeki resim temsili bir ImageData nesnesidir (ör. canvas öğesinden), path içindeki resim temsili ise uzantının manifest dosyasına göre bir resim dosyasının yoludur. scale ekran pikseli bir cihazdan bağımsız piksele sığıyorsa scale * n simgesi kullanılır. Bu ölçek yoksa başka bir resim gerekli boyuta göre yeniden boyutlandırılır.

Özellikler

  • oluşturucu

    geçersiz

    constructor işlevi şu şekildedir: 

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

  • imageData

    ImageData | nesne isteğe bağlı

    Ayarlanacak simgeyi temsil eden bir ImageData nesnesi veya sözlük {size -> ImageData}. Simge bir sözlük olarak belirtilirse kullanılan resim, ekranın piksel yoğunluğuna göre seçilir. Bir ekran alanı birimine sığan resim piksellerinin sayısı scale ise scale * n boyutunda bir resim seçilir. Burada n, kullanıcı arayüzündeki simgenin boyutudur. En az bir resim belirtilmelidir. details.imageData = foo, details.imageData = {'16': foo} ile eşdeğerdir.

ShowAction

Chrome 97 ve sonraki sürümler

İlgili koşullar karşılandığında uzantının araç çubuğu işlemini etkin duruma ayarlayan bildirim temelli bir etkinlik işlemi. Bu işlem, ana makine izinleri olmadan kullanılabilir. Uzantının activeTab izni varsa sayfa işlemini tıkladığınızda etkin sekmeye erişim izni verilir.

Koşulların karşılanmadığı sayfalarda uzantının araç çubuğu işlemi gri tonlamalı olur ve tıklandığında işlem tetiklenmek yerine bağlam menüsü açılır.

Özellikler

ShowPageAction

Chrome 97'den itibaren desteği sonlandırıldı

Lütfen declarativeContent.ShowAction kullanın.

İlgili koşullar karşılandığında uzantının sayfa işlemini etkin duruma ayarlayan açıklayıcı bir etkinlik işlemi. Bu işlem, ana makine izinleri olmadan kullanılabilir ancak uzantının bir sayfa işlemi olmalıdır. Uzantının activeTab izni varsa sayfa işlemini tıkladığınızda etkin sekmeye erişim izni verilir.

Koşulların karşılanmadığı sayfalarda uzantının araç çubuğu işlemi gri tonlamalı olur ve tıklandığında işlem tetiklenmek yerine bağlam menüsü açılır.

Özellikler

Etkinlikler

onPageChanged

addRules, removeRules ve getRules'dan oluşan Declarative Event API'yi sağlar.

Koşullar

PageStateMatcher

İşlemler

RequestContentScript

SetIcon

ShowPageAction

ShowAction