Mỗi tiện ích phải có một tệp manifest.json trong thư mục gốc. Tệp này liệt kê các 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à những tính năng có thể sử dụng.
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 bắt đầu để 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ý một 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
Dưới đâ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"- Một chuỗi dùng để 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). Độ dài tối đa là 75 ký tự. Để biết thông tin về cách sử dụng tên 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 Phiên bản.
Những khoá mà 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 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ụ của 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 trình chạy dịch vụ của tiện ích, hoạt động như một trình xử lý sự kiện. Để biết thêm thông tin, hãy xem phần Giới thiệu về trình chạy dịch vụ tiện ích.
"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 phần Ghi đè các chế độ cài đặt của Chrome.
"chrome_url_overrides"- Xác định chế độ ghi đè cho các trang Chrome mặc định. Để 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ẽ 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à 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-Nhúngder-Policy. Tiêu đề này sẽ định cấu hình việc nhúng tài nguyên nhiều nguồn gốc trong 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 ngữ cảnh duyệt web với 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". Khoá này là bắt buộc trong các tiện ích đã bản địa hoá và không được dùng trong các tiện ích chưa được bản địa hoá. Để biết thêm thông tin, hãy xem bài viết Quốc tế hoá.
"devtools_page"- Xác định những 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"- Chỉ đị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 không xác định được điều 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 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. Cần có quyền của người dùng cho 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 bài viết 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 hoạt động của tiện ích ở chế độ ẩn danh. Các giá trị được hỗ trợ:
"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 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à 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 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 tiện ích 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. Quy định 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ã 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 Thanh địa chỉ.
"optional_host_permissions"- Khai báo quyền của máy chủ (không bắt buộc) cho tiện ích.
"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 các tuỳ chọn cho người dùng.
"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ể. Vui lòng xem bài viết Quyền để nắm được nội dung giải thích chung. Các trang tham khảo cho từng API liệt kê những quyền cần thiết.
"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 quyền truy cập trực tiếp vào các trang không ở trong 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ẽ được sử dụng khi không gian ký tự bị giới hạn. Độ dài tối đa là 12 ký tự. Nếu giá trị này không xác định, phiên bản cắt ngắn của khoá "name" sẽ xuất hiện.
"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 lưu trữ được quản lý. Để biết thêm thông tin, hãy xem Tệp kê khai cho khu vực lưu trữ.
"tts_engine"- Đăng ký tiện ích dưới dạng một 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 trang cập nhật của tiện ích. Hãy sử dụng khoá này nếu bạn đang lưu trữ tiện ích 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ụ như
"1.0 beta"và"build rc2". Nếu bạn không chỉ định giá trị này, thì giá trị "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à trang web hoặc tiện ích khác có thể truy cập. Để biết thêm thông tin, hãy xem bài viết Tài nguyên có thể truy cập trên web.
Khoá không bắt buộc trên ChromeOS
"file_browser_handlers"- Cấp quyền truy cập vào API
fileBrowserHandler, cho phép tiện ích truy cập vào trình duyệt tệp của ChromeOS. "file_handlers"- Chỉ định loại tệp mà các tiện ích ChromeOS cần 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để 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.