chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Açıklama

Sayfa içeriğini okuma izni gerektirmeden, sayfa içeriğine bağlı olarak işlem yapmak için chrome.declarativeContent API'sini kullanın.

İzinler

declarativeContent

Kullanım

Declarative Content API, ana makine izinleri eklemeniz veya içerik komut dosyası yerleştirmeniz gerekmeden web sayfasının URL'sine ya da CSS seçicinin sayfadaki bir öğeyle eşleşip eşleşmediğine bağlı olarak uzantınızın işlemini etkinleştirmenize olanak tanır.

Kullanıcı, uzantının işlem düğmesini tıkladıktan sonra bir sayfayla etkileşim kurmak için activeTab iznini kullanın.

Kurallar

Kurallar, koşullar 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'dır.

PageStateMatcher, web sayfalarıyla yalnızca listelenen tüm ölçütler karşılandığında eşleşir. Sayfa URL'si, CSS bileşik seçicisi veya bir sayfanın yer işaretli durumu ile eşleşebilir. Aşağıdaki kural, bir şifre alanı 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 video içeren Google sitelerinde de etkinleştirmek için 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 karşılanmış en az bir koşulu olup olmadığını test eder ve işlemleri yürütür. Kurallar, tarama oturumları boyunca geçerli olur. Bu nedenle, uzantı yükleme sırasında önce removeRules kullanarak daha önce yüklenen kuralları temizlemeli, ardından addRules kullanarak yeni kuralları kaydetmelisiniz.

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 alakalı sayfalarda çalışır.

Sayfa URL'si Eşleştirme

URL ölçütleri karşılandığında PageStateMatcher.pageurl eşleşir. En yaygın ölçütler, ana makine, yol veya URL'nin birleştirilmesinden sonra Contains (İçerir), Equals (Eşittir), Prefix (Önek) veya Suffix (Sonek) ile devam eden ölçütlerdir. 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ı dokümanlarının 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. Bu nedenle, 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 stil verilen, ekran dışında konumlandırılan veya diğer öğeler tarafından gizlenen öğeler, koşulunuzun eşleşmesini sağlayabilir.

Yer İşareti Durumu Eşleştirme

PageStateMatcher.isBookmarked koşulu, kullanıcının profilindeki mevcut URL'nin yer işaretli durumunun eşleştirilmesine olanak tanır. Bu koşuldan yararlanmak için uzantı manifestinde "yer işaretleri" izni bildirilmelidir.

Türler

Tür

ImageData

PageStateMatcher

Bir web sayfasının durumunu çeşitli ölçütlere göre eşleştirir.

Özellikler

  • oluşturucu

    void

    constructor işlevi şu şekilde görünür: 

    (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çevedeki görüntülenen öğelerle eşleşirse eşleşir. Eşleşmeyi 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

    boolean isteğe bağlı

    Chrome 45 ve sonraki sürümler

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

  • pageUrl

    UrlFilter isteğe bağlı

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

RequestContentScript

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

UYARI: Bu işlem hâlâ deneyseldir ve Chrome'un kararlı sürümlerinde desteklenmez.

Özellikler

  • oluşturucu

    void

    constructor işlevi şu şekilde görünür: 

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

  • allFrames

    boolean isteğe bağlı

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

  • css

    string[] isteğe bağlı

    İçerik komut dosyasına eklenmesi gereken CSS dosyalarının adları.

  • js

    string[] isteğe bağlı

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

  • matchAboutBlank

    boolean isteğe bağlı

    İçerik komut dosyasının about:blank ve about:srcdoc üzerine eklenip eklenmeyeceği. Varsayılan değer false'dır.

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 bildirimli 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'den yalnızca biri belirtilmelidir. Her ikisi de bir dizi pikseli görüntü gösterimine eşleyen sözlüklerdir. imageData içindeki resim gösterimi bir ImageData nesnesidir (örneğin, canvas öğesinden). path içindeki resim gösterimi ise uzantının manifestine göre bir resim dosyasının yoludur. scale ekran pikseli, cihazdan bağımsız bir piksele sığıyorsa scale * n simgesi kullanılır. Bu ölçek eksikse başka bir resim gerekli boyuta göre yeniden boyutlandırılır.

Özellikler

  • oluşturucu

    void

    constructor işlevi şu şekilde görünür: 

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

  • imageData

    ImageData | object isteğe bağlı

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

ShowAction

Chrome 97 ve sonraki sürümler

İlgili koşullar karşılandığında uzantının araç çubuğu işlemini etkin duruma getiren, bildirim temelli bir etkinlik işlemidir. 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 tonlarda olur ve tıklandığında işlemi tetiklemek yerine bağlam menüsü açılır.

Özellikler

ShowPageAction

Chrome 97'den beri kullanımdan kaldırıldı

Lütfen declarativeContent.ShowAction kullanın.

İlgili koşullar karşılandığında uzantının sayfa işlemini etkin duruma getiren, bildirim temelli bir etkinlik işlemidir. 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 tonlarda olur ve tıklandığında işlemi tetiklemek yerine bağlam menüsü açılır.

Özellikler

Etkinlikler

onPageChanged

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

Koşullar

PageStateMatcher

İşlemler

RequestContentScript

SetIcon

ShowPageAction

ShowAction