İçerik komut dosyaları

İçerik komut dosyaları, web sayfaları bağlamında çalışan dosyalardır. Standart Belge Nesne Modeli'ni (DOM) kullanarak, tarayıcının ziyaret ettiği web sayfalarının ayrıntılarını okuyabilir, bu sayfalarda değişiklikler yapabilir ve bilgileri üst uzantılarına aktarabilirler.

İçerik komut dosyası özelliklerini anlayın

İçerik komut dosyaları, mesajları uzantıyla gönderip üst uzantıları tarafından kullanılan Chrome API'lerine erişebilir. Ayrıca chrome.runtime.getURL() ile bir uzantı dosyasının URL'sine erişebilir ve sonucu diğer URL'lerle aynı şekilde kullanabilirler.

// Code for displaying EXTENSION_DIR/images/myimage.png:
var imgURL = chrome.runtime.getURL("images/myimage.png");
document.getElementById("someImage").src = imgURL;

Ayrıca, içerik komut dosyası aşağıdaki Chrome API'lerine doğrudan erişebilir:

İçerik komut dosyaları diğer API'lere doğrudan erişemez.

Yalnız dünyalarda çalışın

İçerik komut dosyaları izole bir dünyada yaşar ve içerik komut dosyalarının sayfayla veya ek içerik komut dosyalarıyla çakışmadan JavaScript ortamında değişiklikler yapmasına olanak tanır.

Bir uzantı, aşağıdaki örneğe benzer koda sahip bir web sayfasında çalışabilir.

<html>
  <button id="mybutton">click me</button>
  <script>
    var greeting = "hello, ";
    var button = document.getElementById("mybutton");
    button.person_name = "Bob";
    button.addEventListener("click", function() {
      alert(greeting + button.person_name + ".");
    }, false);
  </script>
</html>

Bu uzantı, aşağıdaki içerik komut dosyasını ekleyebilir.

var greeting = "hola, ";
var button = document.getElementById("mybutton");
button.person_name = "Roberto";
button.addEventListener("click", function() {
  alert(greeting + button.person_name + ".");
}, false);

Düğmeye basıldığında her iki uyarı da gösterilir.

Yalıtılmış dünyalar; içerik komut dosyalarının, uzantının ve web sayfasının başka kullanıcılar tarafından oluşturulan değişkenlere veya işlevlere erişmesine izin vermez. Bu, içerik komut dosyalarına, web sayfası tarafından erişilmemesi gereken işlevi etkinleştirme olanağı da verir.

Komut dosyası ekle

İçerik komut dosyaları programatik olarak veya bildirime dayalı olarak yerleştirilebilir.

Programatik olarak ekleyin

Belirli durumlarda çalışması gereken içerik komut dosyaları için programatik yerleştirme kullanın.

Programatik içerik komut dosyası eklemek için manifest dosyasında activeTab iznini sağlayın. Bu, etkin sitenin ana makinesine güvenli erişim ve sekmeler iznine geçici erişim izni vererek içerik komut dosyasının, kaynaklar arası izinler belirtmeden geçerli etkin sekmede çalışmasına olanak tanır.

{
  "name": "My extension",
  ...
  "permissions": [
    "activeTab"
  ],
  ...
}

İçerik komut dosyaları kod olarak yerleştirilebilir.

chrome.runtime.onMessage.addListener(
  function(message, callback) {
    if (message == "changeColor"){
      chrome.tabs.executeScript({
        code: 'document.body.style.backgroundColor="orange"'
      });
    }
  });

Veya bir dosyanın tamamı yerleştirilebilir.

chrome.runtime.onMessage.addListener(
  function(message, callback) {
    if (message == "runContentScript"){
      chrome.tabs.executeScript({
        file: 'contentScript.js'
      });
    }
  });

Bildirim temelli olarak ekle

Belirtilen sayfalarda otomatik olarak çalıştırılması gereken içerik komut dosyaları için bildirim temelli yerleştirme kullanın.

