chrome.userScripts

Açıklama

Kullanıcı komut dosyalarını User Scripts bağlamında yürütmek için userScripts API'yi kullanın.

İzinler

userScripts

Kullanıcı Komut Dosyaları API'sini chrome.userScripts kullanmak için manifest.json dosyanıza "userScripts" iznini ve komut dosyası ç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

Chrome 120+ MV3+

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 kod snippet'idir. İçerik Komut Dosyaları ve chrome.scripting API gibi diğer uzantı özelliklerinin aksine, Kullanıcı Komut Dosyaları API'si istediğiniz kodu çalıştırmanıza olanak tanır. Bu API, kullanıcı tarafından sağlanan ve uzantı paketiniz kapsamında gönderilemeyen komut dosyalarını çalıştıran uzantılar için gereklidir.

userScripts API'nin kullanımını etkinleştirme

Uzantı, 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 belirli açma/kapatma düğmesi ve API'nin devre dışı bırakıldığındaki 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)

Uzantısı geliştirici olarak, Chrome yüklemenizde Geliştirici Modu zaten etkindir. Kullanıcılarınızın da Geliştirici modunu etkinleştirmesi gerekir.

Aşağıdaki talimatları kopyalayıp kullanıcılarınız için uzantınızın belgelerine yapıştırabilirsiniz.

  1. Yeni bir sekmede chrome://extensions yazarak Uzantılar sayfasına gidin. (chrome:// URL'leri tasarım gereği bağlantı oluşturmaya uygun değildir.)

  2. Geliştirici modu'nun yanındaki açma/kapatma düğmesini tıklayarak Geliştirici Modu'nu etkinleştirin.

    Geliştirici modu açma/kapatma düğmesinin vurgulandığı Chrome Uzantılar sayfası

    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_KIMLIGI) bulunur.

Aşağıdaki talimatları kopyalayıp kullanıcılarınıza yönelik uzantınızın belgelerine yapıştırabilirsiniz:

  1. Yeni bir sekmede chrome://extensions yazarak Uzantılar sayfasına gidin. (chrome:// URL'leri tasarım gereği bağlantı oluşturmaya uygun değildir.)
  2. Uzantıyla ilgili ayrıntılı bilgileri görüntülemek için uzantı kartındaki "Ayrıntılar" düğmesini tıklayın.
  3. Kullanıcı Komut Dosyalarına İzin Ver'in yanındaki açma/kapatma düğmesini tıklayın.
Uzantı ayrıntıları sayfasındaki Kullanıcı Komut Dosyalarına İzin Ver düğmesi
Kullanıcı Komut Dosyaları'na İzin Ver düğmesi (chrome://extensions/?id=abc...)

API'nin kullanılabilir olup olmadığını kontrol etme

Tüm Chrome sürümlerinde çalıştığından, userScripts API'nin etkin olup olmadığını belirlemek için aşağıdaki kontrolü yapmanızı öneririz. Bu kontrol, API kullanılabilir olduğunda her zaman başarılı olması gereken bir chrome.userScripts() yöntemini çağırmayı dener. Bu çağrı bir hata verirse API kullanılamaz:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

İzole edilmiş dünyalarda çalışma

Hem kullanıcı hem de içerik komut dosyaları, izole bir dünyada veya ana dünyada çalışabilir. İzole dünya, barındıran sayfanın veya diğer uzantıların erişemediği bir yürütme ortamıdır. Bu sayede 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. Buna karşılık, 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ı, ana sayfalar ve diğer uzantılar tarafından erişilebilir ve ana 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 içerik güvenliği politikası yapılandırmak üzere userScripts.configureWorld()'i 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 uzantının diğer bölümleri gibi runtime.sendMessage() ve runtime.connect()'i çağırabilir). Ancak bu etkinlikler özel etkinlik işleyicileri kullanılarak alınır (yani onMessage veya onConnect kullanılmaz). Bu işleyiciler runtime.onUserScriptMessage ve runtime.onUserScriptConnect olarak adlandırılır. Özel işleyiciler, daha az güvenilir bir bağlam olan kullanıcı komut dosyalarından gelen iletileri tanımlamayı kolaylaştırır.

