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 ise "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 ve sonraki sürümler 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 koddur. Komut dosyaları, kullanıcılar tarafından oluşturulur veya komut dosyası deposundan ya da 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ştirmişsinizdir. Kullanıcı komut dosyası uzantıları için kullanıcılarınızın geliştirici modunu da etkinleştirmesi gerekir. Aşağıda verilen talimatları kopyalayıp kendi dokümanlarınıza yapıştırabilirsiniz.

1. Yeni bir sekmeye chrome://extensions yazarak Uzantılar sayfasına gidin. (Tasarımı gereği chrome:// URL'ler bağlanamaz.)

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)

   'nı inceleyin.

chrome.userScripts ürününün hata verip vermediğini kontrol ederek geliştirici modunun etkinleştirilip etkinleştirilmediğini 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;
  }
}

Issı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ış dünya, bir ana makine sayfasının veya diğer uzantıların erişemeyeceği yürütme ortamıdır. Bu, bir kullanıcı komut dosyasının ana makine sayfasını veya diğer uzantıları etkilemeden JavaScript ortamını değiştirmesine olanak tanır. kullanıcı ve içerik komut dosyalarıdır. Öte yandan, kullanıcı komut dosyaları (ve içerik komut dosyaları) ana makine sayfasına ya da diğer uzantıların kullanıcı ve içerik komut dosyaları tarafından görülemez. Ana ortamda çalışan komut dosyaları, sayfaları ve diğer uzantıları barındırmak için erişilebilir durumdadır ve ana sayfalar ile diğer uzantılar tarafından görülebilir. Dünyayı seçmek için userScripts.register() araması yaparken "USER_SCRIPT" veya "MAIN" verin.

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ümanlar gibi, kullanıcı komut dosyaları da mesajlaşma özelliğini kullanarak uzantının diğer bölümleriyle iletişim kurar (yani bir uzantının diğer herhangi bir bölümünde olduğu gibi runtime.sendMessage() ve runtime.connect() ç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 iletileri tanımlamayı kolaylaştırır.

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

Kullanıcı komut dosyaları, uzantı güncellendiğinde temizlenir. Uzantı hizmeti çalışanındaki runtime.onInstalled etkinlik işleyicisinde kod çalıştırarak bunları tekrar ekleyebilirsiniz. Yalnızca etkinlik geri çağırmasına iletilen "update" nedeni ile ilgili yanıt verin.

Örnek

Bu örnek, örnek 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 içinde yürütülebileceği JavaScript dünyası.

Enum

"MAIN"
Ana makine sayfasının JavaScript'i ile paylaşılan yürütme ortamı olan DOM'un yürütme ortamını belirtir.

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

RegisteredUserScript

Özellikler

• allFrames

  boole isteğe bağlı

  True (doğru) değerine ayarlanırsa, kare sekmenin en üstünde yer alan kare olmasa bile tüm karelere yerleştirilir. Her çerçeve, URL gereklilikleri 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. Bu, yalnızca üst karenin 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 normalde yerleştirileceği sayfalar hariç tutulur. 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. Bu özellik "_" ile başlamamalıdır çünkü oluşturulan komut dosyası kimliklerine ön ek olarak ayrılı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 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 yerleştirileceğini belirtir. Tercih edilen ve varsayılan değer: document_idle.

• 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. Tam olarak bir file veya code belirtilmelidir.

• dosya

  dize isteğe bağlı

  Yerleştirilecek JavaScript dosyasının, uzantının kök dizinine göre yolu. Tam olarak bir file veya code 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

• igp

  dize isteğe bağlı

  Dünya genelinde csp'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 'nı inceleyin.

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

• Taahhüt<void>

  Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

getScripts()

Söz 'nı inceleyin.

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

• filtrele

  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

  işlev isteğe bağlı

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

  (scripts: RegisteredUserScript[]) => void

  • komut dosyaları

    RegisteredUserScript[]

İadeler

• Promise&lt;RegisteredUserScript[]&gt;

  Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

register()

Söz 'nı inceleyin.

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

  işlev isteğe bağlı

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

  () => void

İadeler

• Taahhüt<void>

  Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

unregister()

Söz 'nı inceleyin.

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

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

Parametreler

• filtrele

  UserScriptFilter isteğe bağlı

  Belirtilirse bu yöntem yalnızca kendisiyle 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

• Taahhüt<void>

  Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.

update()

Söz 'nı inceleyin.

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ğrulaması sırasında hata oluşursa veya belirtilen kimlikler tam olarak kaydedilmiş 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

• Taahhüt<void>

  Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.