chrome.commands

คำอธิบาย

ไฟล์ Manifest

แนวคิดและการใช้งาน

Commands API ช่วยให้นักพัฒนาส่วนขยายกำหนดคำสั่งที่เฉพาะเจาะจงและ เชื่อมโยงคำสั่งเหล่านั้นกับชุดคีย์เริ่มต้นได้ คำสั่งแต่ละรายการที่ส่วนขยายยอมรับต้อง ประกาศเป็นพร็อพเพอร์ตี้ของออบเจ็กต์ "commands" ในไฟล์ Manifest ของส่วนขยาย

ระบบจะใช้คีย์พร็อพเพอร์ตี้เป็นชื่อของคำสั่ง ออบเจ็กต์คำสั่งมีพร็อพเพอร์ตี้ได้ 2 รายการ

suggested_key

พร็อพเพอร์ตี้ที่ไม่บังคับซึ่งประกาศแป้นพิมพ์ลัดเริ่มต้นสำหรับคำสั่ง หากไม่ระบุ ระบบจะไม่ผูกคำสั่ง พร็อพเพอร์ตี้นี้อาจใช้ค่าสตริงหรือค่าออบเจ็กต์ก็ได้

• ค่าสตริงระบุแป้นพิมพ์ลัดเริ่มต้นที่ควรใช้ในทุกแพลตฟอร์ม

  • ค่าออบเจ็กต์ช่วยให้นักพัฒนาส่วนขยายปรับแต่ง แป้นพิมพ์ลัดสำหรับแต่ละแพลตฟอร์มได้ เมื่อระบุทางลัดเฉพาะแพลตฟอร์ม พร็อพเพอร์ตี้ออบเจ็กต์ที่ถูกต้องคือ default, chromeos, linux, mac และ windows

  ดูรายละเอียดเพิ่มเติมได้ที่ข้อกำหนดในการรวมคีย์

description

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

ส่วนขยายมีคำสั่งได้หลายรายการ แต่ระบุคีย์บอร์ดลัดที่แนะนำได้สูงสุด 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 เท่านั้น), Option (macOS เท่านั้น) Command (macOS เท่านั้น), Search (ChromeOS เท่านั้น)

ข้อกำหนดของชุดคีย์

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

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

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

  • ใน macOS คุณยังใช้ Command หรือ MacCtrl แทน Ctrl ได้ด้วย และใช้ปุ่ม Option แทน 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(): Promise<Command[]>

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