chrome.commands

คำอธิบาย

ไฟล์ 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, Shift, MacCtrl (macOS เท่านั้น), Command (macOS เท่านั้น), Search (ChromeOS เท่านั้น)

ข้อกำหนดของชุดแป้น

• แป้นพิมพ์ลัดคำสั่งของส่วนขยายต้องมี Ctrl หรือ Alt

  • ตัวแก้ไขใช้ร่วมกับปุ่มสื่อไม่ได้

  • ในแป้นพิมพ์ macOS หลายรุ่น Alt หมายถึงปุ่ม Option

  • ใน macOS คุณยังใช้ Command หรือ MacCtrl แทน Ctrl หรือ Alt ได้ด้วย (ดูหัวข้อย่อยถัดไป)

• ใน macOS ระบบจะแปลง Ctrl เป็น Command โดยอัตโนมัติ

  • Command ยังใช้ในแป้นพิมพ์ลัด "mac" เพื่ออ้างอิงแป้น 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 เป็นแป้นพิมพ์ลัดส่วนกลาง ตัวอย่างเช่น แป้นพิมพ์ลัดสำหรับเปิดกล่องโต้ตอบการพิมพ์อาจไม่ทำงานในแอปพลิเคชันอื่นๆ

ผู้ใช้ปลายทางสามารถเปลี่ยนการแมปคำสั่งส่วนกลางเป็นการกดแป้นร่วมกันที่ต้องการได้โดยใช้ 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`); }); 

คำสั่งการดำเนินการ

ตามที่อธิบายไว้ในส่วนแนวคิดและการใช้งาน คุณยังแมปคำสั่งกับ การดำเนินการของส่วนขยายได้ด้วย ตัวอย่างต่อไปนี้จะแทรก Content Script ที่แสดงการแจ้งเตือนในหน้าปัจจุบันเมื่อผู้ใช้คลิกการดำเนินการของส่วนขยายหรือทริกเกอร์แป้นพิมพ์ลัด

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</0x0A> จะลงทะเบียนไม่ได้ตามที่คาดไว้ คุณสามารถมอบประสบการณ์การใช้งานที่ดียิ่งขึ้นให้แก่ผู้ใช้ปลายทางได้โดยคาดการณ์ถึงความเป็นไปได้นี้และตรวจสอบการชนกันในเวลาที่ติดตั้ง

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.     }   }); } 

chrome.commands.getAll(): Promise<Command[]>

chrome.commands.onCommand.addListener(
  callback: function,
)