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",
   }
 ],
 ...
}

Files

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

"css" - Array
Opsional. Array jalur file CSS, 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 dalam direktori root ekstensi. Garis miring di awal ('/') otomatis dipangkas.

URL yang cocok

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

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

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

Skrip konten akan dimasukkan ke halaman jika:

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

Contoh pencocokan Globs dan URL

"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 sesuai dengan persyaratan URL yang ditentukan. Jika ditetapkan ke false, kode ini hanya akan dimasukkan ke frame paling atas. Kolom ini dapat digunakan bersama dengan "match_about_blank" untuk memasukkan ke dalam frame about:blank.

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

"all_frames" Boolean
Opsional. Defaultnya adalah false, artinya hanya frame teratas yang cocok. Jika disetel ke benar (true), tindakan ini akan dimasukkan ke semua frame, meskipun frame tersebut bukan frame teratas dalam tab. Setiap frame diperiksa secara terpisah untuk mengetahui persyaratan URL, frame tersebut 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 dalam "matches".
"match_origin_as_fallback" - Boolean
Opsional. Default-nya adalah false. Apakah skrip harus memasukkan frame yang dibuat oleh origin yang cocok, tetapi URL atau origin yang mungkin tidak cocok secara langsung dengan pola. Ini termasuk frame dengan skema 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 berada di lingkungan eksekusi yang terisolasi dan tidak dapat diakses oleh halaman atau ekstensi lainnya. Anda dapat mengubah setelan default ini di 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 eksekusi skrip. 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 terpencil untuk mempelajari lebih lanjut.

Contoh

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