Bildirim temelli olarak yerleştirilen komut dosyaları, manifest dosyasında "content_scripts" alanının altına kaydedilir. JavaScript dosyalarını, CSS dosyalarını veya her ikisini birden içerebilir. Otomatik olarak çalıştırılan tüm içerik komut dosyaları, eşleşme kalıplarını belirtmelidir.

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["http://*.nytimes.com/*"],
     "css": ["myStyles.css"],
     "js": ["contentScript.js"]
   }
 ],
 ...
}
Ad Tür Açıklama
matches {: #matches } dize dizisi Zorunludur. Bu içerik komut dosyasının hangi sayfalara yerleştirileceğini belirtir. Bu dizelerin söz dizimiyle ilgili daha fazla ayrıntı için Eşleşme Kalıpları'na, URL'lerin nasıl hariç tutulacağına ilişkin bilgi için Eşleşme kalıpları ve glob'lar konusuna bakın.
css {: #css } dize dizisi İsteğe bağlı. Eşleşen sayfalara yerleştirilecek CSS dosyalarının listesi. Bunlar, sayfa için herhangi bir DOM oluşturulmadan veya görüntülenmeden önce, bu dizide göründükleri sırayla yerleştirilir.
js {: #js } dize dizisi İsteğe bağlı. Eşleşen sayfalara yerleştirilecek JavaScript dosyalarının listesi. Bunlar, dizide göründükleri sırayla yerleştirilir.
match_about_blank {: #match_about_blank } boolean İsteğe bağlı. Komut dosyasının, üst veya açıcı çerçevenin matches politikasında tanımlanan kalıplardan biriyle eşleştiği bir about:blank çerçevesine eklenip eklenmeyeceğini belirtir. Varsayılan olarak false değerine ayarlanır.

Eşleşmeleri ve glob'ları hariç tut

Belirtilen sayfa eşleşmesi, aşağıdaki alanlar manifest kaydına eklenerek özelleştirilebilir.

Ad Tür Açıklama
exclude_matches {: #excluded_matches } dize dizisi İsteğe bağlı. Bu içerik komut dosyasının normalde yerleştirileceği sayfaları hariç tutar. Bu dizelerin söz dizimiyle ilgili daha fazla ayrıntı için Eşleşme Kalıpları bölümüne bakın.
include_globs {: #include_globs } dize dizisi İsteğe bağlı. Yalnızca bu glob ile eşleşen URL'leri eklemek için matches tarihinden sonra uygulanır. Buradaki amaç, @include Greasemonkey anahtar kelimesini öykünmektir.
exclude_globs {: #excluded_globs } dize dizisi İsteğe bağlı. Bu glob ile eşleşen URL'leri hariç tutmak için matches tarihinden sonra uygulanır. @excludeGreasemonkey anahtar kelimesini taklit etmek için kullanılır.

İçerik komut dosyası, URL'si herhangi bir matches kalıbıyla veya include_globs kalıbıyla eşleşirse exclude_matches veya exclude_globs kalıbıyla eşleşmediği sürece sayfaya eklenir.

matches özelliği zorunlu olduğundan, exclude_matches, include_globs ve exclude_globs yalnızca hangi sayfaların etkileneceğini sınırlamak için kullanılabilir.

Aşağıdaki uzantı, içerik komut dosyasını http://www.nytimes.com/ health alanına ekler, ancak http://www.nytimes.com/ business alanına eklemez .

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Yerküre özellikleri, eşleşme kalıplarından farklı ve daha esnek bir söz dizimi kullanır. Kabul edilebilir glob dizeleri, "joker karakter" yıldız ve soru işaretleri içerebilen URL'lerdir. Yıldız işareti * boş dize de dahil olmak üzere her uzunluktaki herhangi bir dizeyle eşleşirken soru işareti ? herhangi bir tek karakterle eşleşir.

Örneğin, http:// ??? .example.com/foo/ * glob'u aşağıdakilerin herhangi biriyle eşleşir:

  • http:// www .example.com/foo /bar
  • http:// .example.com/foo /

Ancak, aşağıdakilerle eşleşmez:

  • http:// .example.com/foo/bar
  • http:// örneği .com/foo/
  • http://www.example.com/foo

Bu uzantı, içerik komut dosyasını http:/www.nytimes.com/ arts /index.html ve http://www.nytimes.com/ jobs /index.html alanlarına ekler, ancak http://www.nytimes.com/ Sports /index.html sayfalarına eklemez.

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Bu uzantı, içerik komut dosyasını http:// date .nytimes.com ve http://.nytimes.com/ eski alanlarına ekler, ancak http:// bilim .nytimes.com veya http://www.nytimes.com/ bilim adreslerine eklemez .

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Doğru kapsamı elde etmek için bunlardan biri, tümü veya bazıları dahil edilebilir.

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*nytimes.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["contentScript.js"]
    }
  ],
  ...
}

Süre

JavaScript dosyaları web sayfasına yerleştirildiğinde run_at alanı tarafından kontrol edilir. Tercih edilen ve varsayılan alan "document_idle"'dir ancak gerekirse "document_start" veya "document_end" olarak da belirtilebilir.

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "run_at": "document_idle",
      "js": ["contentScript.js"]
    }
  ],
  ...
}
Ad Tür Açıklama
document_idle {: #document_idle } dize Tercih edilir. Mümkün olduğunda "document_idle" kullanın.

Tarayıcı, komut dosyalarının "document_end" arasında yerleştirileceği zamanı, windowonload etkinliğinin tetiklenmesinden hemen sonra seçer. Ekleme işleminin tam zamanı, dokümanın ne kadar karmaşık olduğuna, yüklenmesinin ne kadar sürdüğüne bağlıdır ve sayfa yükleme hızı için optimize edilmiştir.

"document_idle" konumunda çalışan içerik komut dosyalarının window.onload etkinliğini dinlemesi gerekmez. DOM tamamlandıktan sonra çalışacakları garanti edilir. Bir komut dosyasının kesinlikle window.onload tarihinden sonra çalışması gerekiyorsa uzantı, document.readyState özelliğini kullanarak onload zaten tetiklenip tetiklenmediğini kontrol edebilir.
document_start {: #document_start } dize Komut dosyaları, css ürününden tüm dosyalardan sonra, ancak başka bir DOM oluşturulmadan veya başka bir komut dosyası çalıştırılmadan önce yerleştirilir.
document_end {: #document_end } dize Komut dosyaları, DOM tamamlandıktan hemen sonra ancak resim ve çerçeve gibi alt kaynaklar yüklenmeden önce yerleştirilir.

Çerçeveleri belirtin

"all_frames" alanı, uzantının, JavaScript ve CSS dosyalarının belirtilen URL gereksinimleriyle eşleşen tüm karelere mi yoksa sekmenin yalnızca en üst karesine mi yerleştirilmesi gerektiğini belirtmesine olanak tanır.

{
  "name": "My extension",
  ...
  "content_scripts": [
    {
      "matches": ["http://*.nytimes.com/*"],
      "all_frames": true,
      "js": ["contentScript.js"]
    }
  ],
  ...
}
Ad Tür Açıklama
all_frames {: #all_frames } boolean İsteğe bağlı. Varsayılan olarak false değerine ayarlanır, yani yalnızca üst kare eşleşir.

true belirtilirse bu kare, sekmenin en üstündeki kare olmasa bile tüm karelere eklenir. Her çerçeve, URL gereksinimleri açısından bağımsız olarak kontrol edilir. URL gereksinimleri karşılanmazsa alt çerçevelere yerleştirilmez.

Yerleştirme sayfasıyla iletişim

İçerik komut dosyalarının yürütme ortamları ve bunları barındıran sayfalar birbirinden izole edilse de sayfanın DOM'una erişimi paylaşır. Sayfa, içerik komut dosyasıyla veya içerik komut dosyası üzerinden uzantıyla iletişim kurmak istiyorsa bunu paylaşılan DOM üzerinden yapmalıdır.

window.postMessage kullanılarak bir örnek oluşturulabilir:

var port = chrome.runtime.connect();

window.addEventListener("message", function(event) {
  // We only accept messages from ourselves
  if (event.source != window)
    return;

  if (event.data.type && (event.data.type == "FROM_PAGE")) {
    console.log("Content script received: " + event.data.text);
    port.postMessage(event.data.text);
  }
}, false);
document.getElementById("theButton").addEventListener("click",
    function() {
  window.postMessage({ type: "FROM_PAGE", text: "Hello from the webpage!" }, "*");
}, false);

Uzantı olmayan sayfa (example.html) kendisine mesaj gönderir. Bu mesaj, içerik komut dosyası tarafından engellenir ve incelenir, ardından uzantı işleminde yayınlanır. Bu şekilde sayfa, genişleme süreciyle bir iletişim hattı oluşturur. Bunun tersi de benzer yöntemlerle yapılabilir.

Güvende kalın

Yalıtılmış dünyalar bir koruma katmanı sağlarken, içerik komut dosyalarını kullanmak uzantılarda ve web sayfasında güvenlik açıkları oluşturabilir. İçerik komut dosyası, XMLHttpRequest oluşturma gibi ayrı bir web sitesinden içerik alıyorsa, komut dosyasını yerleştirmeden önce içerik siteler arası komut dosyası oluşturma saldırılarını filtrelemeye dikkat edin. Yalnızca "man-in-the-middle" saldırılarından kaçınmak için HTTPS üzerinden iletişim kurun.

Kötü amaçlı web sayfalarını filtrelediğinizden emin olun. Örneğin, aşağıdaki kalıplar tehlikelidir:

var data = document.getElementById("json-data")
// WARNING! Might be evaluating an evil script!
var parsed = eval("(" + data + ")")
var elmt_id = ...
// WARNING! elmt_id might be "); ... evil script ... //"!
window.setTimeout("animate(" + elmt_id + ")", 200);

Bunun yerine, komut dosyalarını çalıştırmayan daha güvenli API'leri tercih edin:

var data = document.getElementById("json-data")
// JSON.parse does not evaluate the attacker's scripts.
var parsed = JSON.parse(data);
var elmt_id = ...
// The closure form of setTimeout does not evaluate scripts.
window.setTimeout(function() {
  animate(elmt_id);
}, 200);