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ının kullanılabilmesi için 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 bulabilirsiniz.

  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 makine sayfasını 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ına ana sayfalar ve diğer uzantılar erişebilir ve bu komut dosyaları ana sayfalar ve diğer uzantılar tarafından görülebilir. Dünyayı seçmek için userScripts.register()'i çağırırken "USER_SCRIPT" veya "MAIN" gönderin.

USER_SCRIPT dünyası için bir içerik güvenliği politikası yapılandırmak üzere userScripts.configureWorld() işlevini çağırı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 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()'i çağırabilir). Ancak bunlar ö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() işlevine 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 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 ortam, 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ı

    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 false (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ş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. 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ş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 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ışacağı JavaScript yürütme ortamı. Varsayılan değer: `USER_SCRIPT`.

  • worldId

    dize isteğe bağlı

    Beklemede

    Ç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.

WorldProperties

Özellikler

  • csp

    dize 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 kullanıma sunulup sunulmadığını belirtir. Varsayılan değer: false.

  • worldId

    dize isteğe bağlı

    Beklemede

    Güncellenecek belirli 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. 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.

  • geri çağırma

    işlevi 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ürde çö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şlevi 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ürde çözülür.

getWorldConfigurations()

Promise Beklemede
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

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

Parametreler

  • geri çağırma

    işlevi isteğe bağlı

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

    (worlds: WorldProperties[]) => void

İ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ürde çö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şlevi 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ürde çözülür.

resetWorldConfiguration()

Promise Beklemede
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Bir kullanıcı komut dosyası dünyasının yapılandırmasını sıfırlar. Belirtilen kimlikle dünyaya 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. Atlanırsa varsayılan dünyanın yapılandırmasını sıfırlar.

  • geri çağırma

    işlevi 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ürde çö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.

  • geri çağırma

    işlevi 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ürde çö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şlevi 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üre göre çözülür.