Deskripsi
Gunakan chrome.scripting
API untuk mengeksekusi skrip dalam berbagai konteks.
Izin
scripting
Ketersediaan
Manifes
Untuk menggunakan chrome.scripting
API, deklarasikan izin "scripting"
di manifes ditambah izin host untuk halaman yang akan disisipi skrip. Gunakan kunci "host_permissions"
atau izin "activeTab"
, yang memberikan izin host sementara. Contoh berikut menggunakan izin activeTab.
{
"name": "Scripting Extension",
"manifest_version": 3,
"permissions": ["scripting", "activeTab"],
...
}
Konsep dan penggunaan
Anda dapat menggunakan chrome.scripting
API untuk memasukkan JavaScript dan CSS ke dalam
situs web. Hal ini serupa dengan yang dapat Anda lakukan dengan konten
skrip. Namun, dengan menggunakan namespace chrome.scripting
, ekstensi
dapat membuat keputusan pada saat runtime.
Target injeksi
Anda dapat menggunakan parameter target
guna menentukan target untuk memasukkan JavaScript atau
ke dalam CSS.
Satu-satunya kolom yang wajib diisi adalah tabId
. Secara {i>default<i}, injeksi akan berjalan di
{i>frame <i}utama dari tab yang ditentukan.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("script injected"));
Untuk berjalan di semua frame tab yang ditentukan, Anda dapat menyetel boolean allFrames
ke true
.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
files : [ "script.js" ],
})
.then(() => console.log("script injected in all frames"));
Anda juga bisa memasukkan ke dalam {i>frame<i} tertentu pada {i>tab<i} dengan menentukan {i>frame<i} individual
pelanggan. Untuk mengetahui informasi selengkapnya tentang ID frame, lihat chrome.webNavigation
API.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
files : [ "script.js" ],
})
.then(() => console.log("script injected on target frames"));
Kode yang dimasukkan
Ekstensi dapat menentukan kode yang akan dimasukkan baik melalui file eksternal atau melalui variabel runtime.
File
File ditetapkan sebagai string yang merupakan jalur yang terkait dengan root ekstensi
saat ini. Kode berikut akan memasukkan file script.js
ke file utama
{i>frame<i} tab.
function getTabId() { ... }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
files : [ "script.js" ],
})
.then(() => console.log("injected script file"));
Fungsi runtime
Saat memasukkan JavaScript dengan scripting.executeScript()
, Anda dapat menentukan
yang akan dieksekusi
sebagai pengganti file. Fungsi ini harus berupa fungsi
yang tersedia untuk konteks ekstensi saat ini.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : getTitle,
})
.then(() => console.log("injected a function"));
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor() {
document.body.style.backgroundColor = getUserColor();
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
})
.then(() => console.log("injected a function"));
Anda dapat mengatasi masalah ini dengan menggunakan properti args
:
function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
document.body.style.backgroundColor = backgroundColor;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId()},
func : changeBackgroundColor,
args : [ getUserColor() ],
})
.then(() => console.log("injected a function"));
String runtime
Jika menginjeksikan CSS di dalam halaman, Anda juga dapat menentukan string yang akan digunakan di
css
. Opsi ini hanya tersedia untuk scripting.insertCSS()
; Anda
tidak dapat mengeksekusi string menggunakan scripting.executeScript()
.
function getTabId() { ... }
const css = "body { background-color: red; }";
chrome.scripting
.insertCSS({
target : {tabId : getTabId()},
css : css,
})
.then(() => console.log("CSS injected"));
Menangani hasil
Hasil eksekusi JavaScript akan diteruskan ke ekstensi. Hasil tunggal disertakan per frame. Frame utama dijamin akan menjadi indeks pertama dalam {i>array<i} yang dihasilkan; semua {i>frame<i} lainnya dalam urutan yang tidak deterministik.
function getTabId() { ... }
function getTitle() { return document.title; }
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : getTitle,
})
.then(injectionResults => {
for (const {frameId, result} of injectionResults) {
console.log(`Frame ${frameId} result:`, result);
}
});
scripting.insertCSS()
tidak menampilkan hasil apa pun.
Promise
Jika nilai eksekusi skrip yang dihasilkan adalah promise, Chrome akan menunggu untuk promise untuk menyelesaikan dan mengembalikan nilai yang dihasilkan.
function getTabId() { ... }
async function addIframe() {
const iframe = document.createElement("iframe");
const loadComplete =
new Promise(resolve => iframe.addEventListener("load", resolve));
iframe.src = "https://example.com";
document.body.appendChild(iframe);
await loadComplete;
return iframe.contentWindow.document.title;
}
chrome.scripting
.executeScript({
target : {tabId : getTabId(), allFrames : true},
func : addIframe,
})
.then(injectionResults => {
for (const frameResult of injectionResults) {
const {frameId, result} = frameResult;
console.log(`Frame ${frameId} result:`, result);
}
});
Contoh
Batalkan pendaftaran semua skrip konten dinamis
Cuplikan berikut berisi fungsi yang membatalkan pendaftaran semua konten dinamis skrip yang sebelumnya telah didaftarkan ekstensi.
async function unregisterAllDynamicContentScripts() {
try {
const scripts = await chrome.scripting.getRegisteredContentScripts();
const scriptIds = scripts.map(script => script.id);
return chrome.scripting.unregisterContentScripts(scriptIds);
} catch (error) {
const message = [
"An unexpected error occurred while",
"unregistering dynamic content scripts.",
].join(" ");
throw new Error(message, {cause : error});
}
}
Untuk mencoba chrome.scripting
API,
instal contoh skrip dari contoh ekstensi Chrome
repositori resource.
Jenis
ContentScriptFilter
Properti
-
ids
string[] opsional
Jika ditentukan,
getRegisteredContentScripts
hanya akan menampilkan skrip dengan ID yang ditentukan dalam daftar ini.
CSSInjection
Properti
-
css
string opsional
String berisi CSS yang akan diinjeksi. Hanya satu dari
files
dancss
yang harus ditentukan. -
file
string[] opsional
Jalur file CSS yang akan dimasukkan, relatif terhadap direktori utama ekstensi. Hanya satu dari
files
dancss
yang harus ditentukan. -
asal
StyleOrigin opsional
Asal gaya untuk injeksi. Default-nya adalah
'AUTHOR'
. -
target
Detail yang menentukan target untuk menyisipkan CSS.
ExecutionWorld
Dunia JavaScript untuk skrip yang akan dieksekusi.
Enum
"ISOLATED"
Menentukan dunia yang terisolasi, yang merupakan lingkungan eksekusi yang unik untuk ekstensi ini.
"MAIN"
Menentukan dunia utama DOM, yaitu lingkungan eksekusi yang dibagikan dengan JavaScript halaman host.
InjectionResult
Properti
-
documentId
string
Chrome 106 dan yang lebih baruDokumen yang terkait dengan injeksi.
-
frameId
angka
Chrome 90 dan yang lebih baruFrame yang terkait dengan injeksi.
-
hasil
semua opsional
Hasil eksekusi skrip.
InjectionTarget
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
Chrome 106 dan yang lebih baruID documentId tertentu yang akan dimasukkan. Nilai ini tidak boleh ditetapkan jika
frameIds
disetel. -
frameIds
number[] opsional
ID frame tertentu yang akan dimasukkan.
-
tabId
angka
ID tab yang akan diinjeksikan.
RegisteredContentScript
Properti
-
allFrames
boolean opsional
Jika ditetapkan true, kode ini akan dimasukkan ke semua frame, meskipun frame tersebut bukan frame paling atas dalam tab. Setiap frame diperiksa secara terpisah untuk mengetahui persyaratan URL; itu tidak akan dimasukkan ke dalam {i>frame<i} turunan jika persyaratan URL tidak terpenuhi. Default-nya adalah false, artinya hanya frame teratas yang cocok.
-
css
string[] opsional
Daftar file CSS yang akan dimasukkan ke halaman yang cocok. Hal ini dimasukkan sesuai urutan kemunculannya di array ini, sebelum DOM dibuat atau ditampilkan untuk halaman.
-
excludeMatches
string[] opsional
Mengecualikan halaman yang seharusnya dimasukkan skrip konten ini. Lihat Pola Pencocokan untuk mengetahui detail selengkapnya tentang sintaksis string ini.
-
id
string
ID skrip konten, yang ditentukan dalam panggilan API. Tidak boleh diawali dengan '_' karena dicadangkan sebagai awalan untuk ID skrip yang dihasilkan.
-
js
string[] opsional
Daftar file JavaScript yang akan dimasukkan ke halaman yang cocok. Ini diinjeksikan sesuai urutan kemunculannya di array ini.
-
matchOriginAsFallback
boolean opsional
Chrome 119 dan yang lebih baruMenunjukkan apakah skrip dapat dimasukkan ke dalam frame jika URL berisi skema yang tidak didukung; khususnya: about:, data:, blob:, atau filesystem:. Dalam kasus ini, asal URL diperiksa untuk menentukan apakah skrip harus dimasukkan atau tidak. Jika origin adalah
null
(seperti halnya data: URL), origin yang digunakan adalah frame yang membuat frame saat ini atau frame yang memulai navigasi ke frame ini. Perhatikan, ini mungkin bukan frame induk. -
cocok
string[] opsional
Menentukan halaman tempat skrip konten ini akan dimasukkan. Lihat Pola Pencocokan untuk mengetahui detail selengkapnya tentang sintaksis string ini. Harus ditetapkan untuk
registerContentScripts
. -
persistAcrossSessions
boolean opsional
Menentukan apakah skrip konten ini akan tetap ada di sesi mendatang. Nilai defaultnya adalah benar (true).
-
runAt
RunAt opsional
Menentukan kapan file JavaScript dimasukkan ke halaman web. Nilai yang disukai dan default adalah
document_idle
. -
dunia
ExecutionWorld opsional
Chrome 102 dan yang lebih baru"World" JavaScript untuk menjalankan skrip. Default-nya adalah
ISOLATED
.
ScriptInjection
Properti
-
args
setiap[] opsional
Chrome 92 dan yang lebih baruArgumen yang akan diteruskan ke fungsi yang disediakan. Ini hanya valid jika parameter
func
ditentukan. Argumen ini harus dapat diserialisasi JSON. -
file
string[] opsional
Jalur file JS atau CSS yang akan dimasukkan, relatif terhadap direktori utama ekstensi. Hanya satu dari
files
ataufunc
yang harus ditentukan. -
injectImmediately
boolean opsional
Chrome 102 dan yang lebih baruApakah injeksi harus dipicu pada target sesegera mungkin. Perhatikan bahwa hal ini tidak menjamin injeksi akan terjadi sebelum pemuatan halaman, karena halaman mungkin sudah dimuat saat skrip mencapai target.
-
target
Detail yang menentukan target untuk memasukkan skrip.
-
dunia
ExecutionWorld opsional
Chrome 95 dan yang lebih baru"World" JavaScript untuk menjalankan skrip. Default-nya adalah
ISOLATED
. -
func
batal opsional
Chrome 92 dan yang lebih baruFungsi JavaScript untuk melakukan injeksi. Fungsi ini akan diserialisasi, lalu dideserialisasi untuk injeksi. Artinya, setiap parameter terikat dan konteks eksekusi akan hilang. Hanya satu dari
files
ataufunc
yang harus ditentukan.Fungsi
func
akan terlihat seperti ini:() => {...}
StyleOrigin
Asal untuk perubahan gaya. Lihat origin gaya untuk info selengkapnya.
Enum
"AUTHOR"
"PENGGUNA"
Metode
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
callback?: function,
)
Memasukkan skrip ke dalam konteks target. Secara default, skrip akan dijalankan pada document_idle
, atau langsung jika halaman sudah dimuat. Jika properti injectImmediately
disetel, skrip akan dimasukkan tanpa menunggu, meskipun halaman belum selesai dimuat. Jika skrip mengevaluasi ke promise, browser akan menunggu promise selesai dan mengembalikan nilai yang dihasilkan.
Parameter
-
injeksi
Detail skrip yang akan dimasukkan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(results: InjectionResult[]) => void
-
hasil
-
Hasil
-
Promise<InjectionResult[]>
Chrome 90 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
getRegisteredContentScripts()
chrome.scripting.getRegisteredContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Menampilkan semua skrip konten yang terdaftar secara dinamis untuk ekstensi ini yang cocok dengan filter yang diberikan.
Parameter
-
filter
ContentScriptFilter opsional
Objek untuk memfilter skrip ekstensi yang terdaftar secara dinamis.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:(scripts: RegisteredContentScript[]) => void
-
skrip
-
Hasil
-
Promise<RegisteredContentScript[]>
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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
callback?: function,
)
Menyisipkan stylesheet CSS ke dalam konteks target. Jika beberapa frame ditentukan, injeksi yang gagal akan diabaikan.
Parameter
-
injeksi
Detail gaya yang akan disisipkan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<void>
Chrome 90 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Mendaftarkan satu atau beberapa skrip konten untuk ekstensi ini.
Parameter
-
skrip
Berisi daftar skrip yang akan didaftarkan. Jika ada error selama penguraian skrip/validasi file, atau jika ID yang ditentukan sudah ada, tidak ada skrip yang didaftarkan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
Menghapus stylesheet CSS yang sebelumnya disisipkan oleh ekstensi ini dari konteks target.
Parameter
-
injeksi
Detail gaya yang akan dihapus. Perhatikan bahwa properti
css
,files
, danorigin
harus sama persis dengan stylesheet yang disisipkan melaluiinsertCSS
. Mencoba menghapus lembar gaya yang tidak ada berarti tidak ada pengoperasian. -
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Membatalkan pendaftaran skrip konten untuk ekstensi ini.
Parameter
-
filter
ContentScriptFilter opsional
Jika ditentukan, hanya batalkan pendaftaran skrip konten dinamis yang cocok dengan filter. Jika tidak, semua skrip konten dinamis ekstensi tidak akan terdaftar.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Memperbarui satu atau beberapa skrip konten untuk ekstensi ini.
Parameter
-
skrip
Berisi daftar skrip 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 diperbarui.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti ini:() => void
Hasil
-
Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.