คำอธิบาย
ใช้ API คำสั่งเพื่อเพิ่มแป้นพิมพ์ลัดที่ทริกเกอร์การดำเนินการในส่วนขยาย เช่น การดำเนินการเพื่อเปิดการทำงานของเบราว์เซอร์หรือส่งคำสั่งไปยังส่วนขยาย
ไฟล์ Manifest
แนวคิดและการใช้งาน
Commands API ช่วยให้นักพัฒนาส่วนขยายกำหนดคำสั่งเฉพาะและเชื่อมโยงกับชุดคีย์เริ่มต้นได้ แต่ละคำสั่งที่ส่วนขยายยอมรับจะต้องมีการประกาศเป็นพร็อพเพอร์ตี้ของออบเจ็กต์ "commands" ในไฟล์ Manifest ของส่วนขยาย
ระบบจะใช้คีย์คุณสมบัติเป็นชื่อคำสั่ง ออบเจ็กต์คำสั่งมีได้ 2 พร็อพเพอร์ตี้
suggested_keyพร็อพเพอร์ตี้ที่ไม่บังคับซึ่งประกาศแป้นพิมพ์ลัดเริ่มต้นสำหรับคำสั่ง หากละไว้ คำสั่ง จะยกเลิกการเชื่อมโยง พร็อพเพอร์ตี้นี้ใช้สตริงหรือค่าออบเจ็กต์ก็ได้
ค่าสตริงระบุแป้นพิมพ์ลัดเริ่มต้นซึ่งควรใช้ในทุกแพลตฟอร์ม
ค่าออบเจ็กต์ช่วยให้นักพัฒนาซอฟต์แวร์ส่วนขยายปรับแต่งแป้นพิมพ์ลัดสำหรับแต่ละแพลตฟอร์มได้ เมื่อให้ทางลัดเฉพาะแพลตฟอร์ม พร็อพเพอร์ตี้ออบเจ็กต์ที่ถูกต้องคือ
default,chromeos,linux,macและwindows
ดูรายละเอียดเพิ่มเติมได้ในข้อกำหนดชุดคีย์
descriptionสตริงที่ใช้เพื่อให้คำอธิบายสั้นๆ เกี่ยวกับวัตถุประสงค์ของคำสั่งแก่ผู้ใช้ สตริงนี้จะปรากฏใน UI การจัดการแป้นพิมพ์ลัดของส่วนขยาย ต้องมีคำอธิบายสำหรับคำสั่งมาตรฐาน แต่คำสั่งของการดำเนินการจะไม่สนใจ
ส่วนขยายมีคำสั่งได้หลายรายการ แต่อาจระบุแป้นพิมพ์ลัดที่แนะนำได้สูงสุด 4 แป้นพิมพ์ลัด ผู้ใช้สามารถเพิ่มทางลัดด้วยตนเองจากกล่องโต้ตอบ chrome://extensions/shortcuts ได้
คีย์ที่รองรับ
คีย์ต่อไปนี้คือแป้นพิมพ์ลัดคำสั่งที่ใช้งานได้ คำจำกัดความที่สำคัญจะคำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ การพยายามโหลดส่วนขยายด้วยคีย์ที่ใส่คีย์ไม่ถูกต้องจะทำให้เกิดข้อผิดพลาดการแยกวิเคราะห์ไฟล์ Manifest ในขณะที่ติดตั้ง
- คีย์อัลฟ่า
A...Z- คีย์ตัวเลข
0...9- สตริงคีย์มาตรฐาน
ทั่วไป -
Comma,Period,Home,End,PageUp,PageDown,Space,Insert,Deleteปุ่มลูกศร -
Up,Down,Left,Rightคีย์สื่อ -
MediaNextTrack,MediaPlayPause,MediaPrevTrack,MediaStop- สตริงคีย์ตัวปรับแต่ง
Ctrl,Alt(Optionใน macOS),Shift,MacCtrl(macOS เท่านั้น),Command(macOS เท่านั้น),Search(ChromeOS เท่านั้น)
ข้อกำหนดชุดคีย์
ทางลัดคำสั่งของส่วนขยายต้องมี
CtrlหรือAlt- ตัวปรับแต่งใช้ร่วมกับคีย์สื่อไม่ได้
ส่วนใน macOS
Ctrlจะแปลงเป็นCommandโดยอัตโนมัติหากต้องการใช้แป้น Control ใน macOS ให้แทนที่
Ctrlด้วยMacCtrlเมื่อกำหนดแป้นพิมพ์ลัด"mac"การใช้
MacCtrlร่วมกับแพลตฟอร์มอื่นจะทำให้เกิดข้อผิดพลาดในการตรวจสอบความถูกต้อง และทำให้ติดตั้งส่วนขยายไม่ได้
Shiftเป็นตัวแก้ไขที่ไม่บังคับในทุกแพลตฟอร์มSearchเป็นตัวแก้ไขที่ไม่บังคับซึ่งมีเฉพาะใน ChromeOSระบบปฏิบัติการและแป้นพิมพ์ลัดของ Chrome บางอย่าง (เช่น การจัดการหน้าต่าง) จะมีความสำคัญเหนือทางลัดคำสั่งของส่วนขยายเสมอและไม่สามารถเขียนทับได้
จัดการเหตุการณ์คําสั่ง
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"
}
}
},
...
}
ใน Service Worker คุณจะเชื่อมโยงตัวแฮนเดิลกับแต่ละคำสั่งที่กำหนดไว้ในไฟล์ Manifest ได้โดยใช้ onCommand.addListener เช่น
service-worker.js
chrome.commands.onCommand.addListener((command) => {
console.log(`Command: ${command}`);
});
คำสั่งการดำเนินการ
คำสั่ง _execute_action (ไฟล์ Manifest V3), _execute_browser_action (ไฟล์ Manifest V2) และ _execute_page_action (ไฟล์ Manifest V2) สงวนไว้สำหรับการทริกเกอร์การดำเนินการของคุณ การทำงานของเบราว์เซอร์ หรือการทำงานของหน้าเว็บตามลำดับ คำสั่งเหล่านี้จะไม่ส่งเหตุการณ์ command.onCommand เช่น คำสั่งมาตรฐาน
หากคุณต้องการดำเนินการตามการเปิดป๊อปอัป ให้ลองฟังเหตุการณ์ DOMContentLoaded ภายใน JavaScript ของป๊อปอัป
ขอบเขต
โดยค่าเริ่มต้น คําสั่งจะกําหนดขอบเขตอยู่ที่เบราว์เซอร์ Chrome ซึ่งหมายความว่าเมื่อเบราว์เซอร์ไม่มีโฟกัส ทางลัดคำสั่งจะไม่ทำงาน ตั้งแต่ Chrome 35 เป็นต้นไป นักพัฒนาส่วนขยายสามารถ ทำเครื่องหมายคำสั่งเป็น "global" คำสั่งส่วนกลางยังใช้งานแม้ Chrome ไม่มีโฟกัสได้ด้วย
คำแนะนำแป้นพิมพ์ลัดสำหรับคำสั่งส่วนกลางจำกัดอยู่ที่ Ctrl+Shift+[0..9] ซึ่งเป็นมาตรการป้องกันที่จะลดความเสี่ยงในการลบล้างแป้นพิมพ์ลัดในแอปพลิเคชันอื่นๆ เนื่องจากหากอนุญาตให้ใช้ Alt+P เป็นส่วนกลาง แป้นพิมพ์ลัดสำหรับเปิดกล่องโต้ตอบการพิมพ์อาจไม่ทำงานในแอปพลิเคชันอื่น
ผู้ใช้ปลายทางจะแมปคำสั่งส่วนกลางกับชุดคีย์ที่ต้องการซ้ำได้อย่างอิสระโดยใช้ UI ที่เปิดเผยที่ chrome://extensions/shortcuts
ตัวอย่าง
manifest.json:
{
"name": "My extension",
...
"commands": {
"toggle-feature-foo": {
"suggested_key": {
"default": "Ctrl+Shift+5"
},
"description": "Toggle feature foo",
"global": true
}
},
...
}
ตัวอย่าง
ตัวอย่างต่อไปนี้ครอบคลุมฟังก์ชันหลักของ Commands API
คำสั่งพื้นฐาน
คำสั่งจะช่วยให้ส่วนขยายแมปตรรกะกับแป้นพิมพ์ลัดที่ผู้ใช้เรียกใช้ได้ โดยพื้นฐานแล้ว คำสั่งมีเพียงการประกาศคำสั่งในไฟล์ Manifest ของส่วนขยายและการลงทะเบียน Listener ดังที่แสดงในตัวอย่างต่อไปนี้
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`);
});
คำสั่งสำหรับดำเนินการ
ตามที่อธิบายไว้ในส่วนการใช้งาน คุณยังสามารถแมปคำสั่งกับการทำงานของส่วนขยายได้ด้วย ตัวอย่างต่อไปนี้จะแทรกสคริปต์เนื้อหาที่แสดงการแจ้งเตือนในหน้าปัจจุบันเมื่อผู้ใช้คลิกการทำงานของส่วนขยายหรือทริกเกอร์แป้นพิมพ์ลัด
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`);
});
ยืนยันคำสั่งที่ลงทะเบียนไว้
หากส่วนขยายพยายามจะลงทะเบียนทางลัดที่มีส่วนขยายอื่นใช้อยู่แล้ว ทางลัดของส่วนขยายที่สองจะไม่บันทึกตามที่คาดไว้ คุณสามารถมอบประสบการณ์การใช้งานที่มีประสิทธิภาพมากขึ้นแก่ผู้ใช้ โดยคาดการณ์ความเป็นไปได้นี้ และตรวจหาการชน ณ เวลาติดตั้ง
service-worker.js
chrome.runtime.onInstalled.addListener((details) => {
if (details.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.
}
});
}
ประเภท
Command
พร็อพเพอร์ตี้
-
คำอธิบาย
string ไม่บังคับ
คำอธิบายคำสั่งส่วนขยาย
-
ชื่อ
string ไม่บังคับ
ชื่อของคำสั่งส่วนขยาย
-
ทางลัด
string ไม่บังคับ
แป้นพิมพ์ลัดที่ใช้งานอยู่สำหรับคำสั่งนี้ หรือเว้นว่างไว้หากไม่ได้ใช้งาน
วิธีการ
getAll()
chrome.commands.getAll(
callback?: function,
)
แสดงคำสั่งของส่วนขยายทั้งหมดที่ลงทะเบียนสำหรับส่วนขยายนี้และทางลัด (หากเปิดใช้งาน) ก่อน Chrome 110 คำสั่งนี้ไม่ได้แสดงผล _execute_action
พารามิเตอร์
การคืนสินค้า
-
สัญญา<Command[]>
Chrome 96 ขึ้นไปManifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