chrome.scripting

Deskripsi

Gunakan chrome.scripting API untuk menjalankan skrip dalam konteks yang berbeda.

Izin

scripting

Ketersediaan

Chrome 88+ MV3+

Manifes

Untuk menggunakan chrome.scripting API, deklarasikan izin "scripting" di manifes serta izin host untuk halaman yang akan disisipkan skripnya. 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 menyisipkan JavaScript dan CSS ke dalam situs. Hal ini mirip dengan 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 tempat JavaScript atau CSS akan disisipkan.

Satu-satunya kolom yang wajib diisi adalah tabId. Secara default, injeksi akan berjalan di frame utama 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 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 menyuntikkan ke dalam frame tertentu dari tab dengan menentukan ID frame individual. 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 disuntikkan

Ekstensi dapat menentukan kode yang akan disisipkan melalui file eksternal atau variabel runtime.

File

File ditentukan sebagai string yang merupakan jalur relatif ke direktori root ekstensi. Kode berikut akan menyuntikkan 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 menyuntikkan JavaScript dengan scripting.executeScript(), Anda dapat menentukan fungsi yang akan dieksekusi, 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 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 menyisipkan 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. Satu hasil disertakan per frame. Frame utama dijamin menjadi indeks pertama dalam array yang dihasilkan; semua frame lainnya berada dalam urutan non-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 yang dihasilkan dari eksekusi skrip adalah promise, Chrome akan menunggu hingga promise diselesaikan 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

Membatalkan pendaftaran semua skrip konten dinamis

