chrome.scripting

Deskripsi

Gunakan chrome.scripting API untuk mengeksekusi skrip dalam berbagai konteks.

Izin

scripting

Ketersediaan

Chrome 88+ MV3+

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"));

Catatan: Anda tidak dapat menentukan properti "frameIds" dan "allFrames" sekaligus.

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});
  }
}

Poin penting: Membatalkan pendaftaran skrip konten tidak akan menghapus skrip atau gaya yang telah dimasukkan.

Untuk mencoba chrome.scripting API, instal contoh pembuatan skrip dari repositori contoh ekstensi Chrome.

Jenis

ContentScriptFilter

Chrome 96 dan yang lebih baru

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 dan css harus ditentukan.

• file

  string[] opsional

  Jalur file CSS yang akan dimasukkan, relatif terhadap direktori utama ekstensi. Tepat salah satu dari files dan css harus ditentukan.

• asal

  StyleOrigin opsional

  Origin gaya untuk injeksi. Default-nya adalah 'AUTHOR'.

• target

  InjectionTarget

  Detail yang menentukan target tempat CSS akan disisipkan.

ExecutionWorld

Chrome 95 dan yang lebih baru

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 baru

  Frame 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

Chrome 96 dan yang lebih baru

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 baru

  Argumen 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 atau func 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

  InjectionTarget

  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 baru

  Fungsi 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 atau func harus ditentukan.

  Fungsi func terlihat seperti:

  ()=> {...}

StyleOrigin

Origin untuk perubahan gaya. Lihat asal gaya untuk info selengkapnya.

Enum

"AUTHOR"

Metode

executeScript()

Promise

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

  ScriptInjection

  Detail skrip yang akan dimasukkan.

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  (results: InjectionResult[])=>void

  • hasil

    InjectionResult[]

Hasil

• Promise<InjectionResult[]>

  Chrome 90 dan yang lebih baru

  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.

getRegisteredContentScripts()

Promise Chrome 96+

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

    RegisteredContentScript[]

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()

Promise

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

  CSSInjection

  Detail gaya yang akan disisipkan.

• callback

  fungsi opsional

  Parameter callback terlihat seperti:

  ()=>void

Hasil

• Promise<void>

  Chrome 90 dan yang lebih baru

  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.

registerContentScripts()

Promise Chrome 96+

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Mendaftarkan satu atau beberapa skrip konten untuk ekstensi ini.

Parameter

• skrip

  RegisteredContentScript[]

  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()

Promise Chrome 90+

chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

Menghapus stylesheet CSS yang sebelumnya disisipkan oleh ekstensi ini dari konteks target.

Parameter

• injeksi

  CSSInjection

  Detail gaya yang akan dihapus. Perhatikan bahwa properti css, files, dan origin harus sama persis dengan stylesheet yang disisipkan melalui insertCSS. 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()

Promise Chrome 96+

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()

Promise Chrome 96+

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Memperbarui satu atau beberapa skrip konten untuk ekstensi ini.

Parameter

• skrip

  RegisteredContentScript[]

  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.