chrome.userScripts

Açıklama

Kullanıcı komut dosyalarını Kullanıcı Komut Dosyaları 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, komut dosyalarını çalıştırmak istediğiniz siteler için de "host_permissions" iznini ekleyin.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Kullanılabildiği yerler

Chrome 120 ve üzeri MV3 ve üzeri

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 koddur. Komut dosyaları kullanıcılar tarafından oluşturulur veya bir komut dosyası deposundan veya bir kullanıcı komut dosyası uzantısından indirilir.

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

Bir uzantı geliştiricisi olarak, Chrome yüklemenizde Geliştirici modunu zaten etkinleştiriyorsunuz. Kullanıcı komut dosyası uzantıları için kullanıcılarınızın geliştirici modunu da etkinleştirmesi gerekir. Kopyalayıp kendi dokümanlarınıza yapıştırabileceğiniz talimatları aşağıda bulabilirsiniz.

1. Yeni bir sekmeye chrome://extensions yazarak Uzantılar sayfasına gidin. (Tasarım gereği chrome:// URL'leri bağlanabilir 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 uygulamasının hata verip vermediğini 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;
  }
}

Yalnız dünyalarda çalışın

Hem kullanıcı hem de içerik komut dosyaları izole bir dünyada veya ana dünyada çalışabilir. Yalıtılmış bir dünya, bir ana makine sayfası veya diğer uzantılar tarafından erişilemeyen bir yürütme ortamıdır. Bu, bir kullanıcı komut dosyasının, ana makine sayfasını veya diğer uzantıların kullanıcı ve içerik komut dosyalarını etkilemeden JavaScript ortamını değiştirmesine olanak tanır. Bunun aksine, kullanıcı komut dosyaları (ve içerik komut dosyaları) ana makine sayfasına 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 tarafından erişilebilir. Barındırılan sayfalar ve diğer uzantılar da bu komut dosyalarını görebilir. Dünyayı seçmek için userScripts.register() numaralı telefonu ararken "USER_SCRIPT" veya "MAIN" geçin.

USER_SCRIPT dünyası için bir içerik güvenliği politikası yapılandırmak üzere userScripts.configureWorld() numaralı telefonu arayın:

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Mesajlaşma

İçerik komut dosyaları ve ekran dışı dokümanlarda olduğu gibi, kullanıcı komut dosyaları da mesajlaşma özelliğini kullanarak bir uzantının diğer bölümleriyle iletişim kurar (yani, runtime.sendMessage() ve runtime.connect() adlarını bir uzantının başka herhangi bir bölümü gibi çağırabilirler). 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 iletilerin tanımlanmasını kolaylaştırır.

Bir ileti göndermeden önce, messaging bağımsız değişkeni true olarak ayarlanmış şekilde configureWorld() yöntemini çağırmanız gerekir. csp ve messaging bağımsız değişkenlerinin aynı anda aktarılabileceğini unutmayın.

chrome.userScripts.configureWorld({
  messaging: true
});

Uzantı güncellemeleri

Bir uzantı güncellendiğinde kullanıcı komut dosyaları temizlenir. Uzantı hizmet çalışanındaki runtime.onInstalled etkinlik işleyicide kod çalıştırarak bunları tekrar ekleyebilirsiniz. Yalnızca etkinlik geri çağırmasına iletilen "update" nedene yanıt verin.

Örnek

Bu örnek, örnekler depomuzdaki userScript örneğinden alınmıştır.

Komut dosyası kaydedin

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

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. DOM, ana makine sayfasının JavaScript'i ile paylaşılan yürütme ortamıdır.

"USER_SCRIPT"
Kullanıcı komut dosyalarına özel yürütme ortamını belirtir ve sayfanın İGP'sinden muaftır.

RegisteredUserScript

Özellikler

• allFrames

  boole isteğe bağlı

  True (doğru) değerine ayarlanırsa çerçeve, sekmenin en üstündeki kare olmasa bile tüm karelere eklenir. Her çerçeve, URL gereksinimleri açısından bağımsız olarak kontrol edilir. URL gereksinimleri karşılanmazsa alt çerçevelere yerleştirilmez. Varsayılan olarak false (yanlış) değerine ayarlanır, yani yalnızca üst kare eşleştirilir.

• 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 başka bir şekilde yerleştirileceği sayfaları hariç tutar. Bu dizelerin söz dizimiyle ilgili daha fazla ayrıntı 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 ön ek olarak ayrıldığından, "_" karakteriyle 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[]

  Eşleşen sayfalara eklenecek komut dosyası kaynaklarını tanımlayan ScriptSource nesnelerinin listesi.

• 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 dizimiyle ilgili daha fazla ayrıntı 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 ekleneceğini belirtir. document_idle, tercih edilen ve varsayılan değerdir.

• ulusal

  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

  string isteğe bağlı

  Eklenecek JavaScript kodunu içeren bir dize. Tam olarak file veya code belirtilmelidir.

• file

  string isteğe bağlı

  Uzantının kök dizinine göre eklenecek JavaScript dosyasının yolu. Tam olarak file veya code belirtilmelidir.

UserScriptFilter

Özellikler

• ids

  string[] isteğe bağlı

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

WorldProperties

Özellikler

• gBGBM

  string isteğe bağlı

  Dünya genelinde geçerli CSS'yi 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.

Yöntemler

configureWorld()

Söz

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

  Functions (isteğe bağlı)

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

  ()=>void

İlerlemeler

• Promise<void>

  Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

getScripts()

Söz

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

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

Parametreler

• filter

  UserScriptFilter isteğe bağlı

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

• geri çağırma

  Functions (isteğe bağlı)

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

  (scripts: RegisteredUserScript[])=>void

  • komut dosyaları

    RegisteredUserScript[]

İlerlemeler

• Promise<RegisteredUserScript[]>

  Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

register()

Söz

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

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

Parametreler

• komut dosyaları

  RegisteredUserScript[]

  Kaydedilecek kullanıcı komut dosyalarının listesini içerir.

• geri çağırma

  Functions (isteğe bağlı)

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

  ()=>void

İlerlemeler

• Promise<void>

  Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

unregister()

Söz

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

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

Parametreler

• filter

  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.

• geri çağırma

  Functions (isteğe bağlı)

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

  ()=>void

İlerlemeler

• Promise<void>

  Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.

update()

Söz

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 belirtilmesi durumunda mevcut komut dosyası için güncellenir. Komut dosyası ayrıştırma/dosya doğrulaması sırasında hatalar varsa veya belirtilen kimlikler tam olarak kayıtlı bir komut dosyasına karşılık gelmiyorsa komut dosyası güncellenmez.

• geri çağırma

  Functions (isteğe bağlı)

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

  ()=>void

İlerlemeler

• Promise<void>

  Vaatler, Manifest V3 ve sonraki sürümlerde desteklenir ancak geriye dönük uyumluluk için geri çağırmalar sağlanır. Aynı işlev çağrısında ikisini birden kullanamazsınız. Vaat, geri çağırmaya iletilen aynı türle çözümlenir.