browser.userScripts

Deskripsi

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

Izin

userScripts

Untuk menggunakan User Scripts API, browser.userScripts, 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+ browser.* sejak Chrome 148 MV3+

Konsep dan penggunaan

Skrip pengguna adalah cuplikan kode yang dimasukkan ke halaman web untuk mengubah tampilan atau perilakunya. Tidak seperti fitur ekstensi lainnya, seperti Skrip Konten dan browser.scripting API, User Scripts API memungkinkan Anda menjalankan kode arbitrer. API ini diperlukan untuk ekstensi yang menjalankan skrip yang disediakan oleh pengguna yang tidak dapat dikirim sebagai bagian dari paket ekstensi Anda.

Mengaktifkan penggunaan userScripts API

Setelah ekstensi Anda menerima izin untuk menggunakan userScripts API, pengguna harus mengaktifkan tombol tertentu untuk mengizinkan ekstensi Anda menggunakan API. Tombol khusus yang diperlukan, dan perilaku API saat dinonaktifkan, bervariasi menurut versi Chrome.

Gunakan pemeriksaan berikut untuk menentukan tombol mana yang perlu diaktifkan pengguna, misalnya, selama orientasi pengguna baru:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

Bagian berikut menjelaskan berbagai tombol dan cara mengaktifkannya.

Chrome versi sebelum 138 (Tombol mode developer)

Sebagai developer ekstensi, Anda sudah mengaktifkan Mode developer di penginstalan Chrome. Pengguna Anda juga harus mengaktifkan Mode developer.

