Tệp kê khai – tập lệnh nội dung

Khoá "content_scripts" chỉ định một tệp JavaScript hoặc CSS tải tĩnh để sử dụng mỗi khi mở một trang khớp với một mẫu URL nhất định. Các tiện ích cũng có thể chèn tập lệnh nội dung theo phương thức lập trình. Hãy xem bài viết Chèn tập lệnh để biết thông tin chi tiết.

Tệp kê khai

Đây là những khoá được hỗ trợ cho "content_scripts". Chỉ có khoá "matches" và "js" hoặc "css" là bắt buộc.

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

Mỗi tệp phải chứa một đường dẫn tương đối đến một tài nguyên trong thư mục gốc của tiện ích. Dấu gạch chéo ở đầu (/) được tự động cắt bỏ. Khoá "run_at" chỉ định thời điểm chèn mỗi tệp.

"css" – Mảng
Không bắt buộc. Một mảng các đường dẫn tệp CSS, được chèn theo thứ tự của mảng này và trước khi quá trình tạo DOM hoặc hiển thị trang diễn ra.
"js" – Mảng,
Không bắt buộc. Một mảng các đường dẫn tệp JavaScript, được chèn theo thứ tự chúng xuất hiện trong mảng này, sau khi các tệp css được chèn. Mỗi chuỗi trong mảng phải là một đường dẫn tương đối đến một tài nguyên trong thư mục gốc của tiện ích. Dấu gạch chéo ở đầu ("/") sẽ tự động được cắt bỏ.

URL trùng khớp

Chỉ có thuộc tính "matches" là bắt buộc. Sau đó, bạn có thể sử dụng "exclude_matches", "include_globs" và "exclude_globs" để tuỳ chỉnh URL cần chèn mã. Khoá "matches" sẽ kích hoạt một cảnh báo.

"matches" – Mảng
Bắt buộc. Chỉ định mẫu URL để chèn tập lệnh nội dung vào. Hãy xem phần Mẫu so khớp để biết cú pháp.
"exclude_matches" – Mảng
Không bắt buộc. Loại trừ các mẫu URL để chèn tập lệnh nội dung vào. Hãy xem phần Mẫu so khớp để biết cú pháp.
"include_globs" – Mảng
Không bắt buộc. Được áp dụng sau các kết quả trùng khớp để chỉ bao gồm những URL cũng khớp với cụm cầu này. Nhằm mô phỏng từ khoá Greaseil @include.
"exclude_globs" – Mảng
Không bắt buộc. Được áp dụng sau khi so khớp để loại trừ những URL khớp với cụm cầu này. Nhằm mô phỏng từ khoá @excluded Greasesh.

URL glob là những URL có chứa "ký tự đại diện" * và dấu chấm hỏi. Ký tự đại diện * khớp với mọi chuỗi có độ dài bất kỳ, kể cả chuỗi trống, còn dấu chấm hỏi ? khớp với bất kỳ ký tự đơn nào.

Tập lệnh nội dung được chèn vào một trang nếu:

  • URL của mẫu này khớp với mọi mẫu "matches" và "include_globs".
  • Và URL không khớp với mẫu "exclude_matches" hoặc "exclude_globs".

Ví dụ về cụm từ tìm kiếm động và so khớp URL

"include_globs"

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "include_globs": ["https://???.example.com/foo/*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Khớp với
https://www.example.com/foo/bar
https://the.example.com/foo/
Không khớp
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"]
    }
  ],
  ...
}
Khớp với
https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html
Không khớp
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"]
    }
  ],
  ...
}
Khớp với
https://history.example.com
https://.example.com/music
Không khớp
https://science.example.com
https://www.example.com/science

Ví dụ về cách tuỳ chỉnh nâng cao

manifest.json

{
  ...
  "content_scripts": [
    {
      "matches": ["https://*.example.com/*"],
      "exclude_matches": ["*://*/*business*"],
      "include_globs": ["*example.com/???s/*"],
      "exclude_globs": ["*science*"],
      "js": ["content-script.js"]
    }
  ],
  ...
}
Khớp với
https://www.example.com/arts/index.html
https://.example.com/jobs/index.html
Không khớp
https://science.example.com
https://www.example.com/jobs/business
https://www.example.com/science

Khung

Khoá "all_frames" chỉ định xem có nên chèn tập lệnh nội dung vào tất cả các khung phù hợp với các yêu cầu về URL đã chỉ định hay không. Nếu bạn đặt thành false, thì hệ thống sẽ chỉ chèn khung hình trên cùng. Bạn có thể sử dụng hàm này cùng với "match_about_blank" để chèn vào khung about:blank.

Để chèn vào các khung khác như data:, blob: và filesystem:, hãy đặt "match_origin_as_fallback" thành true. Để biết thông tin chi tiết, hãy xem phần Chèn các khung có liên quan

Boolean "all_frames"
Không bắt buộc. Giá trị mặc định là false, nghĩa là chỉ khung hình trên cùng được khớp. Nếu bạn đặt chính sách này thành true, thì hệ thống sẽ chèn khung hình này vào tất cả các khung hình, ngay cả khi khung hình không phải là khung hình trên cùng trong thẻ. Mỗi khung hình được kiểm tra độc lập để đảm bảo các yêu cầu về URL, và khung đó sẽ không chèn vào khung con nếu không đáp ứng các yêu cầu về URL.
"match_about_blank" – Boolean
Không bắt buộc. Mặc định là false. Tập lệnh có nên chèn vào khung about:blank, nơi URL mẹ khớp với một trong các mẫu được khai báo trong "matches" hay không.
"match_origin_as_fallback" – Boolean
Không bắt buộc. Mặc định là false. Tập lệnh có nên chèn vào các khung được tạo bởi một nguồn gốc phù hợp nhưng có URL hoặc nguồn gốc có thể không khớp trực tiếp với mẫu hay không. Các khung này bao gồm các khung có giao thức khác nhau, chẳng hạn như about:, data:, blob: và filesystem:.

Thời gian chạy và môi trường thực thi

Theo mặc định, các tập lệnh nội dung được đưa vào khi tài liệu và tất cả tài nguyên đã tải xong và nằm trong một môi trường thực thi riêng tư tách biệt không thể truy cập vào trang hoặc các tiện ích khác. Bạn có thể thay đổi các giá trị mặc định này trong các khoá sau:

"run_at" – document_start | document_end | document_idle
Không bắt buộc. Chỉ định thời điểm chèn tập lệnh vào trang. Nó tương ứng với các trạng thái tải của Document.readyState:
  • "document_start": DOM vẫn đang tải.
  • "document_end": tài nguyên của trang vẫn đang tải
  • "document_idle": DOM và các tài nguyên đã tải xong. Đây là tuỳ chọn mặc định.
"world" – ISOLATED | MAIN
Không bắt buộc. Thế giới JavaScript để thực thi một tập lệnh bên trong. Giá trị mặc định là "ISOLATED", đây là môi trường thực thi duy nhất cho tập lệnh nội dung. Việc chọn môi trường "MAIN" có nghĩa là tập lệnh sẽ chia sẻ môi trường thực thi với JavaScript của trang lưu trữ. Xem bài viết Làm việc trong những môi trường tách biệt để tìm hiểu thêm.

Ví dụ:

Xem hướng dẫn Chạy trên mọi trang để tạo tiện ích sẽ chèn tập lệnh nội dung vào tệp kê khai.