chrome.scripting

Açıklama

Komut dosyasını farklı bağlamlarda yürütmek için chrome.scripting API'yi kullanın.

İzinler

scripting

Kullanılabilirlik

Chrome 88 ve üstü sürümler MV3 ve sonraki sürümler

Manifest

chrome.scripting API'yi kullanmak için manifest dosyasındaki "scripting" iznini ve komut dosyalarının yerleştirileceği sayfalar için ana makine izinlerini tanımlayın. Geçici ana makine izinleri sağlayan "host_permissions" anahtarını veya "activeTab" iznini kullanın. Aşağıdaki örnekte ActiveTab izni kullanılmaktadır.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

Kavramlar ve kullanım

Web sitelerine JavaScript ve CSS eklemek için chrome.scripting API'yi kullanabilirsiniz. Bu, içerik komut dosyaları ile yapabileceğinize benzer. Ancak uzantılar, chrome.scripting ad alanını kullanarak çalışma zamanında karar verebilir.

Yerleştirme hedefleri

JavaScript veya CSS'nin yerleştirileceği bir hedef belirtmek için target parametresini kullanabilirsiniz.

Yalnızca tabId alanının doldurulması zorunludur. Varsayılan olarak, ekleme işlemi belirtilen sekmenin ana çerçevesinde çalışır.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

Belirtilen sekmenin tüm karelerinde çalıştırmak için allFrames boole'sini true olarak ayarlayabilirsiniz.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

Ayrıca, bağımsız çerçeve kimlikleri belirterek bir sekmenin belirli karelerine ekleme yapabilirsiniz. Çerçeve kimlikleri hakkında daha fazla bilgi için chrome.webNavigation API'ye bakın.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

Yerleştirilen kod

Uzantılar, harici bir dosya veya çalışma zamanı değişkeni aracılığıyla eklenecek kodu belirtebilir.

Files

Dosyalar, uzantının kök dizinine göreli yollar olan dizeler olarak belirtilir. Aşağıdaki kod, script.js dosyasını sekmenin ana çerçevesine ekler.

function getTabId() { ... }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

Çalışma zamanı işlevleri

scripting.executeScript() ile JavaScript yerleştirirken dosya yerine yürütülecek bir işlev belirtebilirsiniz. Bu işlev, mevcut uzantı bağlamında kullanılabilen bir işlev değişkeni olmalıdır.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

args özelliğini kullanarak bu sorunu çözebilirsiniz:

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

Çalışma zamanı dizeleri

Bir sayfaya CSS yerleştiriyorsanız css özelliğinde kullanılacak bir dize de belirtebilirsiniz. Bu seçenek yalnızca scripting.insertCSS() için kullanılabilir. scripting.executeScript() kullanarak dize yürütemezsiniz.

function getTabId() { ... }
const css = "body { background-color: red; }";

chrome.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

Sonuçları yönetin

JavaScript yürütmenin sonuçları uzantıya iletilir. Her kare için tek bir sonuç dahil edilir. Ana çerçevenin sonuç dizisindeki ilk dizin olacağı garanti edilir. Diğer tüm çerçeveler belirli olmayan bir sıradadır.

function getTabId() { ... }
function getTitle() { return document.title; }

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() herhangi bir sonuç döndürmedi.

Vaatler

Komut dosyası yürütme işleminin sonuç olarak vadedilirse Chrome, söz verilenin sonuçlanmasını bekler ve sonuç değerini döndürür.

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

chrome.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

Örnekler

Tüm dinamik içerik komut dosyalarının kaydını iptal et

Aşağıdaki snippet, uzantının önceden kaydettiği tüm dinamik içerik komut dosyalarının kaydını iptal eden bir işlev içeriyor.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts(scriptIds);
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

chrome.scripting API'yi denemek için Chrome uzantı örnekleri deposundaki komut dosyası örneğini yükleyin.

Türler

ContentScriptFilter

Chrome 96 ve sonraki sürümler

Özellikler

  • ids

    string[] isteğe bağlı

    Belirtilirse getRegisteredContentScripts, yalnızca bu listede belirtilen kimliğe sahip komut dosyalarını döndürür.

CSSInjection

Özellikler

  • css

    string isteğe bağlı

    Eklenecek CSS'yi içeren bir dize. Tam olarak files ve css belirtilmelidir.

  • dosyalar

    string[] isteğe bağlı

    Eklenecek CSS dosyalarının, uzantının kök dizinine göre yolu. Tam olarak files ve css belirtilmelidir.

  • kaynak

    StyleOrigin isteğe bağlı

    Ekleme için stil kaynağı. Varsayılan olarak 'AUTHOR' değerine ayarlanır.

  • CSS'nin ekleneceği hedefi belirten ayrıntılar.

ExecutionWorld

Chrome 95 ve sonraki sürümler

Bir komut dosyasının içinde yürütüleceği JavaScript dünyası.

Enum

"ISOLATED"
Bu uzantıya özgü yürütme ortamı olan izole dünyayı belirtir.

