Açıklama
Komut dosyasını farklı bağlamlarda yürütmek için chrome.scripting
API'yi kullanın.
İzinler
scripting
Kullanılabilirlik
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
Ö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
vecss
belirtilmelidir. -
dosyalar
string[] isteğe bağlı
Eklenecek CSS dosyalarının, uzantının kök dizinine göre yolu. Tam olarak
files
vecss
belirtilmelidir. -
kaynak
StyleOrigin isteğe bağlı
Ekleme için stil kaynağı. Varsayılan olarak
'AUTHOR'
değerine ayarlanır. -
hedef
CSS'nin ekleneceği hedefi belirten ayrıntılar.
ExecutionWorld
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ümlerYerleştirmeyle ilişkili belge.
-
frameId
sayı
Chrome 90 ve sonraki sürümlerEklemeyle 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ümlerEklenecek 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
Ö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ümlerKomut 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ümlerKomut 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ümlerSağ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
veyafunc
belirtilmelidir. -
injectImmediately
boole isteğe bağlı
Chrome 102 ve sonraki sürümlerEklemenin 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.
-
hedef
Komut dosyasının ekleneceği hedefi belirten ayrıntılar.
-
ulusal
ExecutionWorld isteğe bağlı
Chrome 95 ve sonraki sürümlerKomut 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ümlerEklenecek 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
veyafunc
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()
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
-
enjeksiyon
Eklenecek komut dosyasının ayrıntıları.
-
geri çağırma
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:(results: InjectionResult[]) => void
-
sonuç
-
İlerlemeler
-
Promise<InjectionResult[]>
Chrome 90 ve sonraki sürümlerVaatler, 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()
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
-
filter
ContentScriptFilter isteğe bağlı
Uzantının dinamik olarak kaydedilen komut dosyalarını filtreleyecek bir nesne.
-
geri çağırma
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:(scripts: RegisteredContentScript[]) => void
-
komut dosyaları
-
İlerlemeler
-
Promise<RegisteredContentScript[]>
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()
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
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ümlerVaatler, 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()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Bu uzantı için bir veya daha fazla içerik komut dosyası kaydeder.
Parametreler
-
komut dosyaları
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()
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
Kaldırılacak stillerin ayrıntıları.
css
,files
veorigin
ö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()
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()
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ı
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.