Nội dung mô tả
Sử dụng API lệnh để thêm phím tắt kích hoạt các thao tác trong tiện ích của bạn, chẳng hạn như một thao tác để mở thao tác trên trình duyệt hoặc gửi một lệnh đến tiện ích.
Tệp kê khai
Cách sử dụng
Commands API cho phép nhà phát triển tiện ích xác định các lệnh cụ thể và liên kết chúng với một tổ hợp khoá mặc định. Bạn phải khai báo mỗi lệnh mà một tiện ích chấp nhận là thuộc tính của đối tượng "commands"
trong tệp kê khai của tiện ích.
Khoá thuộc tính được dùng làm tên của lệnh. Các đối tượng lệnh có thể nhận hai thuộc tính.
suggested_key
Một thuộc tính không bắt buộc khai báo phím tắt mặc định cho lệnh. Nếu bị bỏ qua, lệnh này sẽ không được liên kết. Thuộc tính này có thể nhận một chuỗi hoặc một giá trị đối tượng.
Giá trị chuỗi chỉ định phím tắt mặc định nên được sử dụng trên tất cả các nền tảng.
Giá trị đối tượng cho phép nhà phát triển tiện ích tuỳ chỉnh phím tắt cho từng nền tảng. Khi cung cấp lối tắt dành riêng cho nền tảng, các thuộc tính đối tượng hợp lệ là
default
,chromeos
,linux
,mac
vàwindows
.
Xem Yêu cầu về tổ hợp khóa để biết thêm thông tin chi tiết.
description
Một chuỗi dùng để cung cấp cho người dùng nội dung mô tả ngắn về mục đích của lệnh. Chuỗi này xuất hiện trong giao diện người dùng quản lý phím tắt của tiện ích. Nội dung mô tả là bắt buộc đối với các lệnh tiêu chuẩn, nhưng bị bỏ qua đối với Lệnh hành động.
Một tiện ích có thể có nhiều lệnh, nhưng có thể chỉ định tối đa 4 phím tắt được đề xuất. Người dùng có thể thêm các lối tắt khác theo cách thủ công từ hộp thoại chrome://extensions/shortcuts
.
Các phím được hỗ trợ
Các phím sau là phím tắt lệnh có thể sử dụng. Các định nghĩa chính có phân biệt chữ hoa chữ thường. Việc cố gắng tải một tiện ích có khoá có vỏ không chính xác sẽ dẫn đến lỗi phân tích cú pháp tệp kê khai tại thời điểm cài đặt.
- Phím alpha
A
...Z
- Phím số
0
...9
- Chuỗi khoá tiêu chuẩn
Dịch vụ chung –
Comma
,Period
,Home
,End
,PageUp
,PageDown
,Space
,Insert
,Delete
Các phím mũi tên–
Up
,Down
,Left
,Right
Các khoá đa phương tiện –
MediaNextTrack
,MediaPlayPause
,MediaPrevTrack
,MediaStop
- Chuỗi phím bổ trợ
Ctrl
,Alt
(Option
trên macOS),Shift
,MacCtrl
(chỉ macOS),Command
(chỉ macOS),Search
(chỉ ChromeOS)
Yêu cầu về tổ hợp phím
Lối tắt lệnh của tiện ích phải bao gồm
Ctrl
hoặcAlt
.- Bạn không thể dùng đối tượng sửa đổi cùng với Khoá nội dung đa phương tiện.
Trên macOS,
Ctrl
được tự động chuyển đổi thànhCommand
.Để sử dụng phím Control trên macOS, hãy thay thế
Ctrl
bằngMacCtrl
khi xác định phím tắt"mac"
.Việc sử dụng
MacCtrl
kết hợp với một nền tảng khác sẽ gây ra lỗi xác thực và ngăn cài đặt tiện ích.
Shift
là đối tượng sửa đổi không bắt buộc trên tất cả nền tảng.Search
là đối tượng sửa đổi không bắt buộc dành riêng cho ChromeOS.Một số phím tắt của hệ điều hành và Chrome (ví dụ: quản lý cửa sổ) luôn được ưu tiên hơn so với các phím tắt lệnh của Tiện ích và không thể bị ghi đè.
Xử lý các sự kiện lệnh
manifest.json:
{
"name": "My extension",
...
"commands": {
"run-foo": {
"suggested_key": {
"default": "Ctrl+Shift+Y",
"mac": "Command+Shift+Y"
},
"description": "Run \"foo\" on the current page."
},
"_execute_action": {
"suggested_key": {
"windows": "Ctrl+Shift+Y",
"mac": "Command+Shift+Y",
"chromeos": "Ctrl+Shift+U",
"linux": "Ctrl+Shift+J"
}
}
},
...
}
Trong trình chạy dịch vụ, bạn có thể liên kết một trình xử lý với từng lệnh được xác định trong tệp kê khai bằng cách sử dụng onCommand.addListener
. Ví dụ:
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
Lệnh hành động
Các lệnh _execute_action
(Manifest V3), _execute_browser_action
(Manifest V2) và _execute_page_action
(Manifest V2) được dành riêng cho hành động kích hoạt hành động, hành động trên trình duyệt hoặc hành động trên trang tương ứng. Các lệnh này không gửi các sự kiện command.onCommand như các lệnh tiêu chuẩn.
Nếu bạn cần thực hiện hành động dựa trên việc mở cửa sổ bật lên, hãy cân nhắc theo dõi sự kiện DOMContentLoaded bên trong JavaScript của cửa sổ bật lên.
Phạm vi
Theo mặc định, các lệnh thuộc phạm vi của trình duyệt Chrome. Điều này có nghĩa là khi trình duyệt không có tâm điểm, các phím tắt lệnh sẽ không hoạt động. Kể từ Chrome 35, nhà phát triển tiện ích có thể tuỳ ý đánh dấu một lệnh là "global". Các lệnh chung cũng hoạt động trong khi Chrome không có tiêu điểm.
Gợi ý phím tắt cho các lệnh chung được giới hạn ở Ctrl+Shift+[0..9]
. Đây là biện pháp bảo vệ để giảm thiểu nguy cơ ghi đè phím tắt trong các ứng dụng khác vì nếu Alt+P
được phép dưới dạng chung, thì phím tắt để mở hộp thoại in có thể không hoạt động trong các ứng dụng khác.
Người dùng cuối có thể tuỳ ý gán lại các lệnh chung với tổ hợp phím mà họ muốn bằng cách sử dụng giao diện người dùng hiển thị tại chrome://extensions/shortcuts
.
Ví dụ:
manifest.json:
{
"name": "My extension",
...
"commands": {
"toggle-feature-foo": {
"suggested_key": {
"default": "Ctrl+Shift+5"
},
"description": "Toggle feature foo",
"global": true
}
},
...
}
Ví dụ
Các ví dụ sau đây minh hoạ chức năng cốt lõi của Commands API.
Lệnh cơ bản
Các lệnh cho phép tiện ích liên kết logic với phím tắt mà người dùng có thể gọi. Về cơ bản, một lệnh chỉ yêu cầu khai báo lệnh trong tệp kê khai của tiện ích và quy trình đăng ký trình nghe như minh hoạ trong ví dụ sau.
manifest.json:
{
"name": "Command demo - basic",
"version": "1.0",
"manifest_version": 3,
"background": {
"service_worker": "service-worker.js"
},
"commands": {
"inject-script": {
"suggested_key": "Ctrl+Shift+Y",
"description": "Inject a script on the page"
}
}
}
service-worker.js:
chrome.commands.onCommand.addListener((command) => {
console.log(`Command "${command}" triggered`);
});
Lệnh hành động
Như mô tả trong phần Usage, bạn cũng có thể ánh xạ một lệnh đến hành động của tiện ích. Ví dụ sau đây sẽ chèn một tập lệnh nội dung để hiển thị một cảnh báo trên trang hiện tại khi người dùng nhấp vào thao tác của tiện ích hoặc kích hoạt phím tắt.
manifest.json:
{
"name": "Commands demo - action invocation",
"version": "1.0",
"manifest_version": 3,
"background": {
"service_worker": "service-worker.js"
},
"permissions": ["activeTab", "scripting"],
"action": {},
"commands": {
"_execute_action": {
"suggested_key": {
"default": "Ctrl+U",
"mac": "Command+U"
}
}
}
}
service-worker.js:
chrome.action.onClicked.addListener((tab) => {
chrome.scripting.executeScript({
target: {tabId: tab.id},
func: contentScriptFunc,
args: ['action'],
});
});
function contentScriptFunc(name) {
alert(`"${name}" executed`);
}
// This callback WILL NOT be called for "_execute_action"
chrome.commands.onCommand.addListener((command) => {
console.log(`Command "${command}" called`);
});
Xác minh các lệnh đã đăng ký
Nếu một tiện ích cố gắng đăng ký lối tắt đã được một tiện ích khác sử dụng, thì lối tắt của tiện ích thứ hai sẽ không đăng ký như dự kiến. Bạn có thể cung cấp trải nghiệm người dùng cuối mạnh mẽ hơn bằng cách dự đoán khả năng này và kiểm tra xung đột tại thời điểm cài đặt.
service-worker.js:
chrome.runtime.onInstalled.addListener((reason) => {
if (reason === chrome.runtime.OnInstalledReason.INSTALL) {
checkCommandShortcuts();
}
});
// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
chrome.commands.getAll((commands) => {
let missingShortcuts = [];
for (let {name, shortcut} of commands) {
if (shortcut === '') {
missingShortcuts.push(name);
}
}
if (missingShortcuts.length > 0) {
// Update the extension UI to inform the user that one or more
// commands are currently unassigned.
}
});
}
Loại
Command
Thuộc tính
-
description
chuỗi không bắt buộc
Nội dung mô tả về lệnh của tiện ích
-
tên
chuỗi không bắt buộc
Tên của Lệnh tiện ích
-
khẩu lệnh nhanh
chuỗi không bắt buộc
Phím tắt đang hoạt động cho lệnh này hoặc để trống nếu không hoạt động.
Phương thức
getAll()
chrome.commands.getAll(
callback?: function,
)
Trả về tất cả lệnh của tiện ích đã đăng ký cho tiện ích này và lối tắt của tiện ích (nếu đang hoạt động). Trước Chrome 110, lệnh này không trả về _execute_action
.
Tham số
Giá trị trả về
-
Hứa hẹn<Command[]>
Chrome 96 trở lênLời hứa chỉ được hỗ trợ cho Manifest V3 trở lên, các nền tảng khác cần sử dụng lệnh gọi lại.