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 beserta izin host untuk halaman tempat skrip akan dimasukkan. 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. Hal ini mirip dengan apa yang dapat Anda lakukan dengan skrip
konten. Namun, dengan menggunakan namespace chrome.scripting
, ekstensi
dapat membuat keputusan saat runtime.
Target injeksi
Anda dapat menggunakan parameter target
untuk menentukan target yang akan dimasukkan JavaScript atau
CSS.
Satu-satunya kolom yang wajib diisi adalah tabId
. Secara default, injeksi akan berjalan di
frame 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 pada tab yang ditentukan, Anda dapat menetapkan 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 dapat memasukkan frame tertentu dari tab dengan menentukan ID frame
satu per satu. 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 melalui file eksternal atau variabel runtime.
Files
File ditetapkan sebagai string yang merupakan jalur yang terkait dengan direktori root ekstensi. Kode berikut akan memasukkan file script.js
ke dalam frame
utama 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
fungsi yang akan dijalankan, bukan file. Fungsi ini harus berupa variabel 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 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 memasukkan CSS dalam halaman, Anda juga dapat menentukan string yang akan digunakan dalam properti 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 diteruskan ke ekstensi. Hasil tunggal disertakan per frame. Frame utama dijamin menjadi indeks pertama dalam array yang dihasilkan; semua frame lainnya berada 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 sebuah promise, Chrome akan menunggu promise selesai dan menampilkan 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 skrip konten dinamis yang telah didaftarkan ekstensi sebelumnya.
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 pembuatan skrip dari repositori contoh ekstensi Chrome.
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 dimasukkan. Tepat salah satu dari
files
dancss
harus ditentukan. -
file
string[] opsional
Jalur file CSS yang akan dimasukkan, relatif terhadap direktori utama ekstensi. Tepat salah satu dari
files
dancss
harus ditentukan. -
asal
StyleOrigin opsional
Origin gaya untuk injeksi. Default-nya adalah
'AUTHOR'
. -
target
Detail yang menentukan target tempat CSS akan disisipkan.
ExecutionWorld
Dunia JavaScript untuk eksekusi skrip.
Enum
"ISOLATED"
Menentukan dunia yang terisolasi, yang merupakan lingkungan eksekusi unik untuk ekstensi ini.
"MAIN"
Menentukan dunia utama DOM, yang merupakan lingkungan eksekusi yang dibagikan dengan JavaScript halaman host.
InjectionResult
Properti
-
documentId
string
Chrome 106+Dokumen yang terkait dengan injeksi.
-
frameId
angka
Chrome 90 dan yang lebih baruFrame yang terkait dengan injeksi.
-
hasil
opsional
Hasil eksekusi skrip.
InjectionTarget
Properti
-
allFrames
boolean opsional
Apakah skrip harus dimasukkan ke semua bingkai dalam tab. Nilai defaultnya adalah false (salah). Nilai ini tidak boleh benar jika
frameIds
ditentukan. -
documentIds
string[] opsional
Chrome 106+ID dari documentId tertentu yang akan dimasukkan. Nilai ini tidak boleh ditetapkan jika
frameIds
telah ditetapkan. -
frameIds
number[] opsional
ID frame tertentu yang akan dimasukkan.
-
tabId
angka
ID tab yang akan dimasukkan.
RegisteredContentScript
Properti
-
allFrames
boolean opsional
Jika ditetapkan sebagai true, tindakan ini akan dimasukkan ke semua frame, meskipun frame tersebut bukan frame paling atas 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.
-
css
string[] opsional
Daftar file CSS yang akan dimasukkan ke halaman yang cocok. Ini dimasukkan dalam urutan kemunculannya dalam array ini, sebelum DOM dibuat atau ditampilkan untuk halaman tersebut.
-
excludeMatches
string[] opsional
Mengecualikan halaman tempat skrip konten ini akan dimasukkan ke dalamnya. Lihat Pola Pencocokan untuk 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 akan dimasukkan sesuai urutan kemunculannya dalam array ini.
-
matchOriginAsFallback
boolean opsional
Chrome 119+Menunjukkan apakah skrip dapat dimasukkan ke dalam bingkai tempat URL berisi skema yang tidak didukung; khususnya: about:, data:, blob:, atau filesystem:. Dalam kasus ini, origin URL akan diperiksa untuk menentukan apakah skrip harus dimasukkan atau tidak. Jika origin adalah
null
(seperti halnya untuk data: URL), origin yang digunakan adalah frame yang membuat frame saat ini atau frame yang memulai navigasi ke frame ini. Perhatikan bahwa ini mungkin bukan frame induk. -
cocok dengan
string[] opsional
Menentukan halaman tempat skrip konten akan dimasukkan. Lihat Pola Pencocokan untuk detail selengkapnya tentang sintaksis string ini. Harus ditentukan untuk
registerContentScripts
. -
persistAcrossSessions
boolean opsional
Menentukan apakah skrip konten ini akan terus ada di sesi mendatang. Nilai defaultnya adalah benar (true).
-
runAt
RunAt opsional
Menentukan kapan file JavaScript dimasukkan ke halaman web. Nilai default dan pilihan adalah
document_idle
. -
dunia
ExecutionWorld opsional
Chrome 102+"Dunia" JavaScript tempat skrip akan dijalankan. Default-nya adalah
ISOLATED
.
ScriptInjection
Properti
-
args
any[] 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. Tepat satu dari
files
ataufunc
harus ditentukan. -
injectImmediately
boolean opsional
Chrome 102+Apakah injeksi harus dipicu pada target sesegera mungkin. Perlu diketahui bahwa ini bukan jaminan bahwa injeksi akan terjadi sebelum pemuatan halaman, karena halaman mungkin telah dimuat pada saat skrip mencapai target.
-
target
Detail yang menentukan target tempat skrip akan dimasukkan.
-
dunia
ExecutionWorld opsional
Chrome 95 dan yang lebih baru"Dunia" JavaScript tempat skrip akan dijalankan. Default-nya adalah
ISOLATED
. -
func
membatalkan opsional
Chrome 92 dan yang lebih baruFungsi JavaScript yang akan dimasukkan. Fungsi ini akan diserialisasi, lalu dideserialisasi untuk injeksi. Ini berarti bahwa setiap parameter yang terikat dan konteks eksekusi akan hilang. Tepat satu dari
files
ataufunc
harus ditentukan.Fungsi
func
terlihat seperti:() => {...}
StyleOrigin
Origin untuk perubahan gaya. Lihat asal gaya untuk info selengkapnya.
Enum
"AUTHOR"
Metode
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
callback?: function,
)
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 mengevaluasi ke promise, browser akan menunggu promise untuk selesai dan menampilkan nilai yang dihasilkan.
Parameter
-
injeksi
Detail skrip yang akan dimasukkan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(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. Promise di-resolve dengan jenis yang sama 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:(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. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
insertCSS()
chrome.scripting.insertCSS(
injection: CSSInjection,
callback?: function,
)
Menyisipkan stylesheet CSS ke dalam konteks target. Jika beberapa frame ditentukan, suntikan yang gagal akan diabaikan.
Parameter
-
injeksi
Detail gaya yang akan disisipkan.
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
Hasil
-
Promise<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. Promise di-resolve dengan jenis yang sama 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 terjadi error selama penguraian skrip/validasi file, atau jika ID yang ditentukan sudah ada, berarti tidak ada skrip yang terdaftar.
-
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.
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 stylesheet yang tidak ada tidak akan dioperasikan. -
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.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Membatalkan pendaftaran skrip konten untuk ekstensi ini.
Parameter
-
filter
ContentScriptFilter opsional
Jika ditentukan, hanya pembatalan 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:() => 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.
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 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.