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 ise "host_permissions"
iznini ekleyin.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
Kullanılabilirlik
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 komut dosyası deposundan ya da 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ştirmişsinizdir. Kullanıcı komut dosyası uzantıları için kullanıcılarınızın geliştirici modunu da etkinleştirmesi gerekir. Aşağıda verilen talimatları kopyalayıp kendi dokümanlarınıza yapıştırabilirsiniz.
- Yeni bir sekmeye
chrome://extensions
yazarak Uzantılar sayfasına gidin. (Tasarımı gereğichrome://
URL'ler bağlanamaz.) Geliştirici modu'nun yanındaki açma/kapatma düğmesini tıklayarak Geliştirici Modu'nu etkinleştirin.
Uzantılar sayfası (chrome://extensions) 'nı inceleyin.
chrome.userScripts
ürününün hata verip vermediğini kontrol ederek geliştirici modunun etkinleştirilip etkinleştirilmediğini 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;
}
}
Issı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ış dünya, bir ana makine sayfasının veya diğer uzantıların erişemeyeceği yürütme ortamıdır. Bu, bir kullanıcı komut dosyasının ana makine sayfasını veya diğer uzantıları etkilemeden JavaScript ortamını değiştirmesine olanak tanır. kullanıcı ve içerik komut dosyalarıdır. Öte yandan, kullanıcı komut dosyaları (ve içerik komut dosyaları) ana makine sayfasına ya da diğer uzantıların kullanıcı ve içerik komut dosyaları tarafından görülemez. Ana ortamda çalışan komut dosyaları, sayfaları ve diğer uzantıları barındırmak için erişilebilir durumdadır ve ana sayfalar ile diğer uzantılar tarafından görülebilir. Dünyayı seçmek için userScripts.register()
araması yaparken "USER_SCRIPT"
veya "MAIN"
verin.
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ümanlar gibi, kullanıcı komut dosyaları da mesajlaşma özelliğini kullanarak uzantının diğer bölümleriyle iletişim kurar (yani bir uzantının diğer herhangi bir bölümünde olduğu gibi runtime.sendMessage()
ve runtime.connect()
ç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 iletileri tanımlamayı kolaylaştırır.
İleti göndermeden önce, messaging
bağımsız değişkeni true
olarak ayarlanmış şekilde configureWorld()
numaralı telefonu çağırmanız gerekir. Hem csp
hem de messaging
bağımsız değişkenlerinin aynı anda iletilebileceğini unutmayın.
chrome.userScripts.configureWorld({
messaging: true
});
Uzantı güncellemeleri
Kullanıcı komut dosyaları, uzantı güncellendiğinde temizlenir. Uzantı hizmeti çalışanındaki runtime.onInstalled
etkinlik işleyicisinde kod çalıştırarak bunları tekrar ekleyebilirsiniz. Yalnızca etkinlik geri çağırmasına iletilen "update"
nedeni ile ilgili yanıt verin.
Örnek
Bu örnek, örnek 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 içinde yürütülebileceği JavaScript dünyası.
Enum
"MAIN"
Ana makine sayfasının JavaScript'i ile paylaşılan yürütme ortamı olan DOM'un yürütme ortamını belirtir.
"USER_SCRIPT"
Kullanıcı komut dosyalarına özel olan ve sayfanın İGP'sinden muaf olan yürütme ortamını belirtir.
RegisteredUserScript
Özellikler
-
allFrames
boole isteğe bağlı
True (doğru) değerine ayarlanırsa, kare 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.
-
excludeGlobs
string[] isteğe bağlı
Bu kullanıcı komut dosyasının EKLENMEYECEĞİ sayfalar için joker karakter kalıplarını belirtir.
-
excludeMatches
string[] isteğe bağlı
Bu kullanıcı 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 kullanıcı komut dosyasının kimliği. Bu özellik "_" ile başlamamalıdır çünkü oluşturulan komut dosyası kimliklerine ön ek olarak ayrılı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 ekleneceğini belirtir. Bu dizelerin söz dizimi hakkında daha fazla bilgi için Eşleme 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 yerleştirileceğini belirtir. Tercih edilen ve varsayılan değer:
document_idle
. -
dünya
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
dize isteğe bağlı
Yerleştirilecek JavaScript kodunu içeren bir dize. Tam olarak bir
file
veyacode
belirtilmelidir. -
dosya
dize isteğe bağlı
Yerleştirilecek JavaScript dosyasının, uzantının kök dizinine göre yolu. Tam olarak bir
file
veyacode
belirtilmelidir.
UserScriptFilter
Özellikler
-
kimlikler
string[] isteğe bağlı
getScripts
yalnızca bu listede belirtilen kimliklere sahip komut dosyalarını döndürür.
WorldProperties
Özellikler
-
igp
dize isteğe bağlı
Dünya genelinde csp'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
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.
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
-
filtrele
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
işlev isteğe bağlı
callback
parametresi şu şekilde görünür:(scripts: RegisteredUserScript[]) => void
-
komut dosyaları
-
İadeler
-
Promise<RegisteredUserScript[]>
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.
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
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.
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ı iptal eder.
Parametreler
-
filtrele
UserScriptFilter isteğe bağlı
Belirtilirse bu yöntem yalnızca kendisiyle eşleşen kullanıcı komut dosyalarının kaydını siler.
-
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.
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 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.