chrome.commands

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

מניפסט

שימוש

ממשק ה-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 בלבד)

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

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

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

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

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

‫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,
)