Manifes - skrip konten

Kunci "content_scripts" menentukan file JavaScript atau CSS yang dimuat secara statis untuk digunakan setiap kali halaman dibuka yang cocok dengan pola URL tertentu. Ekstensi juga dapat memasukkan skrip konten secara terprogram. Lihat Memasukkan Skrip untuk mengetahui detailnya.

Manifes

Berikut adalah kunci yang didukung untuk "content_scripts". Hanya kunci "matches" dan "js" atau "css" yang diperlukan.

manifest.json

{
 "name": "My extension",
 ...
 "content_scripts": [
   {
     "matches": ["https://*.example.com/*"],
     "css": ["my-styles.css"],
     "js": ["content-script.js"],
     "exclude_matches": ["*://*/*foo*"],
     "include_globs": ["*example.com/???s/*"],
     "exclude_globs": ["*bar*"],     
     "all_frames": false,
     "match_origin_as_fallback": false,
     "match_about_blank": false,
     "run_at": "document_idle",
     "world": "ISOLATED",
   }
 ],
 ...
}

File

Setiap file harus berisi jalur relatif ke resource di direktori utama ekstensi. Garis miring di awal (/) akan otomatis dipangkas. Kunci "run_at" menentukan kapan setiap file akan dimasukkan.

"css" - Array
Opsional. Array jalur file CSS, yang dimasukkan dalam urutan array ini, dan sebelum konstruksi DOM atau rendering halaman terjadi.
"js" - Array,
Opsional. Array jalur file JavaScript, yang dimasukkan sesuai urutan kemunculannya dalam array ini, setelah file css dimasukkan. Setiap string dalam array harus berupa jalur relatif ke resource di direktori utama ekstensi. Garis miring di awal ('/') akan otomatis dipangkas.

URL yang cocok

Hanya properti "matches" yang wajib diisi. Kemudian, Anda dapat menggunakan "exclude_matches", "include_globs", dan "exclude_globs" untuk menyesuaikan URL mana yang akan diberi kode. Kunci "matches" akan memicu peringatan.

"matches" - Array
Wajib. Menentukan pola URL tempat skrip konten akan dimasukkan. Lihat Pola Pencocokan untuk sintaksis.
"exclude_matches" - Array
Opsional. Mengecualikan pola URL yang digunakan untuk memasukkan skrip konten. Lihat Pola Pencocokan untuk sintaksis.
"include_globs" - Array
Opsional. Diterapkan setelah kecocokan untuk hanya menyertakan URL yang juga cocok dengan glob ini. Dimaksudkan untuk mengemulasi kata kunci @include GreaseMonkey.
"exclude_globs" - Array
Opsional. Diterapkan setelah kecocokan untuk mengecualikan URL yang cocok dengan glob ini. Ditujukan untuk mengemulasi kata kunci @exclude GreaseMonkey.

URL Glob adalah URL yang berisi "karakter pengganti" * dan tanda tanya. Karakter pengganti * cocok dengan string dengan panjang berapa pun, termasuk string kosong, sedangkan tanda tanya ? cocok dengan karakter tunggal apa pun.

Skrip konten dimasukkan ke halaman jika:

  • URL-nya cocok dengan pola "matches" dan "include_globs".
  • Dan URL tersebut tidak cocok dengan pola "exclude_matches" atau "exclude_globs".

Contoh pencocokan URL dan Glob

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Kecocokan
https://www.example.com/foo/bar
https://the.example.com/foo/
Tidak cocok
https://my.example.com/foo/bar
https://example.com/foo/*
https://www.example.com/foo

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["*example.com/???s/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Kecocokan
https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html
Tidak cocok
https://www.example.com/sports/index.html
https://www.example.com/music/index.html

"exclude_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Kecocokan
https://history.example.com
https://.example.com/music
Tidak cocok
https://science.example.com
https://www.example.com/science

Contoh penyesuaian lanjutan

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*example.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Kecocokan
https://www.example.com/arts/index.html
https://.example.com/jobs/index.html
Tidak cocok
https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

Frame

Kunci "all_frames" menentukan apakah skrip konten harus dimasukkan ke semua frame yang cocok dengan persyaratan URL yang ditentukan. Jika ditetapkan ke false, nilai tersebut hanya akan dimasukkan ke frame paling atas. Fungsi ini dapat digunakan bersama dengan "match_about_blank" untuk dimasukkan ke dalam frame about:blank.

Untuk memasukkan ke dalam frame lain seperti data:, blob:, dan filesystem:, setel "match_origin_as_fallback" ke true. Untuk mengetahui detailnya, lihat Memasukkan frame terkait

Boolean "all_frames"
Opsional. Defaultnya adalah false, artinya hanya frame atas yang cocok. Jika disetel ke benar (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, dan tidak akan dimasukkan ke dalam frame turunan jika persyaratan URL tidak terpenuhi.
"match_about_blank"- Boolean
Opsional. Default-nya adalah false. Apakah skrip harus dimasukkan ke dalam frame about:blank tempat URL induk cocok dengan salah satu pola yang dideklarasikan di "matches".
"match_origin_as_fallback" - Boolean
Opsional. Default-nya adalah false. Apakah skrip harus dimasukkan dalam frame yang dibuat oleh asal yang cocok, tetapi URL atau asalnya mungkin tidak langsung cocok dengan pola. Ini termasuk frame dengan skema yang berbeda, seperti about:, data:, blob:, dan filesystem:.

Waktu proses dan lingkungan eksekusi

Secara default, skrip konten dimasukkan saat dokumen dan semua resource selesai dimuat, dan ditempatkan di lingkungan eksekusi pribadi yang terisolasi yang tidak dapat diakses oleh halaman atau ekstensi lainnya. Anda dapat mengubah setelan default ini pada kunci berikut:

"run_at" - document_start | document_end | document_idle
Opsional. Menentukan kapan skrip harus dimasukkan ke halaman. Ini sesuai dengan status pemuatan Document.readyState:
  • "document_start": DOM masih dimuat.
  • "document_end": resource halaman masih dimuat
  • "document_idle": DOM dan resource telah selesai dimuat. Ini adalah defaultnya.
"world" - ISOLATED | MAIN
Opsional. Dunia JavaScript untuk skrip yang akan dieksekusi. Defaultnya adalah "ISOLATED", yang merupakan lingkungan eksekusi unik untuk skrip konten. Memilih dunia "MAIN" berarti skrip akan berbagi lingkungan eksekusi dengan JavaScript halaman host. Lihat Bekerja di dunia yang terisolasi untuk mempelajari lebih lanjut.

Contoh

Lihat tutorial Menjalankan di setiap halaman untuk membangun ekstensi yang memasukkan skrip konten dalam manifes.