Chrome artık standartlaştırılmış browser.* ad alanını destekliyor (Chrome 148'den itibaren kullanılabilir). Dokümanları kademeli olarak güncelliyoruz. Daha fazla bilgi için geçiş kılavuzumuzu inceleyin.

Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

browser.scripting

Açıklama

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

İzinler

scripting

Kullanılabilirlik

Chrome 88 ve sonraki sürümler Chrome 148'den itibaren browser.* MV3 ve sonraki sürümler

Manifest

browser.scripting API'yi kullanmak için manifest dosyasında "scripting" iznini ve komut dosyalarının yerleştirileceği sayfalar için ana makine izinlerini beyan edin. "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

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

Enjeksiyon hedefleri

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

Zorunlu olan tek alan tabId alanıdır. Varsayılan olarak, ekleme işlemi belirtilen sekmenin ana çerçevesinde çalışır.

function getTabId() { ... }

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

Belirtilen sekmenin tüm çerçevelerinde çalıştırmak için allFrames boole değerini true olarak ayarlayabilirsiniz.

function getTabId() { ... }

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

Ayrıca, tek tek kare kimliklerini belirterek bir sekmenin belirli karelerine de ekleme yapabilirsiniz. Kare kimlikleri hakkında daha fazla bilgi için browser.webNavigation API'ye bakın.

function getTabId() { ... }

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

Not: Hem "frameIds" hem de "allFrames" özelliklerini belirtemezsiniz.

Yerleştirilen 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 diziniyle ilgili yollar olan dizeler olarak belirtilir. Aşağıdaki kod, script.js dosyasını sekmenin ana çerçevesine yerleştirir.

function getTabId() { ... }

browser.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; }

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

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

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

browser.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;
}

browser.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 dize yürütemezsiniz.

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

browser.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. Kare başına tek bir sonuç eklenir. Ana karenin, sonuç dizisindeki ilk dizin olması garanti edilir. Diğer tüm kareler, belirleyici olmayan bir sıradadır.

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

browser.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.

Vaatler

Komut dosyası yürütme işleminin sonuç değeri bir promise ise Chrome, promise'in tamamlanması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;
}

browser.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ı iptal eden bir işlev içerir.

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

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

Türler

ContentScriptFilter

Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

Ö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

string isteğe bağlı

Eklenecek CSS'yi içeren bir dize. files ve css değerlerinden yalnızca biri belirtilmelidir.
dosyalar

string[] isteğe bağlı

Eklenecek CSS dosyalarının uzantının kök dizinine göre yolu. files ve css değerlerinden yalnızca biri belirtilmelidir.
kaynak

StyleOrigin isteğe bağlı

Yerleştirme için stil kaynağı. Varsayılan değer: 'AUTHOR'.
target

InjectionTarget

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

ExecutionWorld

Chrome 95 ve sonraki sürümler Chrome 148'den itibaren browser.*

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

Enum

"ISOLATED"
Bu uzantıya özgü yürütme ortamı olan yalıtılmış dünyayı belirtir.

"MAIN"
Ana sayfanın JavaScript'iyle 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 Chrome 148'den itibaren browser.*

Enjeksiyonla ilişkili belge.
frameId

sayı

Chrome 90 ve sonraki sürümler Chrome 148'den itibaren browser.*

Yerleştirmeyle ilişkili çerçeve.
sonuç

isteğe bağlı

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

InjectionTarget

Özellikler

allFrames

boole isteğe bağlı

Komut dosyasının sekmedeki tüm çerçevelere eklenip eklenmeyeceğini belirler. Varsayılan olarak "false" (yanlış) değerine ayarlıdı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 Chrome 148'den itibaren browser.*

İçerik eklenecek belirli documentId'lerin kimlikleri. frameIds ayarlanmışsa bu ayarlanmamalıdır.
frameIds

number[] isteğe bağlı

Eklenecek belirli çerçevelerin kimlikleri.
tabId

sayı

Enjekte edilecek sekmenin kimliği.

RegisteredContentScript

Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

Özellikler

allFrames

boole isteğe bağlı

"True" olarak belirtilirse sekmedeki en üst çerçeve olmasa bile tüm çerçevelere eklenir. Her çerçeve, URL'yle ilgili koşullar açısından bağımsız olarak kontrol edilir. URL'yle ilgili koşullar karşılanmazsa alt çerçevelere ekleme yapılmaz. Varsayılan olarak false değerine ayarlanır. Bu, yalnızca üst çerçevenin eşleştirildiğ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österilmeden önce bu dizide göründükleri sırayla eklenir.
excludeMatches

string[] isteğe bağlı

Bu içerik komut dosyasının aksi takdirde 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 önek 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 eklenir.
matchOriginAsFallback

boole isteğe bağlı

Chrome 119 ve sonraki sürümler Chrome 148'den itibaren browser.*

