Açıklama
Kullanıcı komut dosyalarını Kullanıcı Komut Dosyaları bağlamında yürütmek için userScripts
API'yi kullanın.
İzinler
userScripts
chrome.userScripts
API'yi kullanmak için manifest.json dosyanıza "userScripts"
iznini, komut dosyalarını çalıştırmak istediğiniz siteler için de "host_permissions"
iznini ekleyin.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
Kullanılabildiği yerler
Kavramlar ve kullanım
Kullanıcı komut dosyası, bir web sayfasının görünümünü veya davranışını değiştirmek için sayfaya yerleştirilen bir koddur. Komut dosyaları kullanıcılar tarafından oluşturulur veya bir komut dosyası deposundan veya bir kullanıcı komut dosyası uzantısından indirilir.
Uzantı kullanıcıları için geliştirici modu
Bir uzantı geliştiricisi olarak, Chrome yüklemenizde Geliştirici modunu zaten etkinleştiriyorsunuz. Kullanıcı komut dosyası uzantıları için kullanıcılarınızın geliştirici modunu da etkinleştirmesi gerekir. Kopyalayıp kendi dokümanlarınıza yapıştırabileceğiniz talimatları aşağıda bulabilirsiniz.
- Yeni bir sekmeye
chrome://extensions
yazarak Uzantılar sayfasına gidin. (Tasarım gereğichrome://
URL'leri bağlanabilir değildir.) Geliştirici modu'nun yanındaki açma/kapatma düğmesini tıklayarak Geliştirici Modu'nu etkinleştirin.
chrome.userScripts
uygulamasının hata verip vermediğini kontrol ederek geliştirici modunun etkin olup olmadığını belirleyebilirsiniz. Örneğin:
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
Yalnız dünyalarda çalışın
Hem kullanıcı hem de içerik komut dosyaları izole bir dünyada veya ana dünyada çalışabilir. Yalıtılmış bir dünya, bir ana makine sayfası veya diğer uzantılar tarafından erişilemeyen bir yürütme ortamıdır. Bu, bir kullanıcı komut dosyasının, ana makine sayfasını veya diğer uzantıların kullanıcı ve içerik komut dosyalarını etkilemeden JavaScript ortamını değiştirmesine olanak tanır. Bunun aksine, kullanıcı komut dosyaları (ve içerik komut dosyaları) ana makine sayfasına veya diğer uzantıların kullanıcı ve içerik komut dosyaları tarafından görülemez. Ana dünyada çalışan komut dosyalarına, ana makine sayfaları ve diğer uzantılar tarafından erişilebilir. Barındırılan sayfalar ve diğer uzantılar da bu komut dosyalarını görebilir. Dünyayı seçmek için userScripts.register()
numaralı telefonu ararken "USER_SCRIPT"
veya "MAIN"
geçin.
USER_SCRIPT
dünyası için bir içerik güvenliği politikası yapılandırmak üzere userScripts.configureWorld()
numaralı telefonu arayın:
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
Mesajlaşma
İçerik komut dosyaları ve ekran dışı dokümanlarda olduğu gibi, kullanıcı komut dosyaları da mesajlaşma özelliğini kullanarak bir uzantının diğer bölümleriyle iletişim kurar (yani, runtime.sendMessage()
ve runtime.connect()
adlarını bir uzantının başka herhangi bir bölümü gibi çağırabilirler). Ancak, özel etkinlik işleyiciler kullanılarak alınırlar (yani onMessage
veya onConnect
kullanmazlar). Bu işleyiciler, runtime.onUserScriptMessage
ve runtime.onUserScriptConnect
olarak adlandırılır. Özel işleyiciler, daha az güvenilen bir bağlam olan kullanıcı komut dosyalarından gelen iletilerin tanımlanmasını kolaylaştırır.
Bir ileti göndermeden önce, messaging
bağımsız değişkeni true
olarak ayarlanmış şekilde configureWorld()
yöntemini çağırmanız gerekir. csp
ve messaging
bağımsız değişkenlerinin aynı anda aktarılabileceğini unutmayın.
chrome.userScripts.configureWorld({
messaging: true
});
Uzantı güncellemeleri
Bir uzantı güncellendiğinde kullanıcı komut dosyaları temizlenir. Uzantı hizmet çalışanındaki runtime.onInstalled
etkinlik işleyicide kod çalıştırarak bunları tekrar ekleyebilirsiniz. Yalnızca etkinlik geri çağırmasına iletilen "update"
nedene yanıt verin.
Örnek
Bu örnek, örnekler depomuzdaki userScript örneğinden alınmıştır.
Komut dosyası kaydedin
Aşağıdaki örnekte register()
için yapılan temel bir çağrı gösterilmektedir. İlk bağımsız değişken, kaydedilecek komut dosyalarını tanımlayan bir nesne dizisidir. Burada gösterilenden daha fazla seçenek var.
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Türler
ExecutionWorld
Kullanıcı komut dosyasının yürütüleceği JavaScript dünyası.
Enum
"MAIN"
DOM'un yürütme ortamını belirtir. DOM, ana makine sayfasının JavaScript'i ile paylaşılan yürütme ortamıdır.
"USER_SCRIPT"
Kullanıcı komut dosyalarına özel yürütme ortamını belirtir ve sayfanın İGP'sinden muaftır.
RegisteredUserScript
Özellikler
-
allFrames
boole isteğe bağlı
True (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.
-
excludeGlobs
string[] isteğe bağlı
Bu kullanıcı komut dosyasının yerleştirilmeyeceği sayfalar için joker karakter kalıplarını belirtir.
-
excludeMatches
string[] isteğe bağlı
Bu kullanıcı 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
API çağrısında belirtilen kullanıcı komut dosyasının kimliği. Bu özellik, oluşturulan komut dosyası kimlikleri için ön ek olarak ayrıldığından, "_" karakteriyle başlamamalıdır.
-
includeGlobs
string[] isteğe bağlı
Bu kullanıcı komut dosyasının yerleştirileceği sayfalar için joker karakter kalıplarını belirtir.
-
js
Eşleşen sayfalara eklenecek komut dosyası kaynaklarını tanımlayan ScriptSource nesnelerinin listesi.
-
eşleşiyor
string[] isteğe bağlı
Bu kullanıcı 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. Bu özellik, ${ref:register} için belirtilmelidir.
-
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ı
Komut dosyasının çalıştırılacağı JavaScript yürütme ortamı. Varsayılan değer:
`USER_SCRIPT`
.
ScriptSource
Özellikler
-
kod
string isteğe bağlı
Eklenecek JavaScript kodunu içeren bir dize. Tam olarak
file
veyacode
belirtilmelidir. -
file
string isteğe bağlı
Uzantının kök dizinine göre eklenecek JavaScript dosyasının yolu. Tam olarak
file
veyacode
belirtilmelidir.
UserScriptFilter
Özellikler
-
ids
string[] isteğe bağlı
getScripts
yalnızca bu listede belirtilen kimliklere sahip komut dosyalarını döndürür.
WorldProperties
Özellikler
-
gBGBM
string isteğe bağlı
Dünya genelinde geçerli CSS'yi belirtir. Varsayılan değer
`ISOLATED`
dünya csp'sidir. -
mesajlaşma
boole isteğe bağlı
Mesajlaşma API'lerinin kullanıma sunulup sunulmadığını belirtir. Varsayılan değer:
false
.
Yöntemler
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
`USER_SCRIPT`
yürütme ortamını yapılandırır.
Parametreler
-
mülkler
Kullanıcı komut dosyası dünya yapılandırmasını içerir.
-
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.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
Bu uzantı için dinamik olarak kaydedilmiş tüm kullanıcı komut dosyalarını döndürür.
Parametreler
-
filter
UserScriptFilter isteğe bağlı
Belirtilirse bu yöntem yalnızca kendisiyle eşleşen kullanıcı komut dosyalarını döndürür.
-
geri çağırma
Functions (isteğe bağlı)
callback
parametresi şu şekilde görünür:(scripts: RegisteredUserScript[]) => void
-
komut dosyaları
-
İlerlemeler
-
Promise<RegisteredUserScript[]>
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.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
Bu uzantı için bir veya daha fazla kullanıcı komut dosyası kaydeder.
Parametreler
-
komut dosyaları
Kaydedilecek kullanıcı komut dosyalarının listesini içerir.
-
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.
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
Bu uzantı için dinamik olarak kaydedilmiş tüm kullanıcı komut dosyalarının kaydını siler.
Parametreler
-
filter
UserScriptFilter isteğe bağlı
Belirtilirse bu yöntem yalnızca kendisiyle eşleşen kullanıcı komut dosyalarının kaydını iptal eder.
-
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.
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
Bu uzantı için bir veya daha fazla kullanıcı komut dosyasını günceller.
Parametreler
-
komut dosyaları
Güncellenecek kullanıcı 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.