chrome.scripting

Açıklama

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

İzinler

scripting

Kullanılabilirlik

Chrome 88+ MV3+

Manifest

chrome.scripting API'sini kullanmak için manifest dosyasında "scripting" iznini ve komut dosyalarının ekleneceği sayfalar için ana makine izinlerini beyan edin. "host_permissions" tuşunu veya geçici ana makine izinleri veren "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'sini kullanabilirsiniz. Bu, içerik komut dosyaları ile yapabileceklerinize benzer. Ancak uzantılar, chrome.scripting ad alanını kullanarak çalışma zamanında kararlar verebilir.

Enjeksiyon hedefleri

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

Tek zorunlu alan tabId'dır. Varsayılan olarak, bir yerleştirme 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 çerçevelerinde çalışması için allFrames boolean değerini 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, tek tek çerçeve kimliklerini belirterek bir sekmenin belirli çerçevelerine de yerleştirebilirsiniz. Çerçeve kimlikleri hakkında daha fazla bilgi için chrome.webNavigation API başlıklı makaleyi inceleyin.

function getTabId() { ... }

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

Yerleştirilmiş kod

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

Dosyalar

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

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 ekliyorsanız css özelliğinde kullanılacak bir dize de belirtebilirsiniz. Bu seçenek yalnızca scripting.insertCSS() için kullanılabilir. scripting.executeScript() kullanarak bir 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ı işleme

JavaScript'in yürütülmesinin sonuçları uzantıya iletilir. Her kareye tek bir sonuç dahil edilir. Ana karenin, sonuç dizisindeki ilk dizin olduğu garanti edilir. Diğer tüm kareler ise belirlenmemiş bir sırada yer alı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ürmüyor.

Sözler

Komut dosyası yürütme sonucunda elde edilen değer bir söz ise Chrome, sözün yerine getirilmesini bekler ve sonuçta elde edilen değeri 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ı silme

Aşağıdaki snippet, uzantının daha önce kaydettiği tüm dinamik içerik komut dosyalarının kaydını silen bir işlev içerir.

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

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

Türler

ContentScriptFilter

Chrome 96 veya daha yeni bir sürüm

Özellikler

  • ids

    string[] isteğe bağlı

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

CSSInjection

Özellikler

  • css

    dize isteğe bağlı

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

  • dosyalar

    string[] isteğe bağlı

    Eklenecek CSS dosyalarının yolu (uzantının kök dizinine göre). Tam olarak bir 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 veya daha yeni bir sürüm

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'un ana dünyasını belirtir. Bu, ana sayfanın JavaScript'iyle paylaşılan yürütme ortamıdır.

InjectionResult

Özellikler

  • documentId

    dize

    Chrome 106 ve sonraki sürümler

    Ekleme işlemiyle ilişkili doküman.

  • frameId

    sayı

    Chrome 90 veya daha yeni bir sürüm

    Ekleme ile ilişkili çerçeve.

  • sonuç

    herhangi bir isteğe bağlı

    Komut dosyası yürütme sonucu.

InjectionTarget

Özellikler

  • allFrames

    boolean isteğe bağlı

    Komut dosyasının sekmedeki tüm çerçevelere 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

    İçine yerleştirilecek belirli documentId'lerin kimlikleri. frameIds ayarlandıysa bu ayarlanmamalıdır.

  • frameIds

    number[] isteğe bağlı

    Enjekte edilecek belirli çerçevelerin kimlikleri.

  • tabId

    sayı

    Eklenecek sekmenin kimliği.

RegisteredContentScript

Chrome 96 veya daha yeni bir sürüm