Mesaj göndermeden önce messaging bağımsız değişkeni true olarak ayarlanmış şekilde configureWorld() işlevini ç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

Bir uzantı güncellendiğinde kullanıcı komut dosyaları temizlenir. Uzatma hizmet işçisindeki 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, örnekler depomuzda bulunan userScript örneğinden alınmıştır.

Komut dosyası kaydetme

Aşağıdaki örnekte register() çağrısı 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.

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. Bu, ana sayfanın JavaScript'iyle paylaşılan yürütme ortamıdır.

"USER_SCRIPT"
Kullanıcı komut dosyalarına özgü olan ve sayfanın CSP'sinden muaf olan yürütme ortamını belirtir.

InjectionResult

Chrome 135 ve üzeri sürümler

Özellikler

  • documentId

    dize

    Enjeksiyonla ilişkili doküman.

  • hata

    dize isteğe bağlı

    Hata (varsa). error ve result birlikte kullanılamaz.

  • frameId

    sayı

    Enjeksiyonla ilişkili çerçeve.

  • sonuç

    herhangi bir isteğe bağlı

    Komut dosyası yürütmenin sonucu.

InjectionTarget

Chrome 135 ve üzeri sürümler

Özellikler

  • allFrames

    boole isteğe bağlı

    Komut dosyasının sekmedeki tüm çerçevelere eklenip eklenmeyeceği. Varsayılan değer yanlıştır. frameIds belirtilmişse bu doğru olmamalıdır.

  • documentIds

    string[] isteğe bağlı

    Eklenecek belirli doküman kimliklerinin kimlikleri. frameIds ayarlandıysa bu ayarlanmamalıdır.

  • frameIds

    number[] isteğe bağlı

    Eklenecek belirli karelerin kimlikleri.

  • tabId

    sayı

    İçeriğin ekleneceği sekmenin kimliği.

RegisteredUserScript

Özellikler

  • allFrames

    boole isteğe bağlı

    Bu değer doğru ise, çerçeve sekmedeki en üstteki çerçeve olmasa bile tüm çerçevelere eklenir. Her çerçeve, URL koşulları açısından bağımsız olarak kontrol edilir. URL koşulları karşılanmıyorsa alt çerçevelere eklenmez. Varsayılan olarak yanlış değerini alır. Bu, yalnızca üst çerçevenin 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 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ı başlıklı makaleyi inceleyin.

  • id

    dize

    API çağrısında belirtilen kullanıcı komut dosyasının kimliği. Oluşturulan komut dosyası kimlikleri için ön ek olarak ayrıldığı için bu özellik "_" 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 ekleneceğini belirtir. Bu dizelerin söz dizimi hakkında daha fazla bilgi için Eşleşme Kalıpları başlıklı makaleyi inceleyin. 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. Tercih edilen ve varsayılan değer document_idle'tür.

  • 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

    dize isteğe bağlı

    Chrome 133 ve sonraki sürümler

    Çalıştırılacağı 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 world atlanmışsa veya USER_SCRIPT ise geçerlidir. Başında alt çizgi (_) olan değerler ayrılmıştır.

ScriptSource

Özellikler

  • kod

    dize isteğe bağlı

    Yerleştirilecek JavaScript kodunu içeren bir dize. file veya code özelliklerinden tam olarak biri belirtilmelidir.

  • dosya

    dize isteğe bağlı

    Eklenecek JavaScript dosyasının, uzantının kök dizine göre yolu. file veya code özelliklerinden tam olarak biri belirtilmelidir.

UserScriptFilter

Özellikler

  • kimlikler

    string[] isteğe bağlı

    getScripts yalnızca bu listede belirtilen kimliklere sahip komut dosyalarını döndürür.

UserScriptInjection

Chrome 135 ve üzeri sürümler

