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

chrome.userScripts API'yi 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 parçasıdır. Komut dosyaları kullanıcılar tarafından oluşturulur veya bir komut dosyası deposundan ya da kullanıcı komut dosyası uzantısından indirilir.

Uzantı kullanıcıları için geliştirici modu

Uzantıların geliştiricisi olarak, Chrome yüklemenizde Geliştirici modu zaten etkindir. Kullanıcı komut dosyası uzantılarında, kullanıcılarınızın geliştirici modunu da etkinleştirmesi gerekir. Kendi dokümanlarınıza kopyalayıp yapıştırabileceğiniz talimatlar aşağıda verilmiştir.

  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.

    Uzantılar sayfası

    Uzantılar sayfası (chrome://extensions)

chrome.userScripts işlevinin hata atıp atmadığını 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;
  }
}

İ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 bu sayfalar ile 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 içinde çalışacağı 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.

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 ekleneceğ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`.

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.

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.

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.

  • geri çağırma

    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ürle çö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.

  • geri çağırma

    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ürle çö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.

  • geri çağırma

    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ürle çözülür.

unregister()

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

Bu uzantı için dinamik olarak kayıtlı 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.

  • geri çağırma

    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ürle çö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 mevcut komut dosyası için bu nesnede belirtilmişse 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.

  • geri çağırma

    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ürle çözülür.