chrome.commands

refresh date: 2026-09-25 robots: noindex

תיאור

אפשר להשתמש ב-API של הפקודות כדי להוסיף מקשי קיצור שמפעילים פעולות בתוסף, למשל פעולה לפתיחת פעולת הדפדפן או לשליחת פקודה לתוסף.

מניפסט

כדי להשתמש ב-API הזה, צריך להצהיר על המפתחות הבאים במניפסט.

"commands"

שימוש

ממשק ה-API של הפקודות מאפשר למפתחי תוספים להגדיר פקודות ספציפיות ולקשר אותן לשילוב מקשים שמוגדר כברירת מחדל. כל פקודה שהתוסף מקבל צריכה להיות מוצהרת כמאפיינים של האובייקט "commands" במניפסט של התוסף.

מפתח המאפיין משמש כשם הפקודה. אובייקטים של פקודות יכולים לקבל שני מאפיינים.

suggested_key

מאפיין אופציונלי שמצהיר על מקשי קיצור שמוגדרים כברירת מחדל לפקודה. אם משמיטים את המאפיין, הפקודה לא תהיה מקושרת. המאפיין הזה יכול לקבל ערך של מחרוזת או של אובייקט.

• ערך מחרוזת מציין את מקש הקיצור שמוגדר כברירת מחדל לשימוש בכל הפלטפורמות.

• ערך אובייקט מאפשר למפתח התוסף להתאים אישית את מקש הקיצור לכל פלטפורמה. כשמציינים קיצורי דרך ספציפיים לפלטפורמה, מאפייני האובייקט החוקיים הם default,‏ chromeos,‏ linux,‏ mac ו-windows.

פרטים נוספים זמינים בקטע דרישות לשילובי מקשים.

description

מחרוזת שמשמשת כדי לספק למשתמש תיאור קצר של מטרת הפקודה. המחרוזת הזו מופיעה בממשק המשתמש לניהול מקשי הקיצור של התוסף. חובה להוסיף תיאורים לפקודות רגילות, אבל המערכת מתעלמת מהם בפקודות פעולה.

לתוסף יכולות להיות פקודות רבות, אבל אפשר לציין עד ארבע הצעות למקשי קיצור. המשתמש יכול להוסיף עוד קיצורי דרך באופן ידני מתיבת הדו-שיח chrome://extensions/shortcuts.

מפתחות נתמכים

המקשים הבאים הם מקשי קיצור לפקודות. הגדרות המפתחות תלויות אותיות רישיות. אם תנסו לטעון תוסף עם מפתח שהאותיות בו לא תואמות, תופיע שגיאה בניתוח המניפסט בזמן ההתקנה.

מקשי אותיות

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 בלבד)

הערה: המקש Tab הוסר מרשימת המקשים הנתמכים ב-Chrome 33 מסיבות שקשורות לנגישות.

הדרישות לשילובי מקשים

• מקשי הקיצור של פקודות התוספים חייבים לכלול את Ctrl או את Alt.

  • אי אפשר להשתמש במקשי צירופים בשילוב עם מקשי מדיה.

• ב-macOS, הערך Ctrl מומר באופן אוטומטי ל-Command.

  • כדי להשתמש במקש Control ב-macOS, מחליפים את Ctrl ב-MacCtrl כשמגדירים את מקש הקיצור "mac".

  • אם משתמשים ב-MacCtrl בשילוב עם פלטפורמה אחרת, תופיע שגיאת אימות והתוסף לא יותקן.

• Shift הוא מקש צירופים אופציונלי בכל הפלטפורמות.

• Search הוא מקש צירופים אופציונלי שקיים רק ב-ChromeOS.

• מקשי קיצור מסוימים של מערכת ההפעלה ושל Chrome (למשל, ניהול חלונות) תמיד מקבלים עדיפות על פני מקשי קיצור של פקודות בתוספים, ואי אפשר לשנות אותם.

הערה: אי אפשר להשתמש בשילובי מקשים שכוללים את Ctrl+Alt כדי למנוע התנגשויות עם המקש AltGr.

טיפול באירועי פקודות

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, אפשר לקשר handler לכל אחת מהפקודות שמוגדרות במניפסט באמצעות 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. כלומר, כשאין מיקוד בדפדפן, מקשי הקיצור של הפקודות לא פעילים. החל מגרסה 35 של Chrome, מפתחי תוספים יכולים לסמן פקודה כ "גלובלית". פקודות גלובליות פועלות גם כש-Chrome לא נמצא במוקד.

הערה: מערכת ChromeOS לא תומכת בפקודות גלובליות.

ההצעות למקשי קיצור לפקודות גלובליות מוגבלות ל-Ctrl+Shift+[0..9]. זהו אמצעי הגנה שנועד לצמצם את הסיכון של ביטול מקשי קיצור באפליקציות אחרות. לדוגמה, אם Alt+P היה מוגדר כגלובלי, יכול להיות שמקש הקיצור לפתיחת תיבת דו-שיח להדפסה לא היה פועל באפליקציות אחרות.

משתמשי קצה יכולים למפות מחדש פקודות גלובליות לצירוף המקשים המועדף עליהם באמצעות ממשק המשתמש שמוצג בכתובת 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.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`);
});

אימות הפקודות הרשומות

אם תוסף מנסה לרשום מקש קיצור שכבר נמצא בשימוש על ידי תוסף אחר, מקש הקיצור של התוסף השני לא יירשם כצפוי. כדי לספק חוויית משתמש טובה יותר, כדאי לצפות את האפשרות הזו ולבדוק אם יש התנגשויות בזמן ההתקנה.

הערה:_execute_action לא יופיע ברשימת הפקודות שמוחזרות על ידי commands.getAll().

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

סוגים

Command

מאפיינים

• תיאור

  מחרוזת אופציונלי

  תיאור הפקודה של התוסף

• שם

  מחרוזת אופציונלי

  שם הפקודה של התוסף

• קיצור דרך

  מחרוזת אופציונלי

  מקש הקיצור שפעיל לפקודה הזו, או ריק אם הוא לא פעיל.

Methods

getAll()

Promise

chrome.commands.getAll(
  callback?: function,
): Promise<Command[]>

מחזירה את כל פקודות התוסף הרשומות של התוסף הזה ואת מקשי הקיצור שלהן (אם הם פעילים). בגרסאות ישנות יותר מ-Chrome 110, הפקודה הזו לא החזירה את הערך _execute_action.

פרמטרים

• callback

  function optional

  הפרמטר callback נראה כך:

  (commands: Command[]) => void

  • פקודות

    Command[]

החזרות

• Promise<Command[]>

  ‫Chrome מגרסה 96 ואילך

  הפונקציה מחזירה רשימה של הפקודות הרשומות.

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

אירועים

onCommand

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

מופעל כשפקודה רשומה מופעלת באמצעות מקש קיצור.

פרמטרים

• callback

  פונקציה

  הפרמטר callback נראה כך:

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

  • פקודה

    מחרוזת

  • Tab

    tabs.Tab אופציונלי