chrome.scripting

Deskripsi

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

Izin

scripting

Ketersediaan

Chrome 88 dan yang lebih baru MV3 dan yang lebih baru

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

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 diinjeksi. Hanya satu dari files dan css yang harus ditentukan.

  • file

    string[] opsional

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

  • asal

    StyleOrigin opsional

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

  • Detail yang menentukan target untuk menyisipkan CSS.

ExecutionWorld

Chrome 95 dan yang lebih baru

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 baru

    Dokumen yang terkait dengan injeksi.

  • frameId

    angka

    Chrome 90 dan yang lebih baru

    Frame 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 baru

    ID 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

Chrome 96 dan yang lebih baru

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 baru

    Menunjukkan 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 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. Hanya satu dari files atau func yang harus ditentukan.

  • injectImmediately

    boolean opsional

    Chrome 102 dan yang lebih baru

    Apakah 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.

  • 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 baru

    Fungsi 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 atau func 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()

Janji 
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

Hasil

  • Promise&lt;InjectionResult[]&gt;

    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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

getRegisteredContentScripts()

Janji Chrome 96 dan yang lebih baru 
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

Hasil

  • Promise&lt;RegisteredContentScript[]&gt;

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

Janji 
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

    CSSInjection

    Detail gaya yang akan disisipkan.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    () => void

Hasil

  • Janji<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. Tujuan promise yang di-resolve dengan jenis yang sama dengan yang diteruskan ke callback.

registerContentScripts()

Janji Chrome 96 dan yang lebih baru 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Mendaftarkan satu atau beberapa skrip konten untuk ekstensi ini.

Parameter

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

Janji Chrome 90 dan yang lebih baru 
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 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()

Janji Chrome 96 dan yang lebih baru 
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()

Janji Chrome 96 dan yang lebih baru 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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