Manifes - skrip konten

Kunci "content_scripts" menentukan file JavaScript atau CSS yang dimuat secara statis untuk digunakan setiap kali halaman yang cocok dengan pola URL tertentu dibuka. 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 root 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 sesuai 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 root ekstensi. Garis miring di awal ('/') akan otomatis dipangkas.

Mencocokkan URL

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

"matches" - Array
Wajib. Menentukan pola URL yang akan dimasuki skrip konten. Lihat Pola Pencocokan untuk sintaksis.
"exclude_matches" - Array
Opsional. Mengecualikan pola URL untuk memasukkan skrip konten. Lihat Pola Pencocokan untuk sintaksis.
"include_globs" - Array
Opsional. Diterapkan setelah pencocokan untuk hanya menyertakan URL yang juga cocok dengan glob ini. Ditujukan untuk mengemulasi kata kunci Greasemonkey @include.
"exclude_globs" - Array
Opsional. Diterapkan setelah pencocokan 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 ? mencocokkan satu karakter.

Skrip konten dimasukkan ke halaman jika:

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

Contoh pencocokan glob 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 dalam semua frame yang cocok dengan persyaratan URL yang ditentukan. Jika ditetapkan ke false, skrip hanya akan dimasukkan ke dalam frame paling atas. API ini dapat digunakan bersama dengan "match_about_blank" untuk memasukkan ke dalam frame about:blank.

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

"all_frames" Boolean
Opsional. Nilai defaultnya adalah false, yang berarti hanya frame teratas yang dicocokkan. Jika ditetapkan ke true, skrip akan dimasukkan ke semua frame, meskipun frame tersebut bukan frame teratas di tab. Setiap frame diperiksa secara independen untuk 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 yang URL induknya cocok dengan salah satu pola yang dideklarasikan di "matches".
"match_origin_as_fallback" - Boolean
Opsional. Default-nya adalah false. Apakah skrip harus dimasukkan ke dalam frame yang dibuat oleh origin yang cocok, tetapi URL atau origin-nya mungkin tidak cocok secara langsung dengan pola. Ini termasuk frame dengan skema yang berbeda, seperti about:, data:, blob:, dan filesystem:.

Runtime dan lingkungan eksekusi

Secara default, skrip konten dimasukkan saat dokumen dan semua resource selesai dimuat, dan berada di lingkungan eksekusi terisolasi pribadi yang tidak dapat diakses oleh halaman atau ekstensi lain. 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. Peristiwa 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. Lingkungan JavaScript tempat skrip akan dieksekusi. Default-nya adalah "ISOLATED", yang merupakan lingkungan eksekusi unik untuk skrip konten. Memilih world "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 membuat ekstensi yang memasukkan skrip konten dalam manifes.