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ı (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`.

• worldId

  dize isteğe bağlı

  Beklemede

  Belirtiliyse yürütülecek belirli bir kullanıcı komut dosyası dünya kimliğini belirtir. Yalnızca world atlanmışsa veya USER_SCRIPT ise geçerlidir. Atlanırsa komut dosyası varsayılan kullanıcı komut dosyası dünyasında yürütülür. 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 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ı

  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 (_) bulunan 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ş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

  • komut dosyaları

    RegisteredUserScript[]

İadeler

• Promise<RegisteredUserScript[]>

  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.

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şlev isteğe bağlı

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

  (worlds: WorldProperties[]) => void

  • dünyalar

    WorldProperties[]

İ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ü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.

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

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