refresh date: 2026-09-25 robots: noindex
คำอธิบาย
ใช้ Commands 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 เป็นต้นไป นักพัฒนาส่วนขยายสามารถเลือกทำเครื่องหมายคำสั่งเป็น "ส่วนกลาง" ได้ คำสั่งส่วนกลางยังทำงานได้แม้ว่า Chrome จะไม่ได้โฟกัสอยู่ก็ตาม
คำแนะนำแป้นพิมพ์ลัดสำหรับคำสั่งส่วนกลางจำกัดไว้ที่ Ctrl+Shift+[0..9] รายการ ซึ่งเป็นมาตรการป้องกันเพื่อลดความเสี่ยงในการลบล้างแป้นพิมพ์ลัดในแอปพลิเคชันอื่นๆ เนื่องจากหากอนุญาตให้ใช้ Alt+P เป็นแป้นพิมพ์ลัดส่วนกลาง แป้นพิมพ์ลัดสำหรับเปิดกล่องโต้ตอบการพิมพ์อาจไม่ทำงานในแอปพลิเคชันอื่นๆ
ผู้ใช้ปลายทางสามารถแมปคำสั่งส่วนกลางใหม่กับการกดแป้นร่วมกันที่ต้องการได้โดยใช้อินเทอร์เฟซผู้ใช้ที่แสดงที่ 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`);
});
ยืนยันคำสั่งที่ลงทะเบียนไว้
หากส่วนขยายพยายามลงทะเบียนแป้นพิมพ์ลัดที่ส่วนขยายอื่นใช้อยู่แล้ว แป้นพิมพ์ลัดของส่วนขยายที่ 2 จะไม่ลงทะเบียนตามที่คาดไว้ คุณสามารถมอบประสบการณ์การใช้งานที่ดียิ่งขึ้นให้แก่ผู้ใช้ปลายทางได้โดยการคาดการณ์ความเป็นไปได้นี้และตรวจสอบการชนกันในเวลาติดตั้ง
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.
}
});
}
ประเภท
Command
พร็อพเพอร์ตี้
-
คำอธิบาย
สตริง ไม่บังคับ
คำอธิบายคำสั่งส่วนขยาย
-
name
สตริง ไม่บังคับ
ชื่อของคำสั่งส่วนขยาย
-
ทางลัด
สตริง ไม่บังคับ
แป้นพิมพ์ลัดที่ใช้งานอยู่สำหรับคำสั่งนี้ หรือเว้นว่างไว้หากไม่ได้ใช้งาน
เมธอด
getAll()
chrome.commands.getAll(
callback?: function,
): Promise<Command[]>
แสดงคำสั่งส่วนขยายที่ลงทะเบียนไว้ทั้งหมดสำหรับส่วนขยายนี้และแป้นพิมพ์ลัด (หากใช้งานอยู่) ก่อน Chrome 110 คำสั่งนี้จะไม่แสดง _execute_action
พารามิเตอร์
การคืนสินค้า
-
Promise<Command[]>
Chrome 96 ขึ้นไปแก้ไขด้วยรายการคำสั่งที่ลงทะเบียนไว้
ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback