Açıklama
Kullanıcı komut dosyalarını, kullanıcı komut dosyaları bağlamında yürütmek için userScripts API'sini kullanın.
İzinler
userScriptsUser Scripts API'yi kullanmak için browser.userScripts, manifest.json dosyanıza "userScripts" iznini ve komut dosyalarını çalıştırmak istediğiniz siteler için "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ı, görünümünü veya davranışını değiştirmek için bir web sayfasına eklenen kod snippet'idir. İçerik Komut Dosyaları ve browser.scripting API gibi diğer uzantı özelliklerinin aksine, User Scripts API rastgele kod çalıştırmanıza olanak tanır. Bu API, kullanıcı tarafından sağlanan ve uzantı paketinizin bir parçası olarak gönderilemeyen komut dosyalarını çalıştıran uzantılar için gereklidir.
userScripts API'nin kullanımını etkinleştirme
Uzantınız userScripts API'yi kullanma izni aldıktan sonra kullanıcıların, uzantınızın API'yi kullanmasına izin vermek için belirli bir açma/kapatma düğmesini etkinleştirmesi gerekir. Gerekli olan açma/kapatma düğmesi ve devre dışı bırakıldığında API'nin davranışı, Chrome sürümüne göre değişir.
Kullanıcının hangi açma/kapatma düğmesini etkinleştirmesi gerektiğini belirlemek için aşağıdaki kontrolü kullanın (ör. yeni kullanıcı oryantasyonu sırasında):
let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
// Allow User Scripts toggle will be used.
} else {
// Developer mode toggle will be used.
}
Aşağıdaki bölümlerde farklı açma/kapatma düğmeleri ve bunların nasıl etkinleştirileceği açıklanmaktadır.
138'den önceki Chrome sürümleri (Geliştirici modu açma/kapatma düğmesi)
Uzantı geliştirici olarak, Chrome yüklemenizde Geliştirici modu zaten etkinleştirilmiştir. Kullanıcılarınızın da geliştirici modunu etkinleştirmesi gerekir.
Aşağıdaki talimatları kopyalayıp uzantınızın dokümanlarına yapıştırarak kullanıcılarınızla paylaşabilirsiniz.
- Yeni bir sekmede
chrome://extensionsadresini girerek Uzantılar sayfasına gidin. (Tasarım gereğichrome://URL'ye bağlantı verilemez.) Geliştirici modu'nun yanındaki açma/kapatma düğmesini tıklayarak Geliştirici Modu'nu etkinleştirin.
Uzantılar sayfası (chrome://extensions)
Chrome 138 ve sonraki sürümler (Kullanıcı Komut Dosyalarına İzin Ver düğmesi)
Kullanıcı komut dosyalarına izin ver açma/kapatma düğmesi, her uzantının ayrıntılar sayfasında (ör. chrome://extensions/?id=UZANTI_KİMLİĞİNİZ) bulunur.
Aşağıdaki talimatları kopyalayıp uzantınızın dokümanlarına yapıştırarak kullanıcılarınızla paylaşabilirsiniz:
- Yeni bir sekmede
chrome://extensionsadresini girerek Uzantılar sayfasına gidin. (Tasarım gereğichrome://URL'ye bağlantı verilemez.) - Uzantı kartındaki "Ayrıntılar" düğmesini tıklayarak uzantıyla ilgili ayrıntılı bilgileri görüntüleyebilirsiniz.
- Kullanıcı Komut Dosyalarına İzin Ver'in yanındaki açma/kapatma düğmesini tıklayın.
API'nin kullanılabilirliğini kontrol etme
userScripts API'nin etkin olup olmadığını belirlemek için aşağıdaki kontrolü yapmanızı öneririz. Bu kontrol, tüm Chrome sürümlerinde çalışır. Bu kontrol, API kullanılabilir olduğunda her zaman başarılı olması gereken bir browser.userScripts() yöntemini çağırmaya çalışır. Bu çağrı bir hata verirse API kullanılamaz:
function isUserScriptsAvailable() {
try {
// Method call which throws if API permission or toggle is not enabled.
browser.userScripts.getScripts();
return true;
} catch {
// Not available.
return false;
}
}
Yalıtılmış dünyalarda çalışma
Hem kullanıcı hem de içerik komut dosyaları, izole bir dünyada veya ana dünyada çalıştırılabilir. Yalıtılmış dünya, bir ana makine sayfası veya diğer uzantılar tarafından erişilemeyen bir yürütme ortamıdır. Bu sayede bir kullanıcı komut dosyası, ana sayfayı veya diğer uzantıların kullanıcı ve içerik komut dosyalarını etkilemeden JavaScript ortamını değiştirebilir. Bunun aksine, kullanıcı komut dosyaları (ve içerik komut dosyaları) ana makine sayfası 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 erişebilir ve bunlar ana makine sayfaları ile diğer uzantılar tarafından görülebilir. Dünyayı seçmek için userScripts.register() işlevini çağırırken "USER_SCRIPT" veya "MAIN" değerini iletin.
USER_SCRIPT dünyası için bir içerik güvenliği politikası yapılandırmak üzere userScripts.configureWorld() yöntemini çağırın:
browser.userScripts.configureWorld({
csp: "script-src 'self'"
});
Mesajlaşma
İçerik komut dosyaları ve ekran dışı dokümanlar gibi kullanıcı komut dosyaları da mesajlaşma kullanarak bir uzantının diğer bölümleriyle iletişim kurar (yani uzantının diğer bölümleri gibi runtime.sendMessage() ve runtime.connect()'yi çağırabilir). 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 mesajları tanımlamayı kolaylaştırır.
Mesaj göndermeden önce messaging bağımsız değişkeni true olarak ayarlanmış şekilde configureWorld() yöntemini çağırmanız gerekir. Hem csp hem de messaging bağımsız değişkenlerinin aynı anda iletilebileceğini unutmayın.
browser.userScripts.configureWorld({
messaging: true
});
Uzantı güncellemeleri
Uzantı güncellendiğinde kullanıcı komut dosyaları temizlenir. Uzantı hizmet çalışanındaki runtime.onInstalled etkinlik işleyicisinde kod çalıştırarak bunları tekrar ekleyebilirsiniz. Yalnızca etkinlik geri çağırma işlevine iletilen "update" nedenine yanıt verin.
Örnek
Bu örnek, örnek depomuzdaki userScript örneğinden alınmıştır.
Komut dosyası kaydetme
Aşağıdaki örnekte register() için 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 vardır.
browser.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. Bu, ana makine sayfasının JavaScript'iyle paylaşılan yürütme ortamıdır.
"USER_SCRIPT"
Kullanıcı komut dosyalarına özel olan ve sayfanın CSP'sinden muaf olan yürütme ortamını belirtir.
InjectionResult
Özellikler
-
documentId
dize
Enjeksiyonla ilişkili belge.
-
hata
string isteğe bağlı
Hata (varsa).
errorveresultaynı anda olamaz. -
frameId
sayı
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.
frameIdsbelirtilmişse bu değer doğru olmamalıdır. -
documentIds
string[] isteğe bağlı
Eklenecek belirli documentId'lerin kimlikleri.
frameIdsayarlanmışsa bu ayarlanmamalıdır. -
frameIds
number[] isteğe bağlı
Enjekte edilecek belirli karelerin kimlikleri.
-
tabId
sayı
Enjekte edilecek sekmenin kimliği.
RegisteredUserScript
Özellikler
-
allFrames
boole isteğe bağlı
Doğru ise 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.
-
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 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 kullanıcı komut dosyasının kimliği. Bu özellik, oluşturulan komut dosyası kimlikleri için önek olarak ayrıldığından "_" ile 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
ScriptSource[] isteğe bağlı
Eşleşen sayfalara yerleştirilecek komut dosyalarının kaynaklarını tanımlayan ScriptSource nesnelerinin listesi. Bu özellik ${ref:register} için belirtilmelidir ve belirtildiğinde boş olmayan bir dizi olmalıdır.
-
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 dizimi hakkında daha fazla bilgi 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 yerleştirileceğini belirtir. Tercih edilen ve varsayılan değer
document_idleşeklindedir. -
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`. -
worldId
string isteğe bağlı
Chrome 133 ve sonraki sürümler Chrome 148'den itibaren browser.*Yürütülecek kullanıcı komut dosyası dünya kimliğini belirtir. Atlanırsa komut dosyası, varsayılan kullanıcı komut dosyası dünyasında yürütülür. Yalnızca
worldatlanırsa veyaUSER_SCRIPTise geçerlidir. Alt çizgiyle (_) başlayan değerler ayrılmıştır.
ScriptSource
Özellikler
-
kod
string isteğe bağlı
Eklenecek JavaScript kodunu içeren bir dize.
fileveyacodeözelliklerinden yalnızca biri belirtilmelidir. -
dosya
string isteğe bağlı
Uzantının kök dizinine göre yerleştirilecek JavaScript dosyasının yolu.
fileveyacodeözelliklerinden yalnızca biri belirtilmelidir.
UserScriptFilter
Özellikler
-
ids
string[] isteğe bağlı
getScriptsyalnızca bu listede belirtilen kimliklere sahip komut dosyalarını döndürür.
UserScriptInjection
Özellikler
-
injectImmediately
boole isteğe bağlı
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.
-
js
Hedefe yerleştirilecek komut dosyalarının kaynaklarını tanımlayan ScriptSource nesnelerinin listesi.
-
target
Komut dosyasının yerleştirileceği hedefi belirten ayrıntılar.
-
dünya
ExecutionWorld isteğe bağlı
Komut dosyasının çalıştırılacağı JavaScript "dünyası". Varsayılan değer:
USER_SCRIPT. -
worldId
string isteğe bağlı
Yürütülecek kullanıcı komut dosyası dünya kimliğini belirtir. Atlanırsa komut dosyası, varsayılan kullanıcı komut dosyası dünyasında yürütülür. Yalnızca
worldatlanırsa veyaUSER_SCRIPTise geçerlidir. Alt çizgiyle (_) başlayan değerler ayrılmıştır.
WorldProperties
Özellikler
-
csp
string isteğe bağlı
Dünya CSP'sini belirtir. Varsayılan değer
`ISOLATED`dünya CSP'sidir. -
mesajlaşma
boole isteğe bağlı
Mesajlaşma API'lerinin gösterilip gösterilmeyeceğini belirtir. Varsayılan değer:
false. -
worldId
string isteğe bağlı
Chrome 133 ve sonraki sürümler Chrome 148'den itibaren browser.*Güncellenecek kullanıcı komut dosyası dünyasının kimliğini belirtir. Sağlanmazsa varsayılan kullanıcı komut dosyası dünyasının özelliklerini günceller. Alt çizgiyle (
_) başlayan değerler ayrılmıştır.
Yöntemler
configureWorld()
browser.userScripts.configureWorld(
properties: WorldProperties,
): Promise<void>
`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.
İadeler
-
Promise<void>
Dünya yapılandırıldıktan sonra çözümlenen Promise.
execute()
browser.userScripts.execute(
injection: UserScriptInjection,
): 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
İadeler
-
Promise<InjectionResult[]>
getScripts()
browser.userScripts.getScripts(
filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>
Bu uzantı için dinamik olarak kaydedilen tüm kullanıcı komut dosyalarını döndürür.
Parametreler
-
filtre
UserScriptFilter isteğe bağlı
Belirtilirse bu yöntem yalnızca eşleşen kullanıcı komut dosyalarını döndürür.
İadeler
-
Promise<RegisteredUserScript[]>
Kayıtlı komut dosyalarıyla çözümlenen Promise. Hata oluşursa promise reddedilir.
getWorldConfigurations()
browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>
Kayıtlı tüm dünya yapılandırmalarını alır.
İadeler
-
Promise<WorldProperties[]>
Kayıtlı dünya yapılandırmalarıyla çözümlenen Promise.
register()
browser.userScripts.register(
scripts: RegisteredUserScript[],
): Promise<void>
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.
İadeler
-
Promise<void>
Komut dosyaları tamamen kaydedildikten sonra çözümlenen Promise. Hata oluşursa promise reddedilir.
resetWorldConfiguration()
browser.userScripts.resetWorldConfiguration(
worldId?: string,
): Promise<void>
Kullanıcı komut dosyası dünyasının yapılandırmasını sıfırlar. Belirtilen kimlikle dünyaya eklenen tüm komut dosyaları varsayılan dünya yapılandırmasını kullanır.
Parametreler
-
worldId
string isteğe bağlı
Sıfırlanacak kullanıcı komut dosyası dünyasının kimliği. Atlanırsa varsayılan dünyanın yapılandırmasını sıfırlar.
İadeler
-
Promise<void>
Yapılandırma sıfırlandığında çözümlenen Promise.
unregister()
browser.userScripts.unregister(
filter?: UserScriptFilter,
): Promise<void>
Bu uzantı için dinamik olarak kaydedilen tüm kullanıcı komut dosyalarının kaydını siler.
Parametreler
-
filtre
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.
İadeler
-
Promise<void>
Komut dosyalarının kaydı tamamen iptal edildikten sonra çözümlenen Promise. Hata oluşursa promise reddedilir.
update()
browser.userScripts.update(
scripts: RegisteredUserScript[],
): Promise<void>
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ğ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ı tamamen güncellendikten sonra çözümlenen Promise. Hata oluşursa promise reddedilir.