คำอธิบาย
ใช้ 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
- ตัวแก้ไขไม่สามารถใช้ร่วมกับคีย์สื่อได้
ระบบจะแปลง
Ctrl
ใน macOS เป็น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`);
});
ตรวจสอบการลงทะเบียนคำสั่ง
หากส่วนขยายพยายามบันทึกทางลัดที่มีส่วนขยายอื่นใช้งานอยู่แล้ว แป้นพิมพ์ลัดของส่วนขยายที่ 2 จะไม่บันทึกตามที่คาดไว้ คุณสามารถมอบประสบการณ์การใช้งานที่มีประสิทธิภาพยิ่งขึ้นของผู้ใช้ปลายทางโดยการคาดเดาความเป็นไปได้นี้ และตรวจหาการชนกันในเวลาติดตั้ง
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 ขึ้นไปPromise รองรับไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback เพื่อรองรับความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ โดยสัญญาจะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยัง Callback