Özellikler

  • injectImmediately

    boole isteğe bağlı

    Enjeksiyonun hedefte en kısa sürede tetiklenmesi gerekip gerekmediği. Komut dosyası hedefe ulaştığında sayfa zaten yüklenmiş olabileceğinden, bunun sayfa yüklenmeden önce enjeksiyon yapılacağı anlamına gelmediğini unutmayın.

  • Hedefe yerleştirilecek komut dosyalarının kaynaklarını tanımlayan ScriptSource nesnelerinin listesi.

  • Komut dosyasının yerleştirileceği hedefi belirten ayrıntılar.

  • dünya

    ExecutionWorld isteğe bağlı

    Komut dosyasının çalışacağı JavaScript "dünyası". Varsayılan değer: USER_SCRIPT.

  • worldId

    dize isteğe bağlı

    Çalıştırılacağı 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 world atlanmışsa veya USER_SCRIPT ise geçerlidir. Başında alt çizgi (_) olan değerler ayrılmıştır.

WorldProperties

Özellikler

  • csp

    dize isteğe bağlı

    Dünya csp'sini belirtir. Varsayılan ayar, `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.

  • worldId

    dize isteğe bağlı

    Chrome 133 ve üzeri sürümler

    Güncellenecek belirli kullanıcı komut dosyası dünyasının kimliğini belirtir. Belirtilmemişse varsayılan kullanıcı komut dosyası dünyasının özelliklerini günceller. Başında alt çizgi (_) olan değerler ayrılmıştır.

Yöntemler

configureWorld()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

`USER_SCRIPT` yürütme ortamını yapılandırır.

Parametreler

  • mülkler

    WorldProperties

    Kullanıcı komut dosyası dünya yapılandırmasını içerir.

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

execute()

Promise Chrome 135 ve üzeri sürümler 
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

Hedef bir bağlama komut dosyası ekler. Komut dosyası varsayılan olarak document_idle'te veya sayfa zaten yüklendiyse hemen çalıştırılır. injectImmediately mülkü ayarlanmışsa sayfanın yüklenmesi tamamlanmamış olsa bile komut dosyası beklemeden eklenir. Komut dosyası bir promise olarak değerlendirilirse tarayıcı, promise'in karar vermesini ve ortaya çıkan değeri döndürmesini bekler.

Parametreler

İadeler

  • Promise<InjectionResult[]>

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

getScripts()

Promise 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Bu uzantı için dinamik olarak kayıtlı tüm kullanıcı komut dosyalarını döndürür.

Parametreler

  • filtrele

    UserScriptFilter isteğe bağlı

    Belirtilen bu yöntem yalnızca eşleşen kullanıcı komut dosyalarını döndürür.

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (scripts: RegisteredUserScript[]) => void

İadeler

  • Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

getWorldConfigurations()

Promise Chrome 133 ve üzeri sürümler 
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Kayıtlı tüm dünya yapılandırmalarını alır.

Parametreler

İadeler

  • Promise<WorldProperties[]>

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

register()

Promise 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Bu uzantı için bir veya daha fazla kullanıcı komut dosyası kaydeder.

Parametreler

  • komut dosyaları

    RegisteredUserScript[]

    Kayıt edilecek kullanıcı komut dosyalarının listesini içerir.

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

resetWorldConfiguration()

Promise Chrome 133 ve üzeri sürümler 
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Bir kullanıcı komut dosyası dünyasının yapılandırmasını sıfırlar. Dünyaya belirtilen kimlikle enjekte edilen tüm komut dosyaları varsayılan dünya yapılandırmasını kullanır.

Parametreler

  • worldId

    dize isteğe bağlı

    Sıfırlanacak kullanıcı komut dosyası dünyasının kimliği. Boş bırakılırsa varsayılan dünyanın yapılandırması sıfırlanır.

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

unregister()

Promise 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Bu uzantı için dinamik olarak kaydedilen tüm kullanıcı komut dosyalarının kaydını siler.

Parametreler

  • filtrele

    UserScriptFilter isteğe bağlı

    Belirtilen bu yöntem, yalnızca eşleşen kullanıcı komut dosyalarının kaydını siler.

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.

update()

Promise 
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ı

    RegisteredUserScript[]

    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 tamamen kayıtlı bir komut dosyasına karşılık gelmiyorsa hiçbir komut dosyası güncellenmez.

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Sözler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırma işlevleri sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Sözleşme, geri çağırma işlevine iletilen türün aynısıyla çözülür.