Anda dapat menyalin dan menempelkan petunjuk berikut ke dalam dokumentasi ekstensi untuk pengguna Anda

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

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

   

   Halaman ekstensi (chrome://extensions)

Catatan: Jika mode Developer tidak diaktifkan, mengakses browser.userScripts akan menampilkan error. Anda dapat menggunakan error ini untuk menentukan ketersediaan API, lihat Memeriksa ketersediaan API.

Chrome versi 138 dan yang lebih baru (tombol Izinkan Skrip Pengguna)

Tombol Izinkan Skrip Pengguna ada di halaman detail setiap ekstensi (misalnya, chrome://extensions/?id=ID_EKSTENSI_ANDA).

Anda dapat menyalin dan menempelkan petunjuk berikut ke dalam dokumentasi ekstensi untuk pengguna:

1. Buka halaman Ekstensi dengan memasukkan chrome://extensions di tab baru. (Secara desain, URL chrome:// tidak dapat ditautkan.)
2. Klik tombol "Detail" di kartu ekstensi untuk melihat informasi mendetail tentang ekstensi tersebut.
3. Klik tombol di samping Allow User Scripts.

Tombol Izinkan Skrip Pengguna (chrome://extensions/?id=abc...)

Catatan: Jika tombol Allow User Scripts tidak diaktifkan, browser.userScripts tidak akan ditentukan. Status yang tidak ditentukan ini (mirip dengan perilaku API lainnya) hanya akan direset saat konteks skrip ekstensi dimuat ulang. Misalnya, jika pengguna mencabut akses saat pekerja layanan Anda berjalan, browser.userScripts akan tetap ditentukan. Namun, dalam skenario ini, upaya untuk memanggil salah satu metodenya akan menampilkan error.

Memeriksa ketersediaan API

Sebaiknya lakukan pemeriksaan berikut untuk menentukan apakah userScripts API diaktifkan, karena API ini berfungsi di semua versi Chrome. Pemeriksaan ini mencoba memanggil metode browser.userScripts() yang akan selalu berhasil jika API tersedia. Jika panggilan ini menampilkan error, berarti API tidak tersedia:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    browser.userScripts.getScripts();
    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. Lingkungan 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 dapat dilihat oleh halaman host atau skrip pengguna dan konten ekstensi lainnya. 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():

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

Pesan

Seperti skrip konten dan dokumen di luar layar, skrip pengguna berkomunikasi dengan bagian lain ekstensi menggunakan pesan (artinya, skrip tersebut dapat memanggil runtime.sendMessage() dan runtime.connect() seperti bagian lain ekstensi). Namun, peristiwa ini diterima menggunakan pengendali peristiwa khusus (artinya, 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 ditetapkan ke true. Perhatikan bahwa argumen csp dan messaging dapat diteruskan secara bersamaan.

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

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

Jenis

ExecutionWorld

Lingkungan JavaScript tempat skrip pengguna dijalankan.

Enum

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

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

InjectionResult

Chrome 135+ browser.* sejak Chrome 148

Properti

• documentId

  string

  Dokumen yang terkait dengan injeksi.

• error

  string opsional

  Error, jika ada. error dan result tidak dapat digunakan secara bersamaan.

• frameId

  angka

  Frame yang terkait dengan injeksi.

• hasil

  opsional apa pun

  Hasil eksekusi skrip.

InjectionTarget

Chrome 135+ browser.* sejak Chrome 148

Properti

• allFrames

  boolean opsional

  Apakah skrip harus dimasukkan ke dalam semua frame dalam tab. Nilai defaultnya adalah false (salah). Nilai ini tidak boleh benar jika frameIds ditentukan.

• documentIds

  string[] opsional

  ID documentId tertentu yang akan dimasukkan. Ini tidak boleh ditetapkan jika frameIds ditetapkan.

• frameIds

  number[] opsional

  ID frame tertentu yang akan diinjeksikan.

• tabId

  angka

  ID tab tempat injeksi akan dilakukan.

RegisteredUserScript

Properti

• allFrames

  boolean opsional

  Jika benar, skrip akan dimasukkan ke semua frame, meskipun frame tersebut bukan frame paling atas di tab. Setiap frame diperiksa secara independen untuk persyaratan URL; skrip konten tidak akan dimasukkan ke dalam frame turunan jika persyaratan URL tidak terpenuhi. Defaultnya adalah false, yang berarti hanya frame teratas yang dicocokkan.

• excludeGlobs

  string[] opsional

  Menentukan pola karakter pengganti untuk halaman yang TIDAK akan disisipi skrip pengguna ini.

• excludeMatches

  string[] opsional

  Mengecualikan halaman yang seharusnya disisipi 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 dalam 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 yang direkomendasikan dan default adalah document_idle.

• dunia

  ExecutionWorld opsional

  Lingkungan eksekusi JavaScript untuk menjalankan skrip. Defaultnya adalah `USER_SCRIPT`.

• worldId

  string opsional

  Chrome 133+ browser.* sejak Chrome 148

  Menentukan ID world skrip pengguna yang akan dieksekusi. Jika dihilangkan, skrip akan dijalankan di dunia skrip pengguna default. Hanya berlaku jika world dihilangkan atau bernilai USER_SCRIPT. Nilai dengan garis bawah di awal (_) dicadangkan.

ScriptSource

Properti

• kode

  string opsional

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

• file

  string opsional

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

UserScriptFilter

Properti

• ids

  string[] opsional

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

UserScriptInjection

Chrome 135+ browser.* sejak Chrome 148

Properti

• injectImmediately

  boolean opsional

  Apakah injeksi harus dipicu di target sesegera mungkin. Perhatikan bahwa hal ini tidak menjamin injeksi akan terjadi sebelum pemuatan halaman, karena halaman mungkin sudah dimuat saat skrip mencapai target.

• js

  ScriptSource[]

  Daftar objek ScriptSource yang menentukan sumber skrip yang akan dimasukkan ke target.

• target

  InjectionTarget

  Detail yang menentukan target tempat skrip akan dimasukkan.

• dunia

  ExecutionWorld opsional

  "World" JavaScript untuk menjalankan skrip. Defaultnya adalah USER_SCRIPT.

• worldId

  string opsional

  Menentukan ID world skrip pengguna yang akan dieksekusi. Jika dihilangkan, skrip akan dijalankan di dunia skrip pengguna default. Hanya berlaku jika world dihilangkan atau bernilai USER_SCRIPT. Nilai dengan garis bawah di awal (_) dicadangkan.

WorldProperties

Properti

• csp

  string opsional

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

• fitur pesan

  boolean opsional

  Menentukan apakah API pesan ditampilkan. Defaultnya adalah false.

• worldId

  string opsional

  Chrome 133+ browser.* sejak Chrome 148

  Menentukan ID world 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()

browser.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

Mengonfigurasi lingkungan eksekusi `USER_SCRIPT`.

Parameter

• properti

  WorldProperties

  Berisi konfigurasi dunia skrip pengguna.

Hasil

• Promise<void>

  Promise yang di-resolve setelah dunia dikonfigurasi.

execute()

Chrome 135+ browser.* sejak Chrome 148

browser.userScripts.execute(
  injection: UserScriptInjection,
): Promise<InjectionResult[]>

Memasukkan skrip ke dalam konteks target. Secara default, skrip akan dijalankan di document_idle, atau segera jika halaman sudah dimuat. Jika properti injectImmediately ditetapkan, skrip akan dimasukkan tanpa menunggu, meskipun halaman belum selesai dimuat. Jika skrip dievaluasi ke promise, browser akan menunggu promise diselesaikan dan menampilkan nilai yang dihasilkan.

Parameter

• injeksi

  UserScriptInjection

Hasil

• Promise<InjectionResult[]>

getScripts()

browser.userScripts.getScripts(
  filter?: UserScriptFilter,
): Promise<RegisteredUserScript[]>

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

Parameter

• filter

  UserScriptFilter opsional

  Jika ditentukan, metode ini hanya menampilkan skrip pengguna yang cocok.

Hasil

• Promise<RegisteredUserScript[]>

  Promise yang di-resolve dengan skrip yang terdaftar. Promise akan ditolak jika terjadi error.

getWorldConfigurations()

Chrome 133+ browser.* sejak Chrome 148

browser.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

Mengambil semua konfigurasi dunia yang terdaftar.

Hasil

• Promise<WorldProperties[]>

  Promise yang di-resolve dengan konfigurasi dunia yang terdaftar.

register()

browser.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

Mendaftarkan satu atau beberapa skrip pengguna untuk ekstensi ini.

Parameter

• skrip

  RegisteredUserScript[]

  Berisi daftar skrip pengguna yang akan didaftarkan.

Hasil

• Promise<void>

  Promise yang di-resolve setelah skrip didaftarkan sepenuhnya. Promise akan ditolak jika terjadi error.

resetWorldConfiguration()

Chrome 133+ browser.* sejak Chrome 148

browser.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

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

Parameter

• worldId

  string opsional

  ID lingkungan skrip pengguna yang akan direset. Jika dihilangkan, tindakan ini akan mereset konfigurasi dunia default.

Hasil

• Promise<void>

  Promise yang di-resolve saat konfigurasi direset.

unregister()

browser.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

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.

Hasil

• Promise<void>

  Promise yang diselesaikan setelah skrip sepenuhnya dibatalkan pendaftarannya. Promise akan ditolak jika terjadi error.

update()

browser.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

Memperbarui satu atau beberapa skrip pengguna untuk ekstensi ini.

Parameter

• skrip

  RegisteredUserScript[]

  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.

Hasil

• Promise<void>

  Promise yang di-resolve setelah skrip diupdate sepenuhnya. Promise akan ditolak jika terjadi error.