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

Khoá "content_scripts" chỉ định một tệp JavaScript hoặc CSS được tải tĩnh để sử dụng mỗi khi một trang được mở khớp với một mẫu URL nhất định. 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 phần Chèn tập lệnh để biết thông tin chi tiết.

Tệp kê khai

Sau đây là các khoá được hỗ trợ cho "content_scripts". Chỉ cần khoá "matches" và "js" hoặc "css".

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

Tệp

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 (/) sẽ tự động bị cắt bớt. Khoá "run_at" chỉ định thời điểm chèn từng tệp.

"css" – Mảng

Không bắt buộc. Một mảng đường dẫn tệp CSS, được chèn theo thứ tự của mảng này và trước khi xảy ra bất kỳ quá trình tạo DOM hoặc hiển thị trang nào.

"js" – Mảng,

Không bắt buộc. Một mảng đường dẫn tệp JavaScript, được chèn theo thứ tự 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 bị cắt bớt.

URL trùng khớp

Bạn chỉ cần cung cấp thuộc tính "matches". Sau đó, bạn có thể sử dụng "exclude_matches", "include_globs" và "exclude_globs" để tuỳ chỉnh những URL cần chèn mã. Khoá "matches" sẽ kích hoạ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. Hãy xem phần Mẫu 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 khớp để biết cú pháp.

"include_globs" – Mảng

Không bắt buộc. Được áp dụng sau khi so khớp để chỉ bao gồm những URL cũng khớp với mẫu này. Nhằm mô phỏng từ khoá Greasemonkey @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 glob này. Dùng để mô phỏng từ khoá @exclude của Greasemonkey.

URL Glob là những URL 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, trong khi 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 trang 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ề glob 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"]
    }
  ],
  ...
}

Liên kết

https://www.example.com/foo/bar
https://the.example.com/foo/

Kết quả 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"]
    }
  ],
  ...
}

Liên kết

https://www.example.com/arts/index.html
https://www.example.com/jobs/index.html

Kết quả 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"]
    }
  ],
  ...
}

Liên kết

https://history.example.com
https://.example.com/music

Kết quả không khớp

https://science.example.com
https://www.example.com/science

Ví dụ về 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"]
    }
  ],
  ...
}

Liên kết

https://www.example.com/arts/index.html
https://.example.com/jobs/index.html

Kết quả 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 tập lệnh nội dung có được chèn vào tất cả khung khớp với các yêu cầu về URL đã chỉ định hay không. Nếu được đặt thành false, tập lệnh sẽ chỉ chèn vào khung trên cùng. Bạn có thể sử dụng API 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 vào các khung liên quan

"all_frames" Boolean

Không bắt buộc. Giá trị mặc định là false, nghĩa là chỉ khung trên cùng được so khớp. Nếu được đặt thành true, thì tập lệnh sẽ chèn vào tất cả các khung, ngay cả khi khung đó không phải là khung trên cùng trong thẻ. Mỗi khung được kiểm tra độc lập để đảm bảo đáp ứng các yêu cầu về URL. Tiện ích sẽ không chèn vào các 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. Liệu tập lệnh có nên chèn vào một khung about:blank nơi URL gốc 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. Liệu 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 khớp hay không, nhưng URL hoặc nguồn gốc của khung đó có thể không khớp trực tiếp với mẫu. Các khung này bao gồm khung có nhiều lược đồ, 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, tập lệnh nội dung được chèn khi tài liệu và tất cả tài nguyên đã tải xong, đồng thời hoạt động trong một môi trường thực thi riêng biệt mà trang hoặc các tiện ích khác không thể truy cập đượ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à tài nguyên đã tải xong. Đây là tuỳ chọn mặc định.

"world" – ISOLATED | MAIN

Không bắt buộc. Môi trường JavaScript để tập lệnh thực thi. 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. Khi chọn môi trường "MAIN", tập lệnh sẽ chia sẻ môi trường thực thi với JavaScript của trang lưu trữ. Hãy xem bài viết Làm việc trong môi trường tách biệt để tìm hiểu thêm.

Cảnh báo: Có rủi ro khi sử dụng môi trường "MAIN". Trang lưu trữ có thể truy cập và can thiệp vào tập lệnh được chèn. Hãy xem phần Làm việc trong môi trường tách biệt để tìm hiểu thêm.

Ví dụ

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