chrome.commands

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

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

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

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

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

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

service-worker.js:

chrome.runtime.onInstalled.addListener((reason) => {
  if (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,
): Promise<Command[]>

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