"MAIN"
DOM'nin ana dünyasını belirtir. DOM, ana makine sayfasının JavaScript'i ile paylaşılan yürütme ortamıdır.

InjectionResult

Özellikler

  • documentId

    dize

    Chrome 106 ve sonraki sürümler

    Yerleştirmeyle ilişkili belge.

  • frameId

    sayı

    Chrome 90 ve sonraki sürümler

    Eklemeyle ilişkilendirilen çerçeve.

  • sonuç

    isteğe bağlı

    Komut dosyasının yürütülmesinin sonucu.

InjectionTarget

Özellikler

  • allFrames

    boole isteğe bağlı

    Komut dosyasının sekmedeki tüm karelere eklenip eklenmeyeceği. Varsayılan olarak false değerine ayarlanır. frameIds belirtilmişse bu doğru olmamalıdır.

  • documentIds

    string[] isteğe bağlı

    Chrome 106 ve sonraki sürümler

    Eklenecek belirli documentId'lerin kimlikleri. frameIds ayarlanmışsa bu ayar ayarlanmamalıdır.

  • frameIds

    number[] isteğe bağlı

    Eklenecek belirli çerçevelerin kimlikleri.

  • tabId

    sayı

    Ekleme yapılacak sekmenin kimliği.

RegisteredContentScript

Chrome 96 ve sonraki sürümler

Özellikler

  • allFrames

    boole isteğe bağlı

    Doğru değerine ayarlanırsa çerçeve, 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. Varsayılan olarak false (yanlış) değerine ayarlanır, yani yalnızca üst kare eşleştirilir.

  • css

    string[] isteğe bağlı

    Eşleşen sayfalara eklenecek 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 eklenir.

  • excludeMatches

    string[] isteğe bağlı

    Bu içerik komut dosyasının başka bir şekilde 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.

  • id

    dize

    İçerik komut dosyasının API çağrısında belirtilen kimliği. Oluşturulan komut dosyası kimlikleri için ön ek olarak ayrıldığından, "_" karakteriyle başlamamalıdır.

  • js

    string[] isteğe bağlı

    Eşleşen sayfalara yerleştirilecek JavaScript dosyalarının listesi. Bunlar, bu dizide göründükleri sırayla eklenir.

  • matchOriginAsFallback

    boole isteğe bağlı

    Chrome 119 ve sonraki sürümler

    Komut dosyasının, desteklenmeyen bir şema içeren çerçevelere yerleştirilip yerleştirilemeyeceğini belirtir; özellikle: about:, data:, blob: veya filesystem:. Bu gibi durumlarda, komut dosyasının yerleştirilmesinin gerekip gerekmediğini belirlemek için URL'nin kaynağı kontrol edilir. Kaynak null ise (veriler: URL'lerde olduğu gibi) kullanılan kaynak, geçerli çerçeveyi oluşturan veya bu kareye gitmeyi başlatan çerçevedir. Bunun üst çerçeve olmayabileceğini unutmayın.

  • eşleşiyor

    string[] isteğe bağlı

    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ı bölümüne bakın. registerContentScripts için belirtilmelidir.

  • persistAcrossSessions

    boole isteğe bağlı

    Bu içerik komut dosyasının gelecekteki oturumlarda kullanılmaya devam edip etmeyeceğini belirtir. Varsayılan, doğru değeridir.

  • runAt

    RunAt isteğe bağlı

    JavaScript dosyalarının web sayfasına ne zaman ekleneceğini belirtir. document_idle, tercih edilen ve varsayılan değerdir.

  • ulusal

    ExecutionWorld isteğe bağlı

    Chrome 102 ve sonraki sürümler

    Komut dosyasının çalıştırılacağı JavaScript "world". Varsayılan olarak ISOLATED değerine ayarlanır.

ScriptInjection

Özellikler

  • args

    any[] isteğe bağlı

    Chrome 92 ve sonraki sürümler

    Sağlanan işleve iletilecek bağımsız değişkenler. Bu yalnızca func parametresi belirtilmişse geçerlidir. Bu bağımsız değişkenler JSON ile serileştirilebilir olmalıdır.

  • dosyalar

    string[] isteğe bağlı

    Eklenecek JS veya CSS dosyalarının, uzantının kök dizinine göre yolu. Tam olarak files veya func belirtilmelidir.

  • injectImmediately

    boole isteğe bağlı

    Chrome 102 ve sonraki sürümler

    Eklemenin hedefte en kısa sürede tetiklenip tetiklenmeyeceği. Bunun, ekleme işleminin sayfa yüklenmeden önce gerçekleşeceğini garanti etmediğini unutmayın. Çünkü, komut dosyası hedefe ulaşana kadar sayfa zaten yüklenmiş olabilir.

  • Komut dosyasının ekleneceği hedefi belirten ayrıntılar.

  • ulusal

    ExecutionWorld isteğe bağlı

    Chrome 95 ve sonraki sürümler

    Komut dosyasının çalıştırılacağı JavaScript "world". Varsayılan olarak ISOLATED değerine ayarlanır.

  • func

    void isteğe bağlı

    Chrome 92 ve sonraki sürümler

    Eklenecek JavaScript işlevi. Bu işlev serileştirilecek ve ardından yerleştirme için seri durumdan çıkarılacaktır. Bu, tüm bağlı parametrelerin ve yürütme bağlamının kaybedileceği anlamına gelir. Tam olarak files veya func belirtilmelidir.

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

    ()=> {...}

