chrome.devtools.inspectedWindow

Deskripsi

Gunakan API chrome.devtools.inspectedWindow untuk berinteraksi dengan jendela yang diperiksa: dapatkan ID tab untuk halaman yang diperiksa, evaluasi kode dalam konteks jendela yang diperiksa, muat ulang halaman, atau dapatkan daftar resource dalam halaman.

Manifes

Kunci berikut harus dideklarasikan dalam manifes untuk menggunakan API ini.

"devtools_page"

Gunakan chrome.devtools.inspectedWindow untuk berinteraksi dengan jendela yang diperiksa: dapatkan ID tab untuk halaman yang diperiksa, evaluasi kode dalam konteks jendela yang diperiksa, muat ulang halaman, atau dapatkan daftar resource dalam halaman.

Lihat Ringkasan API DevTools untuk pengantar umum tentang penggunaan API Developer Tools.

Ringkasan

Properti tabId menyediakan ID tab yang dapat Anda gunakan dengan panggilan API chrome.tabs.*. Namun, perhatikan bahwa API chrome.tabs.* tidak diekspos ke halaman ekstensi Alat Developer karena pertimbangan keamanan—Anda harus meneruskan ID tab ke halaman latar belakang dan memanggil fungsi API chrome.tabs.* dari sana.

Metode reload dapat digunakan untuk memuat ulang halaman yang diperiksa. Selain itu, pemanggil dapat menentukan penggantian untuk string agen pengguna, skrip yang akan dimasukkan lebih awal saat pemuatan halaman, atau opsi untuk memuat ulang paksa resource yang di-cache.

Gunakan panggilan getResources dan peristiwa onResourceContent untuk mendapatkan daftar resource (dokumen, stylesheet, skrip, gambar, dll.) dalam halaman yang diperiksa. Metode getContent dan setContent dari class Resource beserta peristiwa onResourceContentCommitted dapat digunakan untuk mendukung modifikasi konten resource, misalnya, oleh editor eksternal.

Mengeksekusi Kode di Jendela yang Diperiksa

Metode eval memberikan kemampuan bagi ekstensi untuk menjalankan kode JavaScript dalam konteks halaman yang diperiksa. Metode ini sangat efektif jika digunakan dalam konteks yang tepat dan berbahaya jika digunakan secara tidak tepat. Gunakan metode tabs.executeScript kecuali jika Anda memerlukan fungsi spesifik yang disediakan oleh metode eval.

Berikut perbedaan utama antara metode eval dan tabs.executeScript:

  • Metode eval tidak menggunakan dunia terisolasi untuk kode yang dievaluasi, sehingga status JavaScript jendela yang diperiksa dapat diakses oleh kode. Gunakan metode ini jika akses ke status JavaScript halaman yang diperiksa diperlukan.
  • Konteks eksekusi kode yang dievaluasi mencakup API konsol Alat Developer. Misalnya, kode dapat menggunakan inspect dan $0.
  • Kode yang dievaluasi dapat menampilkan nilai yang diteruskan ke callback ekstensi. Nilai yang ditampilkan harus berupa objek JSON yang valid (hanya dapat berisi jenis JavaScript primitif dan referensi asiklik ke objek JSON lainnya). Harap berhati-hati saat memproses data yang diterima dari halaman yang diperiksa—konteks eksekusi pada dasarnya dikontrol oleh halaman yang diperiksa; halaman berbahaya dapat memengaruhi data yang dikembalikan ke ekstensi.

Perhatikan bahwa halaman dapat menyertakan beberapa konteks eksekusi JavaScript yang berbeda. Setiap frame memiliki konteksnya sendiri, ditambah konteks tambahan untuk setiap ekstensi yang menjalankan skrip konten di frame tersebut.

Secara default, metode eval dijalankan dalam konteks frame utama halaman yang diperiksa.

Metode eval mengambil argumen kedua opsional yang dapat Anda gunakan untuk menentukan konteks tempat kode dievaluasi. Objek options ini dapat berisi satu atau beberapa kunci berikut:

frameURL
Gunakan untuk menentukan frame selain frame utama halaman yang diperiksa.
contextSecurityOrigin
Digunakan untuk memilih konteks dalam frame yang ditentukan sesuai dengan origin web-nya.
useContentScriptContext
Jika benar, jalankan skrip dalam konteks yang sama dengan skrip konten ekstensi. (Setara dengan menentukan origin web ekstensi itu sendiri sebagai origin keamanan konteks.) Hal ini dapat digunakan untuk bertukar data dengan skrip konten.

Contoh

Kode berikut memeriksa versi jQuery yang digunakan oleh halaman yang diperiksa:

chrome.devtools.inspectedWindow.eval(
  "jQuery.fn.jquery",
  function(result, isException) {
    if (isException) {
      console.log("the page is not using jQuery");
    } else {
      console.log("The page is using jQuery v" + result);
    }
  }
);

Untuk mencoba API ini, instal contoh API devtools dari repositori chrome-extension-samples.

Jenis

Resource

Resource dalam halaman yang diperiksa, seperti dokumen, skrip, atau gambar.

Properti

  • url

    string

    URL resource.

  • getContent

    void

    Janji

    Mendapatkan konten resource.

    Fungsi getContent akan terlihat seperti: 

    (callback?: function) => {...}

    • callback

      fungsi opsional

      Parameter callback terlihat seperti: 

      (response: object) => void

      • respons

        objek

        Tertunda

        Objek yang berisi konten resource dan encoding-nya.

        • konten

          string

          Isi resource (berpotensi dienkode).

        • encoding

          string

          Kosong jika konten tidak dienkode, nama encoding jika tidak. Saat ini, hanya base64 yang didukung.

    • return

      Promise<object>

      Tertunda

      Fungsi yang menerima konten resource saat permintaan selesai.

      Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.

  • setContent

    void

    Janji

    Menetapkan konten resource.

    Fungsi setContent akan terlihat seperti: 

    (content: string, commit: boolean, callback?: function) => {...}

    • konten

      string

      Konten baru resource. Saat ini hanya resource dengan jenis teks yang didukung.

    • commit

      boolean

      Benar (true) jika pengguna telah selesai mengedit resource, dan konten baru resource harus dipertahankan; salah (false) jika ini adalah perubahan kecil yang dikirim saat pengguna mengedit resource.

    • callback

      fungsi opsional

      Parameter callback terlihat seperti: 

      (error?: object) => void

      • error

        objek opsional

        Ditetapkan ke undefined jika konten resource berhasil ditetapkan; menjelaskan error jika tidak.

    • return

      Promise<object>

      Tertunda

      Fungsi yang dipanggil setelah penyelesaian permintaan.

      Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.

Properti

tabId

ID tab yang sedang diperiksa. ID ini dapat digunakan dengan chrome.tabs.* Natural Language API.

Jenis

angka

Metode

eval()

Janji 
chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): Promise<object>

Mengevaluasi ekspresi JavaScript dalam konteks frame utama halaman yang diperiksa. Ekspresi harus dievaluasi ke objek yang sesuai dengan JSON, jika tidak, pengecualian akan dilempar. Fungsi eval dapat melaporkan error sisi DevTools atau pengecualian JavaScript yang terjadi selama evaluasi. Dalam kedua kasus tersebut, parameter result dari callback adalah undefined. Jika terjadi error di sisi DevTools, parameter isException tidak null dan memiliki isError yang disetel ke benar (true) dan code yang disetel ke kode error. Jika terjadi error JavaScript, isException disetel ke benar (true) dan value disetel ke nilai string dari objek yang dilempar.