Komut dosyasının, URL'nin desteklenmeyen bir şema (özellikle about:, data:, blob: veya filesystem:) içerdiği çerçevelere yerleştirilip yerleştirilemeyeceğini belirtir. Bu durumlarda, komut dosyasının eklenip eklenmeyeceğini belirlemek için URL'nin kaynağı kontrol edilir. Kaynak null ise (data: URL'lerinde olduğu gibi) kullanılan kaynak, geçerli ç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 yerleştirileceğ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

boole 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 şeklindedir.
dünya

ExecutionWorld isteğe bağlı

Chrome 102 ve sonraki sürümler Chrome 148'den itibaren browser.*

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

ScriptInjection

Özellikler

args

any[] isteğe bağlı

Chrome 92+ Chrome 148'den itibaren browser.*

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 olarak 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. files veya func özelliklerinden yalnızca biri belirtilmelidir.
injectImmediately

boole isteğe bağlı

Chrome 102 ve sonraki sürümler Chrome 148'den itibaren browser.*

Enjeksiyonun hedefte mümkün olan en kısa sürede tetiklenip tetiklenmeyeceği. Komut dosyası hedefe ulaştığında sayfa zaten yüklenmiş olabileceğinden, ekleme işleminin sayfa yüklenmeden önce gerçekleşeceğinin garanti edilmediğini unutmayın.
target

InjectionTarget

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 Chrome 148'den itibaren browser.*

Komut dosyasının çalıştırılacağı JavaScript "dünyası". Varsayılan değer: ISOLATED.
func

void isteğe bağlı

Chrome 92+ Chrome 148'den itibaren browser.*

Eklenecek JavaScript işlevi. Bu işlev serileştirilir ve ardından ekleme için serileştirme kaldırılır. Bu, bağlı parametrelerin ve yürütme bağlamının kaybolacağı anlamına gelir. files veya func özelliklerinden yalnızca biri belirtilmelidir.

func işlevi şu şekildedir:
```
() => {...}
```

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()

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

Hedef bağlama bir komut dosyası ekler. Varsayılan olarak komut dosyası document_idle tarihinde veya sayfa zaten yüklüyse 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 promise olarak değerlendirilirse tarayıcı, promise'in çözülmesini bekler ve sonuç değerini döndürür.

Parametreler

enjeksiyon

ScriptInjection

Eklenecek komut dosyasının ayrıntıları.

İadeler

Promise<InjectionResult[]>

Chrome 90 ve sonraki sürümler Chrome 148'den itibaren browser.*

Yerleştirme işlemi tamamlandığında çözümlenen bir Promise döndürür. Elde edilen dizi, yerleştirmenin başarılı olduğu her kare için yürütme sonucunu içerir.

getRegisteredContentScripts()

Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

browser.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

Parametreler

filtre

ContentScriptFilter isteğe bağlı

Uzantının dinamik olarak kaydedilen komut dosyalarını filtreleyecek bir nesne.

İadeler

Promise<RegisteredContentScript[]>

insertCSS()

browser.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 ve sonraki sürümler Chrome 148'den itibaren browser.*

Ekleme işlemi tamamlandığında çözümlenen bir Promise döndürür.

registerContentScripts()

Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

browser.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 hata varsa veya belirtilen kimlikler zaten mevcutsa hiçbir komut dosyası kaydedilmez.

İadeler

Promise<void>

Komut dosyaları tamamen kaydedildikten sonra çözümlenen veya bir hata oluşursa reddedilen bir Promise döndürür.

removeCSS()

Chrome 90 ve sonraki sürümler Chrome 148'den itibaren browser.*

browser.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

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. Mevcut olmayan bir stil sayfasını kaldırmaya çalışmak işlem yapılmamasına neden olur.

İadeler

Promise<void>

Kaldırma işlemi tamamlandığında çözümlenen bir Promise döndürür.

unregisterContentScripts()

Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

browser.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Bu uzantının içerik komut dosyalarının kaydını iptal eder.

Parametreler

filtre

ContentScriptFilter isteğe bağlı

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

İadeler

Promise<void>

Komut dosyalarının kaydı iptal edildikten sonra çözümlenen veya hata oluşursa reddedilen bir Promise döndürür.

updateContentScripts()

Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*

browser.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 hata oluşursa veya belirtilen kimlikler tam olarak kayıtlı bir komut dosyasına karşılık gelmiyorsa hiçbir komut dosyası güncellenmez.

İadeler

Promise<void>

Komut dosyaları güncellendikten sonra çözümlenen veya hata oluşursa reddedilen bir Promise döndürür.

browser.scripting Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

Açıklama

İzinler

Kullanılabilirlik

Manifest

Kavramlar ve kullanım

Enjeksiyon hedefleri

Yerleştirilen kod

Dosyalar

Çalışma zamanı işlevleri

Çalışma zamanı dizeleri

Sonuçları işleme

Vaatler

Örnekler

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

Türler

ContentScriptFilter

Özellikler

CSSInjection

Özellikler

ExecutionWorld

Enum

InjectionResult

Özellikler

InjectionTarget

Özellikler

RegisteredContentScript

Özellikler

ScriptInjection

Özellikler

StyleOrigin

Enum

Yöntemler

executeScript()

Parametreler

İadeler

getRegisteredContentScripts()

Parametreler

İadeler

insertCSS()

Parametreler

İadeler

registerContentScripts()

Parametreler

İadeler

removeCSS()

Parametreler

İadeler

unregisterContentScripts()

Parametreler

İadeler

updateContentScripts()

Parametreler

İadeler

browser.scripting