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 sonraki sürümler MV3+

Manifest

chrome.scripting API'yi kullanmak için manifest dosyasında "scripting" iznini ve komut dosyası yerleştirileceği sayfalara ait ana makine izinlerini bildirin. "host_permissions" anahtarını 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

JavaScript ve CSS yerleştirmek için chrome.scripting API'sini kullanabilirsiniz bulabilirsiniz. Bu işlem, Google Görüntülü Reklam Ağı'ndaki içerikler için komut dosyaları'nı tıklayın. Ancak chrome.scripting ad alanı kullanıldığında uzantılar ve çalışma zamanında karar verebilir.

Yerleştirme hedefleri

JavaScript yerleştirmek veya JavaScript yerleştirmek üzere bir hedef belirtmek için target parametresini kullanabilirsiniz CSS'yi girin.

Yalnızca tabId alanının doldurulması zorunludur. Varsayılan olarak, belirtilen sekmenin ana çerçevesi

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 değerini ayarlayabilirsiniz Hedef: true.

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çeveler belirterek bir sekmenin belirli çerçevelerine de yerleştirebilirsiniz Kimlikler. Çerçeve kimlikleri hakkında daha fazla bilgi için chrome.webNavigation bölümüne bakın API.

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, eklenecek kodu harici bir dosya veya çalışma zamanı değişkeni.

Dosyalar

Dosyalar, uzantının köküne göre yollar olan dizeler olarak belirtilir dizin. Aşağıdaki kod, script.js dosyasını ana çerçevesini seçin.

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 işlevini çağıracaktır. Bu işlev, değişkeninin mevcut uzantı bağlamına uygun olduğunu unutmayın.

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

CSS'yi sayfaya yerleştiriyorsanız css mülk. Bu seçenek yalnızca scripting.insertCSS() için kullanılabilir; siz , scripting.executeScript() kullanarak bir dize yürütülemez.

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

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

Sonuçları ele alma

JavaScript yürütmenin sonuçları uzantıya iletilir. Tek sonuç dahil edilir. Ana çerçevenin sonuç dizisi; diğer tüm kareler deterministik 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 sonucunda ortaya çıkan değer bir vaat ise Chrome bekleyecektir uzlaşma ve sonuçta elde edilen değeri döndürme vaadi için ödeme yaparsınız.

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, tüm dinamik içeriğin kaydını iptal eden bir işlev içerir. komut dosyalarını da kullanabilirsiniz.

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ı örneklerinden komut dosyası örneğini yükleyin depodur.

Türler

ContentScriptFilter

Chrome 96 ve sonraki sürümler 'nı inceleyin.

Özellikler

  • kimlikler

    string[] isteğe bağlı

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

CSSInjection

Özellikler

  • css

    dize isteğe bağlı

    Yerleştirilecek CSS'yi içeren bir dize. Tam olarak files ve css belirtilmelidir.

  • dosyalar

    string[] isteğe bağlı

    Yerleştirilecek 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ı

    Eklemenin 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 'nı inceleyin.

Komut dosyasının yürütüleceği JavaScript dünyası.

Enum

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

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

InjectionResult

Özellikler

  • documentId

    dize

    Chrome 106 ve sonraki sürümler 'nı inceleyin.

    Yerleştirmeyle ilişkili doküman.

  • frameId

    sayı

    Chrome 90 ve sonraki sürümler 'nı inceleyin.

    Yerleştirmeyle ilişkilendirilen çerçeve.

  • sonuç

    isteğe bağlı herhangi bir

    Komut dosyası yürütme işleminin sonucu.

InjectionTarget

Özellikler

  • allFrames

    boole isteğe bağlı

    Komut dosyasının sekmedeki tüm karelere yerleştirilip yerleştirilmeyeceği. Varsayılan olarak yanlış değerine ayarlanır. frameIds belirtilmişse bu değer doğru olmamalıdır.

  • documentIds

    string[] isteğe bağlı

    Chrome 106 ve sonraki sürümler 'nı inceleyin.

    Eklenecek belirli documentId'lerin kimlikleri. frameIds ayarlandıysa bu ayar yapılmamalıdır.

  • frameIds

    sayı[] isteğe bağlı

    Eklenecek belirli çerçevelerin kimlikleri.

  • tabId

    sayı

    Eklenecek sekmenin kimliği.

RegisteredContentScript

Chrome 96 ve sonraki sürümler 'nı inceleyin.

