chrome.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 (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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    (commands: Command[]) => void

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

  • สัญญา<Command[]>

    Chrome 96 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

กิจกรรม

onCommand

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

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

    • คำสั่ง

      สตริง

    • แท็บ

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