Mỗi tiện ích đều phải có một tệp manifest.json trong thư mục gốc, trong đó liệt kê thông tin quan trọng về cấu trúc và hành vi của tiện ích đó.
Trang này giải thích cấu trúc của tệp kê khai tiện ích và các tính năng mà tệp kê khai có thể bao gồm.
Ví dụ
Các tệp kê khai ví dụ sau đây cho thấy cấu trúc cơ bản của tệp kê khai và một số tính năng thường dùng làm điểm xuất phát để tạo tệp kê khai của riêng bạn:
Tệp kê khai tối thiểu
{
"manifest_version": 3,
"name": "Minimal Manifest",
"version": "1.0.0",
"description": "A basic example extension with only required keys",
"icons": {
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
}
Đăng ký tập lệnh nội dung
{
"manifest_version": 3,
"name": "Run script automatically",
"description": "Runs a script on www.example.com automatically when user installs the extension",
"version": "1.0",
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
},
"content_scripts": [
{
"js": [
"content-script.js"
],
"matches": [
"http://*.example.com//"
]
}
]
}
Chèn tập lệnh nội dung
{
"manifest_version": 3,
"name": "Click to run",
"description": "Runs a script when the user clicks the action toolbar icon.",
"version": "1.0",
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
},
"background": {
"service_worker": "service-worker.js"
},
"action": {
"default_icon": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
}
},
"permissions": ["scripting", "activeTab"]
}
Cửa sổ bật lên có quyền
{
"manifest_version": 3,
"name": "Popup extension that requests permissions",
"description": "Extension that includes a popup and requests host permissions and storage permissions.",
"version": "1.0",
"icons": {
"16": "images/icon-16.png",
"32": "images/icon-32.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
},
"action": {
"default_popup": "popup.html"
},
"host_permissions": [
"https://*.example.com/"
],
"permissions": [
"storage"
]
}
Bảng điều khiển bên
{
"manifest_version": 3,
"name": "Side panel extension",
"version": "1.0",
"description": "Extension with a default side panel.",
"icons": {
"16": "images/icon-16.png",
"48": "images/icon-48.png",
"128": "images/icon-128.png"
},
"side_panel": {
"default_path": "sidepanel.html"
},
"permissions": ["sidePanel"]
}
Khoá tệp kê khai
Sau đây là danh sách tất cả các khoá tệp kê khai được hỗ trợ.
Các khoá mà nền tảng Tiện ích yêu cầu
"manifest_version"- Một số nguyên chỉ định phiên bản của định dạng tệp kê khai mà tiện ích của bạn sử dụng. Giá trị được hỗ trợ duy nhất là
3. "name"- Một chuỗi xác định tiện ích trong Cửa hàng Chrome trực tuyến, hộp thoại cài đặt và trang Tiện ích của Chrome của người dùng (
chrome://extensions). Chiều dài tối đa là 75 ký tự. Để biết thông tin về cách sử dụng tên theo ngôn ngữ, hãy xem phần Quốc tế hoá. "version"- Một chuỗi xác định số phiên bản của tiện ích. Để biết thông tin về định dạng số phiên bản, hãy xem phần Phiên bản.
Khoá do Cửa hàng Chrome trực tuyến yêu cầu
"description"- Một chuỗi mô tả tiện ích trên cả Cửa hàng Chrome trực tuyến và trang quản lý tiện ích của người dùng. Độ dài tối đa là 132 ký tự. Để biết thông tin về cách bản địa hoá nội dung mô tả, hãy xem phần Quốc tế hoá.
"icons"- Một hoặc nhiều biểu tượng đại diện cho tiện ích của bạn. Để biết thông tin về các phương pháp hay nhất, hãy xem phần Icons.
Khoá không bắt buộc
"action"- Xác định giao diện và hành vi của biểu tượng tiện ích trên Thanh công cụ của Google. Để biết thêm thông tin, hãy xem
chrome.action. "background"- Chỉ định tệp JavaScript chứa trình chạy dịch vụ của tiện ích. Trình chạy dịch vụ này đóng vai trò là một trình xử lý sự kiện. Để biết thêm thông tin, hãy xem bài viết Giới thiệu về trình chạy dịch vụ của tiện ích.
"chrome_settings_overrides"- Xác định các chế độ ghi đè cho một số chế độ cài đặt của Chrome. Để biết thêm thông tin, hãy xem bài viết Ghi đè các chế độ cài đặt của Chrome.
"chrome_url_overrides"- Xác định các chế độ ghi đè cho các trang mặc định của Chrome. Để biết thêm thông tin, hãy xem bài viết Ghi đè các trang của Chrome.
"commands"- Xác định các phím tắt trong tiện ích. Để biết thêm thông tin, hãy xem chrome.commands.
"content_scripts"- Chỉ định các tệp JavaScript hoặc CSS sẽ được dùng khi người dùng mở một số trang web. Để biết thêm thông tin, hãy xem bài viết Tập lệnh nội dung.
"content_security_policy"- Xác định các quy định hạn chế về tập lệnh, kiểu và các tài nguyên khác mà một tiện ích có thể sử dụng. Để biết thêm thông tin, hãy xem Chính sách bảo mật nội dung.
"cross_origin_embedder_policy"- Chỉ định một giá trị cho tiêu đề HTTP Cross-Origin-Embedder-Policy. Tiêu đề này định cấu hình việc nhúng tài nguyên từ nhiều nguồn gốc vào một trang tiện ích.
"cross_origin_opener_policy"- Chỉ định một giá trị cho tiêu đề HTTP Cross-Origin-Opener-Policy. Tiêu đề này giúp bạn đảm bảo rằng trang tiện ích cấp cao nhất không dùng chung nhóm bối cảnh duyệt web với các tài liệu trên nhiều nguồn gốc.
"declarative_net_request"- Xác định các quy tắc tĩnh cho API declarativeNetRequest. API này cho phép chặn và sửa đổi các yêu cầu mạng.
"default_locale"- Một chuỗi xác định ngôn ngữ mặc định của một tiện ích hỗ trợ nhiều ngôn ngữ. Ví dụ: "en" và "pt_BR". Khoá này là bắt buộc trong các tiện ích được bản địa hoá và không được dùng trong các tiện ích không được bản địa hoá. Để biết thêm thông tin, hãy xem phần Quốc tế hoá.
"devtools_page"- Xác định những trang sử dụng các API DevTools.
"export"- Cho phép xuất tài nguyên từ tiện ích. Để biết thêm thông tin, hãy xem phần Xuất.
"externally_connectable"- Xác định những trang và tiện ích khác có thể kết nối với tiện ích của bạn. Để biết thêm thông tin, hãy xem
"externally_connectable". "homepage_url"- Một chuỗi chỉ định URL cho trang chủ của tiện ích. Nếu bạn không xác định trang chủ, thì trang chủ sẽ mặc định là trang Cửa hàng Chrome trực tuyến của tiện ích. Trường này đặc biệt hữu ích nếu bạn lưu trữ tiện ích trên trang web của riêng mình.
"host_permissions"- Liệt kê các trang web mà tiện ích của bạn được phép tương tác, được xác định bằng cách sử dụng mẫu so khớp URL. Sự cho phép của người dùng đối với những trang web này được yêu cầu tại thời điểm cài đặt. Để biết thêm thông tin, hãy xem phần Quyền của người tổ chức.
"import"- Cho phép nhập tài nguyên vào tiện ích. Để biết thêm thông tin, hãy xem phần Nhập.
"incognito"- Xác định cách tiện ích hoạt động ở chế độ ẩn danh. Các giá trị được hỗ trợ là
"spanning","split"và"not_allowed". Để biết thêm thông tin, hãy xem phần Chế độ ẩn danh. "key"- Chỉ định mã nhận dạng của tiện ích cho nhiều trường hợp sử dụng trong quá trình phát triển. Để biết thêm thông tin, hãy xem phần Khoá.
"minimum_chrome_version"- Xác định phiên bản Chrome cũ nhất có thể cài đặt tiện ích của bạn. Giá trị phải là một chuỗi con của một chuỗi phiên bản trình duyệt Chrome hiện có, chẳng hạn như
"107"hoặc"107.0.5304.87". Người dùng sử dụng các phiên bản Chrome cũ hơn phiên bản tối thiểu sẽ thấy cảnh báo "Không tương thích" trong Cửa hàng Chrome trực tuyến và không thể cài đặt tiện ích của bạn. Nếu bạn thêm thông tin này vào một tiện ích hiện có, thì những người dùng có phiên bản Chrome cũ hơn sẽ không nhận được bản cập nhật tự động cho tiện ích của bạn. Quy tắc này áp dụng cho cả người dùng doanh nghiệp ở chế độ tạm thời. "oauth2"- Cho phép sử dụng mã nhận dạng bảo mật OAuth 2.0. Giá trị của khoá này phải là một đối tượng có các thuộc tính
"client_id"và"scopes". Để biết thông tin chi tiết, hãy xem hướng dẫn về OAuth 2.0. "omnibox"- Cho phép tiện ích đăng ký một từ khoá trong thanh địa chỉ của Chrome. Để biết thêm thông tin, hãy xem phần Omnibox.
"optional_host_permissions"- Khai báo quyền của máy chủ lưu trữ không bắt buộc cho tiện ích của bạn.
"optional_permissions"- Khai báo các quyền không bắt buộc cho tiện ích của bạn.
"options_page"- Chỉ định đường dẫn đến tệp options.html để tiện ích sử dụng làm trang tuỳ chọn. Để biết thêm thông tin, hãy xem phần Cung cấp cho người dùng các lựa chọn.
"options_ui"- Chỉ định đường dẫn đến một tệp HTML cho phép người dùng thay đổi các lựa chọn về tiện ích trên trang Tiện ích của Chrome. Để biết thêm thông tin, hãy xem phần Các lựa chọn nhúng.
"permissions"- Cho phép sử dụng các API tiện ích cụ thể. Hãy xem phần Quyền để biết nội dung giải thích chung. Các trang tham chiếu cho từng API liệt kê những quyền mà API đó yêu cầu.
"requirements"- Liệt kê các công nghệ cần thiết để sử dụng tiện ích. Để xem danh sách các yêu cầu được hỗ trợ, hãy xem phần Yêu cầu.
"sandbox"- Xác định một nhóm trang tiện ích không có quyền truy cập vào API tiện ích hoặc quyền truy cập trực tiếp vào các trang không được hộp cát bảo vệ. Để biết thêm thông tin, hãy xem phần Hộp cát.
"short_name"- Một chuỗi chứa phiên bản rút gọn của tên tiện ích sẽ được dùng khi không gian ký tự bị hạn chế. Độ dài tối đa là 12 ký tự. Nếu giá trị này không xác định, thì một phiên bản rút gọn của khoá "name" sẽ xuất hiện thay thế.
"side_panel"- Xác định một tệp HTML để hiển thị trong sidePanel.
"storage"- Khai báo một giản đồ JSON cho vùng lưu trữ được quản lý. Để biết thêm thông tin, hãy xem bài viết Tệp kê khai cho các vùng lưu trữ.
"tts_engine"- Đăng ký tiện ích làm công cụ chuyển văn bản sang lời nói. Để biết thêm thông tin, hãy xem API ttsEngine.
"update_url"- Một chuỗi chứa URL của trang cập nhật tiện ích. Sử dụng khoá này nếu bạn lưu trữ tiện ích của mình bên ngoài Cửa hàng Chrome trực tuyến.
"version_name"- Một chuỗi mô tả phiên bản của tiện ích. Ví dụ:
"1.0 beta"và"build rc2". Nếu bạn không chỉ định giá trị này, thì giá trị "version" (phiên bản) sẽ xuất hiện trên trang quản lý tiện ích. "web_accessible_resources"- Xác định các tệp trong tiện ích mà các trang web hoặc tiện ích khác có thể truy cập. Để biết thêm thông tin, hãy xem phần Tài nguyên có thể truy cập trên web.
Khoá không bắt buộc của ChromeOS
"file_browser_handlers"- Cung cấp quyền truy cập vào API
fileBrowserHandler. API này cho phép các tiện ích truy cập vào trình duyệt tệp của ChromeOS. "file_handlers"- Chỉ định các loại tệp mà tiện ích ChromeOS sẽ xử lý. Để biết thêm thông tin, hãy xem
file_handlers. "file_system_provider_capabilities"- Cho phép truy cập vào API
fileSystemProvider. API này cho phép các tiện ích tạo hệ thống tệp mà ChromeOS có thể sử dụng. "input_components"- Cho phép sử dụng API Trình chỉnh sửa phương thức nhập. Để biết thêm thông tin, hãy xem
input_components.