Parameter

  • ekspresi

    string

    Ekspresi yang akan dievaluasi.

  • opsi

    objek opsional

    Parameter opsi dapat berisi satu atau beberapa opsi.

    • frameURL

      string opsional

      Jika ditentukan, ekspresi dievaluasi pada iframe yang URL-nya cocok dengan yang ditentukan. Secara default, ekspresi dievaluasi di frame teratas halaman yang diperiksa.

    • scriptExecutionContext

      string opsional

      Chrome 107+

      Mengevaluasi ekspresi dalam konteks skrip konten ekstensi yang cocok dengan asal yang ditentukan. Jika diberikan, scriptExecutionContext akan menggantikan setelan 'true' pada useContentScriptContext.

    • useContentScriptContext

      boolean opsional

      Mengevaluasi ekspresi dalam konteks skrip konten ekstensi panggilan, asalkan skrip konten sudah dimasukkan ke halaman yang diperiksa. Jika tidak, ekspresi tidak dievaluasi dan callback dipanggil dengan parameter pengecualian yang ditetapkan ke objek yang memiliki kolom isError yang ditetapkan ke benar (true) dan kolom code yang ditetapkan ke E_NOTFOUND.

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (response: object) => void

    • respons

      objek

      Tertunda

      Hasil evaluasi dan informasi pengecualian.

      • exceptionInfo

        objek

        Objek yang memberikan detail jika terjadi pengecualian saat mengevaluasi ekspresi.

        • kode

          string

          Menetapkan apakah error terjadi di sisi DevTools sebelum ekspresi dievaluasi.

        • deskripsi

          string

          Menetapkan apakah error terjadi di sisi DevTools sebelum ekspresi dievaluasi.

        • detail

          any[]

          Menetapkan apakah error terjadi di sisi DevTools sebelum ekspresi dievaluasi, berisi array nilai yang dapat diganti ke dalam string deskripsi untuk memberikan informasi selengkapnya tentang penyebab error.

        • isError

          boolean

          Menetapkan apakah error terjadi di sisi DevTools sebelum ekspresi dievaluasi.

        • isException

          boolean

          Ditetapkan jika kode yang dievaluasi menghasilkan pengecualian yang tidak tertangani.

        • nilai

          string

          Ditetapkan jika kode yang dievaluasi menghasilkan pengecualian yang tidak tertangani.

      • hasil

        objek

        Hasil evaluasi.

Hasil

  • Promise<object>

    Tertunda

    Fungsi yang dipanggil saat evaluasi selesai.

    Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.

getResources()

Janji 
chrome.devtools.inspectedWindow.getResources(
  callback?: function,
): Promise<Resource[]>

Mengambil daftar resource dari halaman yang diperiksa.

Parameter

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (resources: Resource[]) => void

    • referensi

      Resource[]

      Aset dalam halaman.

Hasil

  • Promise<Resource[]>

    Tertunda

    Fungsi yang menerima daftar resource saat permintaan selesai.

    Promise hanya didukung untuk Manifest V3 dan yang lebih baru, platform lain harus menggunakan callback.

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

Memuat ulang halaman yang diperiksa.

Parameter

  • reloadOptions

    objek opsional

    • ignoreCache

      boolean opsional

      Jika benar, loader akan melewati cache untuk semua resource halaman yang diperiksa dan dimuat sebelum peristiwa load diaktifkan. Efeknya mirip dengan menekan Ctrl+Shift+R di jendela yang diperiksa atau di dalam jendela Alat Developer.

    • injectedScript

      string opsional

      Jika ditentukan, skrip akan disisipkan ke setiap frame halaman yang diperiksa segera setelah dimuat, sebelum skrip frame mana pun. Skrip tidak akan disisipkan setelah pemuatan ulang berikutnya—misalnya, jika pengguna menekan Ctrl+R.

    • userAgent

      string opsional

      Jika ditentukan, string akan menggantikan nilai header HTTP User-Agent yang dikirim saat memuat resource halaman yang diperiksa. String ini juga akan menggantikan nilai properti navigator.userAgent yang ditampilkan ke skrip apa pun yang berjalan dalam halaman yang diperiksa.

Acara

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

Diaktifkan saat resource baru ditambahkan ke halaman yang diperiksa.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (resource: Resource) => void

onResourceContentCommitted

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

Diaktifkan saat revisi baru resource di-commit (misalnya, pengguna menyimpan versi resource yang diedit di Alat Developer).

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

    (resource: Resource, content: string) => void