Bu sayfa, Cloud Translation API ile çevrilmiştir.

İç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:

i18n
depolama alanı
çalışma zamanı:
- Bağlanın
- getManifest
- getURL
- id
- onConnect
- onMessage
- sendMessage

İç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. `@exclude`Greasemonkey 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);