Cuplikan berikut berisi fungsi yang membatalkan pendaftaran semua skrip konten dinamis yang sebelumnya didaftarkan oleh ekstensi.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await chrome.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return chrome.scripting.unregisterContentScripts({ ids: 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 repositori contoh ekstensi Chrome.

Jenis

ContentScriptFilter

Chrome 96+

Properti

  • ids

    string[] opsional

    Jika ditentukan, getRegisteredContentScripts hanya akan menampilkan skrip dengan ID yang ditentukan dalam daftar ini.

CSSInjection

Properti

  • css

    string opsional

    String yang berisi CSS yang akan disisipkan. Tepat satu dari files dan css harus ditentukan.

  • file

    string[] opsional

    Jalur file CSS yang akan disisipkan, relatif terhadap direktori root ekstensi. Tepat satu dari files dan css harus ditentukan.

  • asal

    StyleOrigin opsional

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

  • Detail yang menentukan target tempat CSS akan disisipkan.

ExecutionWorld

Chrome 95+

Dunia JavaScript untuk skrip yang akan dieksekusi di dalamnya.

Enum

"ISOLATED"
Menentukan dunia terisolasi, yang merupakan lingkungan eksekusi yang 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+

    Frame yang terkait dengan injeksi.

  • hasil

    opsional

    Hasil eksekusi skrip.

InjectionTarget

Properti

  • allFrames

    boolean opsional

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

  • documentIds

    string[] opsional

    Chrome 106+

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

  • frameIds

    number[] opsional

    ID frame tertentu yang akan disisipkan.

  • tabId

    angka

    ID tab yang akan disisipkan.

RegisteredContentScript

Chrome 96+

Properti

  • allFrames

    boolean opsional

    Jika ditentukan benar (true), kode akan disisipkan ke semua frame, meskipun frame tersebut bukan frame paling atas di tab. Setiap frame diperiksa secara independen untuk persyaratan URL; frame tidak akan disisipkan ke dalam frame turunan jika persyaratan URL tidak terpenuhi. Defaultnya adalah salah (false), yang berarti hanya frame teratas yang dicocokkan.

  • css

    string[] opsional

    Daftar file CSS yang akan disisipkan ke halaman yang cocok. Ini disisipkan dalam urutan kemunculannya dalam array ini, sebelum DOM dibuat atau ditampilkan untuk halaman.

  • excludeMatches

    string[] opsional

    Mengecualikan halaman yang seharusnya disisipkan 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 disisipkan ke halaman yang cocok. Objek ini disisipkan sesuai urutan kemunculannya dalam array ini.

  • matchOriginAsFallback

    boolean opsional

    Chrome 119+

    Menunjukkan apakah skrip dapat disisipkan ke dalam frame yang URL-nya berisi skema yang tidak didukung; khususnya: about:, data:, blob:, atau filesystem:. Dalam kasus ini, asal URL diperiksa untuk menentukan apakah skrip harus disisipkan. Jika originnya adalah null (seperti pada URL data), maka 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

    string[] opsional

    Menentukan halaman tempat skrip konten ini akan disisipkan. Lihat Pola Pencocokan untuk mengetahui detail selengkapnya tentang sintaksis string ini. Harus ditentukan 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 pilihan dan defaultnya adalah document_idle.

  • dunia

    ExecutionWorld opsional

    Chrome 102+

    "Dunia" JavaScript untuk menjalankan skrip. Default-nya adalah ISOLATED.

ScriptInjection

Properti

  • args

    any[] opsional

    Chrome 92+

    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 disisipkan, relatif terhadap direktori root ekstensi. Tepat satu dari files atau func harus ditentukan.

  • injectImmediately

    boolean opsional

    Chrome 102+

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

  • Detail yang menentukan target tempat skrip akan disisipkan.

  • dunia

    ExecutionWorld opsional

    Chrome 95+

    "Dunia" JavaScript untuk menjalankan skrip. Default-nya adalah ISOLATED.

  • func

    void opsional

    Chrome 92+

    Fungsi JavaScript yang akan disisipkan. Fungsi ini akan diserialkan, lalu dideserialkan untuk injeksi. Artinya, semua parameter terikat dan konteks eksekusi akan hilang. Tepat satu dari files atau func harus ditentukan.

    Fungsi func akan terlihat seperti: 

    () => {...}

StyleOrigin

Asal untuk perubahan gaya. Lihat asal gaya untuk mengetahui info selengkapnya.

Enum

"AUTHOR"

"USER"

Metode

executeScript()

chrome.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

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

Parameter

Hasil

getRegisteredContentScripts()

Chrome 96+ 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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 yang terdaftar secara dinamis di ekstensi.

Hasil

insertCSS()

chrome.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

Menyisipkan stylesheet CSS ke dalam konteks target. Jika beberapa frame ditentukan, injeksi yang tidak berhasil akan diabaikan.

Parameter

Hasil

  • Promise<void>

    Chrome 90+

registerContentScripts()

Chrome 96+ 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Mendaftarkan satu atau beberapa skrip konten untuk ekstensi ini.

Parameter

  • Berisi daftar skrip yang akan didaftarkan. Jika ada error selama parsing skrip/validasi file, atau jika ID yang ditentukan sudah ada, tidak ada skrip yang terdaftar.

Hasil

  • Promise<void>

removeCSS()

Chrome 90+ 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

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 melakukan apa pun.

Hasil

  • Promise<void>

unregisterContentScripts()

Chrome 96+ 
chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Membatalkan pendaftaran skrip konten untuk ekstensi ini.

Parameter

  • filter

    ContentScriptFilter opsional

    Jika ditentukan, hanya membatalkan pendaftaran skrip konten dinamis yang cocok dengan filter. Jika tidak, semua skrip konten dinamis ekstensi akan dibatalkan pendaftarannya.

Hasil

  • Promise<void>

updateContentScripts()

Chrome 96+ 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Memperbarui satu atau beberapa skrip konten untuk ekstensi ini.

Parameter

  • Berisi daftar skrip yang akan diperbarui. Properti hanya diperbarui untuk skrip yang ada jika ditentukan dalam objek ini. Jika terjadi error selama parsing skrip/validasi file, atau jika ID yang ditentukan tidak sesuai dengan skrip yang terdaftar sepenuhnya, tidak ada skrip yang diperbarui.

Hasil

  • Promise<void>