StyleOrigin

Stil değişikliğinin kökeni. Daha fazla bilgi için stil kaynaklarına bakın.

Enum

"AUTHOR"

Yöntemler

executeScript()

Söz 
chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

Hedef bağlama bir komut dosyası ekler. Varsayılan olarak, komut dosyası document_idle anında veya sayfa zaten yüklenmişse hemen çalıştırılır. injectImmediately özelliği ayarlanırsa sayfanın yüklenmesi tamamlanmamış olsa bile komut dosyası beklemeden eklenir. Komut dosyası bir sözü değerlendiriyorsa tarayıcı, vaatin oturmasını bekler ve sonuç değerini döndürür.

Parametreler

İlerlemeler

  • Promise<InjectionResult[]>

    Chrome 90 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

getRegisteredContentScripts()

Söz Chrome 96 ve üstü sürümler 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Belirtilen filtreyle eşleşen bu uzantı için dinamik olarak kaydedilmiş tüm içerik komut dosyalarını döndürür.

Parametreler

İlerlemeler

  • Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

insertCSS()

Söz 
chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

Hedef bağlama bir CSS stil sayfası ekler. Birden fazla kare belirtilirse başarısız olan yerleştirme işlemleri yoksayılır.

Parametreler

  • enjeksiyon

    CSSInjection

    Eklenecek stillerin ayrıntıları.

  • geri çağırma

    Functions (isteğe bağlı)

    callback parametresi şu şekilde görünür: 

    ()=>void

İlerlemeler

  • Promise<void>

    Chrome 90 ve sonraki sürümler

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

registerContentScripts()

Söz Chrome 96 ve üstü sürümler 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Bu uzantı için bir veya daha fazla içerik komut dosyası kaydeder.

Parametreler

  • komut dosyaları

    RegisteredContentScript[]

    Kaydedilecek komut dosyalarının listesini içerir. Komut dosyası ayrıştırma/dosya doğrulaması sırasında hatalar varsa veya belirtilen kimlikler zaten mevcutsa komut dosyası kaydedilmez.

  • geri çağırma

    Functions (isteğe bağlı)

    callback parametresi şu şekilde görünür: 

    ()=>void

İlerlemeler

  • Promise<void>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

removeCSS()

Söz Chrome 90 ve üstü sürümler 
chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

Daha önce bu uzantı tarafından hedef bağlamdan eklenen CSS stil sayfasını kaldırır.

Parametreler

  • enjeksiyon

    CSSInjection

    Kaldırılacak stillerin ayrıntıları. css, files ve origin özelliklerinin, insertCSS aracılığıyla eklenen stil sayfasıyla tam olarak eşleşmesi gerektiğini unutmayın. Var olmayan bir stil sayfasını kaldırmaya çalışmak hiçbir işlem yapmaz.

  • geri çağırma

    Functions (isteğe bağlı)

    callback parametresi şu şekilde görünür: 

    ()=>void

İlerlemeler

  • Promise<void>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

unregisterContentScripts()

Söz Chrome 96 ve üstü sürümler 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Bu uzantıya ilişkin içerik komut dosyalarının kaydını siler.

Parametreler

  • filter

    ContentScriptFilter isteğe bağlı

    Belirtilirse yalnızca filtreyle eşleşen dinamik içerik komut dosyalarının kaydını iptal eder. Aksi halde, uzantının tüm dinamik içerik komut dosyalarının kaydı silinir.

  • geri çağırma

    Functions (isteğe bağlı)

    callback parametresi şu şekilde görünür: 

    ()=>void

İlerlemeler

  • Promise<void>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

updateContentScripts()

Söz Chrome 96 ve üstü sürümler 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Bu uzantı için bir veya daha fazla içerik komut dosyasını günceller.

Parametreler

  • komut dosyaları

    RegisteredContentScript[]

    Güncellenecek komut dosyalarının listesini içerir. Bir özellik, yalnızca bu nesnede belirtilmesi durumunda mevcut komut dosyası için güncellenir. Komut dosyası ayrıştırma/dosya doğrulaması sırasında hatalar varsa veya belirtilen kimlikler tam olarak kayıtlı bir komut dosyasına karşılık gelmiyorsa komut dosyası güncellenmez.

  • geri çağırma

    Functions (isteğe bağlı)

    callback parametresi şu şekilde görünür: 

    ()=>void

İlerlemeler

  • Promise<void>

    Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.