browser.commands

คำอธิบาย

ใช้ Commands API เพื่อเพิ่มแป้นพิมพ์ลัดที่ทริกเกอร์การดำเนินการในส่วนขยาย เช่น การดำเนินการเพื่อเปิดการดำเนินการของเบราว์เซอร์หรือส่งคำสั่งไปยังส่วนขยาย

ไฟล์ Manifest

ต้องประกาศคีย์ต่อไปนี้ในไฟล์ Manifest เพื่อใช้ API นี้

"commands"

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

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 เท่านั้น), 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:

browser.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:

browser.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:

browser.action.onClicked.addListener((tab) => {
  browser.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"
browser.commands.onCommand.addListener((command) => {
  console.log(`Command "${command}" called`);
});

ยืนยันคำสั่งที่ลงทะเบียนไว้

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

service-worker.js:

browser.runtime.onInstalled.addListener((details) => {
  if (details.reason === browser.runtime.OnInstalledReason.INSTALL) {
    checkCommandShortcuts();
  }
});

// Only use this function during the initial install phase. After
// installation the user may have intentionally unassigned commands.
function checkCommandShortcuts() {
  browser.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()

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

แสดงคำสั่งส่วนขยายที่ลงทะเบียนไว้ทั้งหมดสำหรับส่วนขยายนี้และแป้นพิมพ์ลัด (หากใช้งานอยู่) ก่อน Chrome 110 คำสั่งนี้จะไม่แสดง _execute_action

การคืนสินค้า

  • Promise<Command[]>

    Chrome 96 ขึ้นไป browser.* ตั้งแต่ Chrome 148

    แก้ไขด้วยรายการคำสั่งที่ลงทะเบียนไว้

กิจกรรม

onCommand

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

เริ่มทำงานเมื่อเปิดใช้งานคำสั่งที่ลงทะเบียนไว้โดยใช้แป้นพิมพ์ลัด

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback จะมีลักษณะดังนี้ 

    (command: string, tab?: tabs.Tab) => void

    • คำสั่ง

      สตริง

    • แท็บ

      tabs.Tab ไม่บังคับ