Trang này được dịch bởi Cloud Translation API.

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ẽ được dùng mỗi khi người dùng mở một trang và 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 phần Chèn tập lệnh để biết chi tiết.

Tệp kê khai

Đây là các khoá được hỗ trợ cho "content_scripts". Chỉ yêu cầu khoá "matches" cùng với "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",
   }
 ],
 ...
}

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. 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 đường dẫn tệp CSS, được chèn theo thứ tự mảng này và trước khi diễn ra quá trình tạo hoặc hiển thị trang DOM.
"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ự 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ẽ được tự động cắt bớt.

URL phù hợp

Chỉ yêu cầu thuộc tính "matches". Sau đó, bạn có thể sử dụng "exclude_matches", "include_globs" và "exclude_globs" để tuỳ chỉnh các 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. 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. Không bao gồm các mẫu URL cần chèn tập lệnh nội dung. 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. Áp dụng sau các kết quả khớp để chỉ bao gồm những URL cũng khớp với toàn bộ cụm này. Đối với mục đích mô phỏng từ khoá @include Gr mâyPercent.
"exclude_globs" – Mảng: Không bắt buộc. Được áp dụng sau các kết quả khớp để loại trừ các URL khớp với toàn bộ cụm này. Đối với mục đích mô phỏng từ khoá @loại trừ Gr bịPercent.

URL toàn cầu 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 lớp này khớp với mọi mẫu "matches" và "include_globs".
Đồng thời, URL này không khớp với mẫu "exclude_matches" hoặc "exclude_globs".

Ví dụ về quả cầu và URL so khớp

`"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ề 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 liệu tập lệnh nội dung có cần được chèn vào tất cả khung hình phù hợp với yêu cầu đã chỉ định về URL hay không. Nếu bạn đặt thành false, thì hệ thống sẽ chỉ chèn vào khung trên cùng. Bạn có thể dùng đối tượng 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 khung 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ì thẻ này sẽ được chèn vào tất cả khung hình, ngay cả khi khung hình này không phải là khung trên cùng trong thẻ. Mỗi khung được kiểm tra độc lập theo các yêu cầu về URL và sẽ không được đưa 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. Liệu 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. Liệu tập lệnh có nên chèn vào khung được tạo bởi một nguồn gốc trùng khớp nhưng 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 giao thức 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, tập lệnh nội dung sẽ được đưa vào khi tài liệu và tất cả tài nguyên tải xong, đồng thời nằm trong một môi trường thực thi riêng tư mà 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 bằng các phím 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. Trạng thái này 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. Giá trị mặc định là "ISOLATED", là môi trường thực thi dành riêng cho tập lệnh nội dung. Khi chọn phiên bản "MAIN", tập lệnh sẽ chia sẻ môi trường thực thi với JavaScript của trang lưu trữ. Xem nội dung Làm việc trong thế giới tách biệt để tìm hiểu thêm.

Cảnh báo: Có những rủi ro đi kèm khi sử dụng thế giới "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 bài viết Làm việc trong thế giới 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 một tiện ích có khả năng chèn một tập lệnh nội dung trong tệp kê khai.