chrome.devtools.inspectedWindow

Deskripsi

Gunakan chrome.devtools.inspectedWindow API 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, mengevaluasi kode dalam konteks jendela yang diperiksa, memuat ulang halaman, atau 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 chrome.tabs.* Panggilan API. Namun, perlu diketahui bahwa chrome.tabs.* API tidak diekspos ke Developer Tools karena pertimbangan keamanan—Anda harus meneruskan ID tab ke latar belakang dan panggil fungsi chrome.tabs.* API 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 setelah pemuatan halaman, atau untuk memaksa memuat ulang resource yang di-cache.

Gunakan panggilan getResources dan peristiwa onResourceContent untuk mendapatkan daftar resource (dokumen, stylesheet, skrip, gambar, dll.) dalam halaman yang diperiksa. getContent dan Metode setContent dari class Resource bersama dengan 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 mengeksekusi kode JavaScript dalam konteks halaman yang diperiksa. Metode ini efektif jika digunakan dalam konteks yang tepat dan berbahaya jika digunakan secara tidak tepat. Gunakan metode tabs.executeScript kecuali jika Anda memerlukan fungsi tertentu yang disediakan oleh metode eval.

Berikut adalah perbedaan utama antara metode eval dan tabs.executeScript:

  • Metode eval tidak menggunakan dunia yang terisolasi untuk kode yang dievaluasi, sehingga JavaScript status jendela yang diperiksa dapat diakses oleh kode. Gunakan metode ini saat mengakses Status JavaScript dari halaman yang diperiksa wajib diisi.
  • Konteks eksekusi kode yang dievaluasi mencakup API konsol Developer Tools. Misalnya, kode tersebut 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 (mungkin hanya berisi jenis JavaScript primitif dan asiklik referensi 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; suatu halaman berbahaya dapat memengaruhi data yang ditampilkan ke ekstensi.

Perhatikan bahwa halaman dapat menyertakan beberapa konteks eksekusi JavaScript yang berbeda. Setiap {i>frame<i} memiliki konteksnya sendiri, ditambah konteks tambahan untuk setiap ekstensi yang menjalankan skrip konten {i>frame<i}.

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

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

frameURL
Gunakan untuk menentukan bingkai selain bingkai utama halaman yang diperiksa.
contextSecurityOrigin
Gunakan untuk memilih konteks dalam bingkai yang ditentukan sesuai dengan asal webnya.
useContentScriptContext
Jika true (benar), jalankan skrip dalam konteks yang sama dengan skrip konten ekstensi. (Setara dengan yang menentukan asal web ekstensi itu sendiri sebagai asal keamanan konteks.) Model 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 devtools API dari chrome-extension-samples repositori resource.

Jenis

Resource

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

Properti

  • url

    string

    URL resource.

  • getContent

    void

    Mendapatkan konten resource.

    Fungsi getContent akan terlihat seperti ini: 

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

    • callback

      fungsi

      Parameter callback terlihat seperti ini: 

      (content: string, encoding: string) => void

      • konten

        string

        Konten resource (berpotensi dienkode).

      • encoding

        string

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

  • setContent

    void

    Menetapkan konten resource.

    Fungsi setContent akan terlihat seperti ini: 

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

    • konten

      string

      Konten baru referensi. Hanya resource dengan jenis teks yang saat ini didukung.

    • commit

      boolean

      True jika pengguna telah selesai mengedit resource, dan konten baru resource harus dipertahankan; false jika perubahan kecil ini akan dikirim saat pengguna mengedit resource.

    • callback

      fungsi opsional

      Parameter callback terlihat seperti ini: 

      (error?: object) => void

      • error

        objek opsional

        Disetel ke undefined (tidak ditentukan) jika konten resource berhasil disetel; menjelaskan {i>error<i} jika tidak.

Properti

tabId

ID tab yang sedang diperiksa. ID ini dapat digunakan dengan chrome.tabs.* Compute Engine API.

Jenis

angka

Metode

eval()

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

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

Parameter

  • ekspresi

    string

    Ekspresi yang akan dievaluasi.

  • opsi

    objek opsional

    Parameter opsi dapat berisi satu atau beberapa opsi.

    • frameURL

      string opsional

      Jika ditentukan, ekspresi akan dievaluasi di iframe yang URL-nya cocok dengan URL yang ditentukan. Secara default, ekspresi dievaluasi di bingkai atas halaman yang diperiksa.

    • scriptExecutionContext

      string opsional

      Chrome 107 dan yang lebih baru

      Evaluasi ekspresi dalam konteks skrip konten dari ekstensi yang cocok dengan origin yang ditentukan. Jika diberikan, skripExecutionContext akan mengganti nilai 'true' setelan di useContentScriptContext.

    • useContentScriptContext

      boolean opsional

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

  • callback

    fungsi opsional

    Parameter callback terlihat seperti ini: 

    (result: object, exceptionInfo: object) => void

    • hasil

      objek

      Hasil evaluasi.

    • exceptionInfo

      objek

      Objek yang memberikan detail jika terjadi pengecualian saat mengevaluasi ekspresi.

      • kode

        string

        Setel jika terjadi error di sisi DevTools sebelum ekspresi dievaluasi.

      • deskripsi

        string

        Setel jika terjadi error di sisi DevTools sebelum ekspresi dievaluasi.

      • detail

        setiap[]

        Disetel jika terjadi error 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

        Setel jika terjadi error di sisi DevTools sebelum ekspresi dievaluasi.

      • isException

        boolean

        Tetapkan jika kode yang dievaluasi menghasilkan pengecualian yang tidak tertangani.

      • nilai

        string

        Tetapkan jika kode yang dievaluasi menghasilkan pengecualian yang tidak tertangani.

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
)

Mengambil daftar resource dari halaman yang diperiksa.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

    (resources: Resource[]) => void

    • referensi

      Referensi[]

      Resource dalam halaman.

reload()

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

Memuat ulang halaman yang diperiksa.

Parameter

  • reloadOptions

    objek opsional

    • ignoreCache

      boolean opsional

      Jika benar, loader akan mengabaikan 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 Developer Tools.

    • injectedScript

      string opsional

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

    • userAgent

      string opsional

      Jika ditentukan, string akan mengganti nilai header HTTP User-Agent yang dikirim saat memuat resource halaman yang diperiksa. String ini juga akan mengganti 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 ini: 

    (resource: Resource) => void

onResourceContentCommitted

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

Diaktifkan saat revisi resource baru dilakukan (misalnya, pengguna menyimpan versi resource yang diedit di Developer Tools).

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti ini: 

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