Özellikler

  • allFrames

    boole isteğe bağlı

    Doğru değerine ayarlanırsa çerçeve, sekmenin en üstünde yer alan kare olmasa bile tüm karelere yerleştirilir. Her çerçeve, URL gereklilikleri 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. Bu, yalnızca üst karenin eşleştiği anlamına gelir.

  • 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 yerleştirilir.

  • excludeMatches

    string[] isteğe bağlı

    Bu içerik komut dosyasının normalde yerleştirileceği sayfalar hariç tutulur. Bu dizelerin söz dizimi hakkında daha fazla bilgi için Eşleme Kalıpları bölümüne bakın.

  • id

    dize

    API çağrısında belirtilen içerik komut dosyasının kimliği. "_" ile başlamamalıdır çünkü oluşturulan komut dosyası kimliklerine ön ek olarak ayrılır.

  • js

    string[] isteğe bağlı

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

  • matchOriginAsFallback

    boole isteğe bağlı

    Chrome 119 ve sonraki sürümler 'nı inceleyin.

    Komut dosyasının, URL'nin desteklenmeyen bir şema içerdiği çerçevelere yerleştirilip yerleştirilemeyeceğini belirtir; özel olarak: about:, data:, blob: veya filesystem:. Bu durumlarda, komut dosyasının yerleştirilip yerleştirilmemesi gerektiğ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 çerçeve veya bu çerçevede gezinmeyi başlatan çerçeve olur. 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 dizimi hakkında daha fazla bilgi için Eşleme 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 değer, doğru değeridir.

  • 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ünya

    ExecutionWorld isteğe bağlı

    Chrome 102 ve sonraki sürümler 'nı inceleyin.

    JavaScript "dünya" komutunu girin. Varsayılan olarak ISOLATED değerine ayarlanır.

ScriptInjection

Özellikler

  • bağımsız değişkenler

    herhangi[] isteğe bağlı

    Chrome 92 ve sonraki sürümler 'nı inceleyin.

    Sağlanan işleve aktarılacak bağımsız değişkenler. Bu yalnızca func parametresi belirtilmişse geçerlidir. Bu bağımsız değişkenler JSON'da seri haline getirilebilir olmalıdır.

  • dosyalar

    string[] isteğe bağlı

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

  • injectImmediately

    boole isteğe bağlı

    Chrome 102 ve sonraki sürümler 'nı inceleyin.

    Yerleştirmenin hedefte mümkün olan en kısa sürede tetiklenip tetiklenmeyeceğini belirtir. Sayfa, komut dosyası hedefe ulaştığında sayfa yüklenmiş olabileceğinden bunun, ekleme işleminin sayfa yüklenmeden önce gerçekleşeceğini garanti etmediğini unutmayın.

  • Komut dosyasının yerleştirileceği hedefi belirten ayrıntılar.

  • dünya

    ExecutionWorld isteğe bağlı

    Chrome 95 ve sonraki sürümler 'nı inceleyin.

    JavaScript "dünya" komutunu girin. Varsayılan olarak ISOLATED değerine ayarlanır.

  • func

    geçersiz isteğe bağlı

    Chrome 92 ve sonraki sürümler 'nı inceleyin.

    Yerleştirilecek JavaScript işlevi. Bu işlev seri hale getirilecek ve daha sonra ekleme 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 bir files veya func belirtilmelidir.

    func işlevi aşağıdaki gibi görünür: 

    () => {...}

StyleOrigin

Stil değişikliğinin kaynağı. Daha fazla bilgi için stil başlangıç noktalarını inceleyin.

Enum

"AUTHOR"

"KULLANICI"

Yöntemler

executeScript()

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

Hedef bağlama komut dosyası ekler. Komut dosyası varsayılan olarak document_idle itibarıyla veya sayfa zaten yüklendiyse hemen çalıştırılır. injectImmediately özelliği ayarlanırsa sayfanın yüklenmesi tamamlanmamış olsa bile komut dosyası, beklemeden yerleştirilir. Komut dosyası bir vaat olarak değerlendirilirse tarayıcı sözün tamamlanmasını bekler ve sonuçta elde edilen değeri döndürür.

Parametreler

İadeler

  • Promise<InjectionResult[]>

    Chrome 90 ve sonraki sürümler 'nı inceleyin.

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

getRegisteredContentScripts()

Söz Chrome 96 ve sonraki 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

İadeler

  • Promise<RegisteredContentScript[]>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

insertCSS()

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

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

Parametreler

  • enjeksiyon

    CSSInjection

    Eklenecek stillerin ayrıntıları.

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Chrome 90 ve sonraki sürümler 'nı inceleyin.

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

registerContentScripts()

Söz Chrome 96 ve sonraki 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 hata oluşursa veya belirtilen kimlikler zaten mevcutsa hiçbir komut dosyası kaydedilmez.

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

removeCSS()

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

Daha önce bu uzantı tarafından eklenen 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. Var olmayan bir stil sayfasını kaldırma girişimi bir işlem değildir.

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

unregisterContentScripts()

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

Bu uzantı için 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ını iptal eder. Aksi takdirde, uzantının tüm dinamik içerik komut dosyalarının kaydı iptal edilir.

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

updateContentScripts()

Söz Chrome 96 ve sonraki 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 belirtilmişse mevcut komut dosyası için güncellenir. Komut dosyası ayrıştırma/dosya doğrulaması sırasında hata oluşursa veya belirtilen kimlikler tam olarak kaydedilmiş bir komut dosyasına karşılık gelmiyorsa hiçbir komut dosyası güncellenmez.

  • geri çağırma

    işlev isteğe bağlı

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

    () => void

İadeler

  • Taahhüt<void>

    Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.