Mỗi tiện ích phải có một tệp manifest.json trong thư mục gốc 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 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 mẫu sau đây cho thấy cấu trúc tệp kê khai cơ bản 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ả 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ị duy nhất được hỗ trợ là
3. "name"- 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 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ữ cụ thể, 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.
Các khoá mà Cửa hàng Chrome trực tuyến yêu cầu
"description"- 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ề việc 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 Biểu tượng.
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 trong Thanh công cụ Google. Để biết thêm thông tin, hãy xem
chrome.action. "author"- Chỉ định địa chỉ email của tài khoản dùng để tạo tiện ích.
"background"- Chỉ định tệp JavaScript chứa worker dịch vụ của tiện ích, đóng vai trò là 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 phần mở rộng.
"chrome_settings_overrides"- Xác định chế độ ghi đè cho các chế độ cài đặt Chrome đã chọn. Để biết thêm thông tin, hãy xem bài viết Làm cách nào để ghi đè chế độ cài đặt 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 phần Ghi đè các trang Chrome.
"commands"- Xác định 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 sử dụng khi người dùng mở một số trang web nhất định. Để 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ế đối với tập lệnh, kiểu và các tài nguyên khác mà 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 giá trị cho tiêu đề HTTP Cross-Origin-Embedder-Policy. Tiêu đề này sẽ định cấu hình việc nhúng các tài nguyên trên 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, cho phép bạn đảm bảo rằng trang tiện ích cấp cao nhất không chia sẻ nhóm ngữ 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, 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". Bạn bắt buộc phải sử dụng khoá này trong các tiện ích được bản địa hoá và không được sử dụng khoá này trong các tiện ích chưa được bản địa hoá. Để biết thêm thông tin, hãy xem phần Quá trình quốc tế hoá.
"devtools_page"- Xác định các trang sử dụng 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 giá trị này, 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. Hệ thống sẽ yêu cầu người dùng cấp quyền truy cập vào các trang web này 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 máy chủ lưu trữ.
"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 Ẩ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ị này phải là một chuỗi con của 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 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 thuộc tính này vào một tiện ích hiện có, thì 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. Điều này bao gồm 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ó 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 Ô tìm kiếm.
"optional_host_permissions"- Khai báo quyền của máy chủ 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 tệp HTML cho phép người dùng thay đổi các tuỳ chọn tiện ích trên trang Tiện ích của Chrome. Để biết thêm thông tin, hãy xem phần Tuỳ chọn được 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 khảo cho từng API liệt kê các 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. Để biết 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 tập hợp các trang tiện ích không có quyền truy cập vào API tiện ích hoặc truy cập trực tiếp vào các trang không phải hộp cát. Để 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ử dụng khi không gian ký tự bị hạn chế. Độ dài tối đa là 12 ký tự. Nếu không xác định, phiên bản bị cắt bớt của khoá "tên" sẽ hiển thị.
"side_panel"- Xác định một tệp HTML để hiển thị trong sidePanel.
"storage"- Khai báo giản đồ JSON cho khu vực bộ nhớ được quản lý. Để biết thêm thông tin, hãy xem phần Tệp kê khai cho vùng bộ nhớ.
"tts_engine"- Đăng ký tiện ích dưới dạng 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 của tiện ích. Sử dụng khoá này nếu bạn lưu trữ tiện ích bên ngoài Cửa hàng Chrome trực tuyến.
"version_name"- 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, giá trị "phiên bản" sẽ hiển thị 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 cá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.
Các phím không bắt buộc của ChromeOS
"file_browser_handlers"- Cung cấp quyền truy cập vào API
fileBrowserHandler, cho phép các tiện ích truy cập vào trình duyệt tệp ChromeOS. "file_handlers"- Chỉ định các loại tệp để tiện ích ChromeOS 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.