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

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

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