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

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

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

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

chrome.commands.getAll(
  callback?: function,
)

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