chrome.userScripts

Deskripsi

Gunakan userScripts API untuk menjalankan skrip pengguna dalam konteks Skrip Pengguna.

Izin

userScripts

Untuk menggunakan chrome.userScripts API, tambahkan izin "userScripts" ke manifest.json dan "host_permissions" untuk situs tempat Anda ingin menjalankan skrip.

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

Ketersediaan

Chrome 120+ MV3+

Konsep dan penggunaan

Skrip pengguna adalah sedikit kode yang dimasukkan ke halaman web untuk mengubah tampilan atau perilakunya. Skrip dibuat oleh pengguna atau didownload dari repositori skrip atau ekstensi skrip pengguna.

Mode developer untuk pengguna ekstensi

Sebagai developer ekstensi, Anda sudah mengaktifkan Mode developer di penginstalan Chrome. Untuk ekstensi skrip pengguna, pengguna Anda juga harus mengaktifkan mode developer. Berikut adalah petunjuk yang dapat Anda salin dan tempel ke dokumentasi Anda sendiri.

  1. Buka halaman Extensions dengan memasukkan chrome://extensions di tab baru. (Secara desain, URL chrome:// tidak dapat ditautkan.)

  2. Aktifkan Mode Developer dengan mengklik tombol di samping Mode developer.

    Halaman ekstensi

    Halaman ekstensi (chrome://extensions)

Anda dapat menentukan apakah mode developer diaktifkan dengan memeriksa apakah chrome.userScripts menampilkan error. Contoh:

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Bekerja di dunia yang terisolasi

Skrip pengguna dan konten dapat berjalan di dunia terisolasi atau di dunia utama. Dunia terisolasi adalah lingkungan eksekusi yang tidak dapat diakses oleh halaman host atau ekstensi lainnya. Hal ini memungkinkan skrip pengguna mengubah lingkungan JavaScript-nya tanpa memengaruhi halaman host atau skrip konten dan pengguna ekstensi lainnya. Sebaliknya, skrip pengguna (dan skrip konten) tidak terlihat oleh halaman host atau skrip pengguna dan konten dari ekstensi lain. Skrip yang berjalan di dunia utama dapat diakses oleh halaman host dan ekstensi lainnya serta dapat dilihat oleh halaman host dan ekstensi lainnya. Untuk memilih dunia, teruskan "USER_SCRIPT" atau "MAIN" saat memanggil userScripts.register().

Untuk mengonfigurasi kebijakan keamanan konten untuk dunia USER_SCRIPT, panggil userScripts.configureWorld():

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

Messaging

Seperti skrip konten dan dokumen di luar layar, skrip pengguna berkomunikasi dengan bagian lain ekstensi menggunakan pesan (artinya skrip dapat memanggil runtime.sendMessage() dan runtime.connect() seperti bagian lain ekstensi). Namun, peristiwa ini diterima menggunakan pengendali peristiwa khusus (artinya, peristiwa ini tidak menggunakan onMessage atau onConnect). Pengendali ini disebut runtime.onUserScriptMessage dan runtime.onUserScriptConnect. Pengendali khusus mempermudah identifikasi pesan dari skrip pengguna, yang merupakan konteks yang kurang tepercaya.

Sebelum mengirim pesan, Anda harus memanggil configureWorld() dengan argumen messaging ditetapkan ke true. Perhatikan bahwa argumen csp dan messaging dapat diteruskan secara bersamaan.

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

Update ekstensi

Skrip pengguna akan dihapus saat ekstensi diupdate. Anda dapat menambahkannya kembali dengan menjalankan kode di pengendali peristiwa runtime.onInstalled di pekerja layanan ekstensi. Hanya respons alasan "update" yang diteruskan ke callback peristiwa.

Contoh

Contoh ini berasal dari contoh userScript di repositori contoh kami.

Mendaftarkan skrip

Contoh berikut menunjukkan panggilan dasar ke register(). Argumen pertama adalah array objek yang menentukan skrip yang akan didaftarkan. Ada lebih banyak opsi daripada yang ditampilkan di sini.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Jenis

ExecutionWorld

Dunia JavaScript tempat skrip pengguna dieksekusi.

Enum

"MAIN"
Menentukan lingkungan eksekusi DOM, yang merupakan lingkungan eksekusi yang dibagikan dengan JavaScript halaman host.

"USER_SCRIPT"
Menentukan lingkungan eksekusi yang khusus untuk skrip pengguna dan dikecualikan dari CSP halaman.

RegisteredUserScript

Properti

  • allFrames

    boolean opsional

    Jika benar, kode akan dimasukkan ke semua frame, meskipun frame bukan frame paling atas di tab. Setiap frame diperiksa secara terpisah untuk persyaratan URL; frame tidak akan dimasukkan ke dalam frame turunan jika persyaratan URL tidak terpenuhi. Defaultnya adalah salah (false), yang berarti hanya frame atas yang cocok.

  • excludeGlobs

    string[] opsional

    Menentukan pola karakter pengganti untuk halaman tempat skrip pengguna ini TIDAK akan dimasukkan.

  • excludeMatches

    string[] opsional

    Mengecualikan halaman yang akan disuntik oleh skrip pengguna ini. Lihat Pola Pencocokan untuk mengetahui detail selengkapnya tentang sintaksis string ini.

  • id

    string

    ID skrip pengguna yang ditentukan dalam panggilan API. Properti ini tidak boleh diawali dengan '_' karena dicadangkan sebagai awalan untuk ID skrip yang dihasilkan.

  • includeGlobs

    string[] opsional

    Menentukan pola karakter pengganti untuk halaman tempat skrip pengguna ini akan dimasukkan.

  • js

    ScriptSource[] opsional

    Daftar objek ScriptSource yang menentukan sumber skrip yang akan dimasukkan ke halaman yang cocok. Properti ini harus ditentukan untuk ${ref:register}, dan jika ditentukan, properti ini harus berupa array yang tidak kosong.

  • cocok

    string[] opsional

    Menentukan halaman tempat skrip pengguna ini akan dimasukkan. Lihat Pola Pencocokan untuk mengetahui detail selengkapnya tentang sintaksis string ini. Properti ini harus ditentukan untuk ${ref:register}.

  • runAt

    RunAt opsional

    Menentukan kapan file JavaScript dimasukkan ke halaman web. Nilai pilihan dan defaultnya adalah document_idle.

  • dunia

    ExecutionWorld opsional

    Lingkungan eksekusi JavaScript tempat skrip dijalankan. Defaultnya adalah `USER_SCRIPT`.

  • worldId

    string opsional

    Tertunda

    Jika ditentukan, menentukan ID dunia skrip pengguna tertentu untuk dieksekusi. Hanya valid jika world dihilangkan atau USER_SCRIPT. Jika dihilangkan, skrip akan dijalankan di dunia skrip pengguna default. Nilai dengan garis bawah di awal (_) dicadangkan.

ScriptSource

Properti

  • kode

    string opsional

    String yang berisi kode JavaScript yang akan dimasukkan. Tepat satu dari file atau code harus ditentukan.

  • file

    string opsional

    Jalur file JavaScript yang akan dimasukkan relatif terhadap direktori root ekstensi. Tepat satu dari file atau code harus ditentukan.

UserScriptFilter

Properti

  • ids

    string[] opsional

    getScripts hanya menampilkan skrip dengan ID yang ditentukan dalam daftar ini.

WorldProperties

Properti

  • csp

    string opsional

    Menentukan csp dunia. Defaultnya adalah csp dunia `ISOLATED`.

  • fitur pesan

    boolean opsional

    Menentukan apakah API pesan diekspos. Defaultnya adalah false.

  • worldId

    string opsional

    Tertunda

    Menentukan ID dunia skrip pengguna tertentu yang akan diperbarui. Jika tidak diberikan, akan memperbarui properti dunia skrip pengguna default. Nilai dengan garis bawah di awal (_) dicadangkan.

Metode

configureWorld()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Mengonfigurasi lingkungan eksekusi `USER_SCRIPT`.

Parameter

  • properti

    WorldProperties

    Berisi konfigurasi dunia skrip pengguna.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    () => void

Hasil

  • Promise<void>

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getScripts()

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

Menampilkan semua skrip pengguna yang terdaftar secara dinamis untuk ekstensi ini.

Parameter

Hasil

  • Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

getWorldConfigurations()

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

Mengambil semua konfigurasi dunia yang terdaftar.

Parameter

Hasil

  • Promise<WorldProperties[]>

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

register()

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

Mendaftarkan satu atau beberapa skrip pengguna untuk ekstensi ini.

Parameter

  • Berisi daftar skrip pengguna yang akan didaftarkan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    () => void

Hasil

  • Promise<void>

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

resetWorldConfiguration()

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

Mereset konfigurasi untuk dunia skrip pengguna. Semua skrip yang dimasukkan ke dunia dengan ID yang ditentukan akan menggunakan konfigurasi dunia default.

Parameter

  • worldId

    string opsional

    ID dunia skrip pengguna yang akan direset. Jika dihilangkan, konfigurasi dunia default akan direset.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    () => void

Hasil

  • Promise<void>

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

unregister()

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

Membatalkan pendaftaran semua skrip pengguna yang terdaftar secara dinamis untuk ekstensi ini.

Parameter

  • filter

    UserScriptFilter opsional

    Jika ditentukan, metode ini hanya membatalkan pendaftaran skrip pengguna yang cocok.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    () => void

Hasil

  • Promise<void>

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.

update()

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

Memperbarui satu atau beberapa skrip pengguna untuk ekstensi ini.

Parameter

  • Berisi daftar skrip pengguna yang akan diperbarui. Properti hanya diperbarui untuk skrip yang ada jika ditentukan dalam objek ini. Jika ada error selama penguraian skrip/validasi file, atau jika ID yang ditentukan tidak sesuai dengan skrip yang terdaftar sepenuhnya, tidak ada skrip yang akan diperbarui.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    () => void

Hasil

  • Promise<void>

    Promise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.