Özellikler

  • allFrames

    boolean isteğe bağlı

    Doğru olarak belirtilirse sekmedeki en üstteki çerçeve olmasa bile tüm çerçevelere yerleştirilir. Her çerçeve, URL koşulları açısından bağımsız olarak kontrol edilir. URL koşulları karşılanmazsa alt çerçevelere yerleştirilmez. Varsayılan olarak false değerini alır. Bu durumda yalnızca üst çerçeve eşleştirilir.

  • css

    string[] isteğe bağlı

    Eşleşen sayfalara yerleştirilecek CSS dosyalarının listesi. Bunlar, bu dizide göründükleri sırayla, sayfa için herhangi bir DOM oluşturulmadan veya görüntülenmeden önce yerleştirilir.

  • excludeMatches

    string[] isteğe bağlı

    Bu içerik komut dosyasının aksi takdirde içine yerleştirileceği sayfaları hariç tutar. Bu dizelerin söz dizimi hakkında daha fazla bilgi için Eşleşme Kalıpları bölümüne bakın.

  • id

    dize

    API çağrısında belirtilen içerik komut dosyasının kimliği. Oluşturulan komut dosyası kimlikleri için ön ek olarak ayrıldığından "_" ile 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 yerleştirilir.

  • matchOriginAsFallback

    boolean isteğe bağlı

    Chrome 119 veya daha yeni bir sürüm

    URL'nin desteklenmeyen bir şema (ör. about:, data:, blob: veya filesystem:) içerdiği çerçevelere komut dosyasının eklenip eklenemeyeceğini belirtir. Bu gibi durumlarda, komut dosyasının yerleştirilip yerleştirilmeyeceğini belirlemek için URL'nin kaynağı kontrol edilir. Kaynak null ise (data: URL'lerinde olduğu gibi) kullanılan kaynak, mevcut çerçeveyi oluşturan çerçeve veya bu çerçeveye gezinmeyi 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 ekleneceğini belirtir. Bu dizelerin söz dizimi hakkında daha fazla bilgi için Eşleşme Kalıpları bölümüne bakın. registerContentScripts için belirtilmelidir.

  • persistAcrossSessions

    boolean isteğe bağlı

    Bu içerik komut dosyasının gelecekteki oturumlarda kalıcı olup olmayacağını belirtir. Varsayılan değer true'dur.

  • runAt

    RunAt isteğe bağlı

    JavaScript dosyalarının web sayfasına ne zaman yerleştirileceğini belirtir. Tercih edilen ve varsayılan değer document_idle'dır.

  • dünya

    ExecutionWorld isteğe bağlı

    Chrome 102 veya daha yeni bir sürüm

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

ScriptInjection

Özellikler

  • args

    any[] isteğe bağlı

    Chrome 92 veya daha yeni bir sürüm

    Belirtilen işleve geçirilecek bağımsız değişkenler. Bu yalnızca func parametresi belirtilmişse geçerlidir. Bu bağımsız değişkenler JSON'a dönüştürülebilir olmalıdır.

  • dosyalar

    string[] isteğe bağlı

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

  • injectImmediately

    boolean isteğe bağlı

    Chrome 102 veya daha yeni bir sürüm

    Ekleme işleminin hedefte mümkün olduğunca kısa sürede tetiklenip tetiklenmeyeceği. Sayfa, komut dosyası hedefe ulaştığında zaten yüklenmiş olabileceğinden bunun, eklemenin sayfa yüklenmeden önce gerçekleşeceğini garanti etmediğini unutmayın.

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

  • dünya

    ExecutionWorld isteğe bağlı

    Chrome 95 veya daha yeni bir sürüm

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

  • func

    void optional

    Chrome 92 veya daha yeni bir sürüm

    Eklenecek bir JavaScript işlevi. Bu işlev, ekleme için önce serileştirilir, ardından seri durumdan çıkarılır. Bu nedenle, tüm bağlı parametreler ve yürütme bağlamı kaybolur. Tam olarak bir files veya func belirtilmelidir.

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

    () => {...}

StyleOrigin

Stil değişikliğinin kaynağı. Daha fazla bilgi için stil kaynakları bölümüne bakın.

Enum

"AUTHOR"

"USER"

Yöntemler

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

Hedef bağlama bir komut dosyası ekler. Varsayılan olarak komut dosyası document_idle tarihinde çalıştırılır veya sayfa zaten yüklenmişse hemen çalıştırılır. injectImmediately özelliği ayarlanırsa sayfa yüklenmeyi tamamlamamış olsa bile komut dosyası beklemeden yerleştirilir. Komut dosyası bir söz olarak değerlendirilirse tarayıcı, sözün yerine getirilmesini bekler ve sonuçta elde edilen değeri döndürür.

Parametreler

İadeler

getRegisteredContentScripts()

Chrome 96 veya daha yeni bir sürüm 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

Parametreler

  • filtrele

    ContentScriptFilter isteğe bağlı

    Uzantının dinamik olarak kaydedilen komut dosyalarını filtrelemek için kullanılan bir nesne.

İadeler

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

Hedef bağlama bir CSS stil sayfası ekler. Birden fazla çerçeve belirtilirse başarısız eklemeler yoksayılır.

Parametreler

  • enjeksiyon

    CSSInjection

    Eklenecek stillerin ayrıntıları.

İadeler

  • Promise<void>

    Chrome 90 veya daha yeni bir sürüm

registerContentScripts()

Chrome 96 veya daha yeni bir sürüm 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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ğrulama sırasında hatalar varsa veya belirtilen kimlikler zaten mevcutsa komut dosyaları kaydedilmez.

İadeler

  • Promise<void>

removeCSS()

Chrome 90 veya daha yeni bir sürüm 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Bu uzantı tarafından daha önce eklenmiş bir CSS stil sayfasını hedef bağlamdan 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. Mevcut olmayan bir stil sayfasını kaldırmaya çalışmak etkisiz bir işlemdir.

İadeler

  • Promise<void>

unregisterContentScripts()

Chrome 96 veya daha yeni bir sürüm 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Bu uzantının içerik komut dosyalarının kaydını siler.

Parametreler

  • filtrele

    ContentScriptFilter isteğe bağlı

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

İadeler

  • Promise<void>

updateContentScripts()

Chrome 96 veya daha yeni bir sürüm 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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 belirtilmişse mevcut komut dosyası için güncellenir. Komut dosyası ayrıştırma/dosya doğrulama sırasında hatalar varsa veya belirtilen kimlikler tam olarak kaydedilmiş bir komut dosyasına karşılık gelmiyorsa hiçbir komut dosyası güncellenmez.

İadeler

  • Promise<void>