Deskripsi
Gunakan userScripts
API untuk mengeksekusi 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
Konsep dan penggunaan
Skrip pengguna adalah potongan kode yang dimasukkan ke dalam halaman 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 telah mengaktifkan Mode developer saat menginstal Chrome. Untuk ekstensi skrip pengguna, pengguna Anda juga harus mengaktifkan mode developer. Berikut adalah petunjuk yang dapat Anda salin dan tempel ke dalam dokumentasi Anda sendiri.
- Buka halaman Ekstensi dengan memasukkan
chrome://extensions
di tab baru. (Menurut desain,chrome://
URL tidak dapat ditautkan.) Aktifkan Mode Developer dengan mengklik tombol di samping Mode developer.
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 yang 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 konten dan pengguna dari ekstensi lainnya. Skrip yang berjalan di dunia utama dapat diakses untuk menghosting halaman dan ekstensi lainnya serta terlihat untuk menghosting halaman dan ekstensi lainnya. Untuk memilih dunia, teruskan "USER_SCRIPT"
atau "MAIN"
saat memanggil userScripts.register()
.
Guna mengonfigurasi kebijakan keamanan konten untuk dunia USER_SCRIPT
, panggil userScripts.configureWorld()
:
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
Pesan
Seperti skrip konten dan dokumen di balik layar, skrip pengguna berkomunikasi dengan bagian ekstensi lain menggunakan pesan (artinya, runtime.sendMessage()
dan runtime.connect()
dapat dipanggil seperti bagian lain dari ekstensi). Namun, pengendali ini diterima menggunakan pengendali peristiwa khusus (artinya, pengendali ini tidak menggunakan onMessage
atau onConnect
). Pengendali ini disebut runtime.onUserScriptMessage
dan runtime.onUserScriptConnect
. Pengendali khusus memudahkan identifikasi pesan dari skrip pengguna, yang merupakan konteks yang kurang tepercaya.
Sebelum mengirim pesan, Anda harus memanggil configureWorld()
dengan argumen messaging
yang disetel ke true
. Perlu diperhatikan 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 merespons 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. Terdapat lebih banyak opsi daripada yang ditampilkan di sini.
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Jenis
ExecutionWorld
Dunia JavaScript untuk eksekusi skrip pengguna.
Enum
"MAIN"
Menentukan lingkungan eksekusi DOM, yang merupakan lingkungan eksekusi yang dibagikan dengan JavaScript halaman host.
"USER_script"
Menentukan lingkungan eksekusi yang spesifik untuk skrip pengguna dan dikecualikan dari CSP halaman.
RegisteredUserScript
Properti
-
allFrames
boolean opsional
Jika true (benar), tindakan ini akan dimasukkan ke semua frame, meskipun frame tersebut bukan frame teratas dalam tab. Setiap frame diperiksa secara terpisah untuk mengetahui persyaratan URL; frame tidak akan dimasukkan ke dalam frame turunan jika persyaratan URL tidak terpenuhi. Nilai defaultnya adalah false (salah), artinya hanya frame teratas yang cocok.
-
excludeGlobs
string[] opsional
Menentukan pola karakter pengganti untuk halaman yang TIDAK akan dimasukkan skrip pengguna ini.
-
excludeMatches
string[] opsional
Mengecualikan halaman tempat skrip pengguna ini akan dimasukkan ke dalamnya. Lihat Pola Pencocokan untuk 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 yang akan memasukkan skrip pengguna ini.
-
js
Daftar objek ScriptSource yang menentukan sumber skrip yang akan dimasukkan ke halaman yang cocok.
-
cocok dengan
string[] opsional
Menentukan halaman tempat skrip pengguna ini akan dimasukkan. Lihat Pola Pencocokan untuk 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 default dan pilihan adalah
document_idle
. -
dunia
ExecutionWorld opsional
Lingkungan eksekusi JavaScript untuk menjalankan skrip. Defaultnya adalah
`USER_SCRIPT`
.
ScriptSource
Properti
-
kode
string opsional
String berisi kode JavaScript yang akan dimasukkan. Tepat satu dari
file
ataucode
harus ditentukan. -
file
string opsional
Jalur file JavaScript yang akan dimasukkan relatif terhadap direktori root ekstensi. Tepat satu dari
file
ataucode
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
.
Metode
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Mengonfigurasi lingkungan eksekusi `USER_SCRIPT`
.
Parameter
-
properti
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()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
Menampilkan semua skrip pengguna yang terdaftar secara dinamis untuk ekstensi ini.
Parameter
-
filter
UserScriptFilter opsional
Jika ditentukan, metode ini hanya akan menampilkan skrip pengguna yang cocok dengannya.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(scripts: RegisteredUserScript[]) => void
-
skrip
-
Hasil
-
Promise<RegisteredUserScript[]>
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()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
Mendaftarkan satu atau beberapa skrip pengguna untuk ekstensi ini.
Parameter
-
skrip
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.
unregister()
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 akan membatalkan pendaftaran skrip pengguna yang cocok dengannya.
-
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()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
Memperbarui satu atau beberapa skrip pengguna untuk ekstensi ini.
Parameter
-
skrip
Berisi daftar skrip pengguna yang akan diperbarui. Properti hanya diperbarui untuk skrip yang ada jika ditentukan dalam objek ini. Jika terjadi 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.