chrome.commands

תיאור

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

מניפסט

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

"commands"

מושגים ושימוש

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

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

suggested_key

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

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

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

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

description

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

תוסף יכול לכלול הרבה פקודות, אבל אפשר לציין עד ארבע הצעות למקשי קיצור. המשתמש יכול להוסיף עוד קיצורי דרך באופן ידני מתיבת הדו-שיח 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, ‏ Shift, ‏ MacCtrl (macOS בלבד), ‏ Command (macOS בלבד), ‏ Search (ChromeOS בלבד)

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

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

    • אי אפשר להשתמש בתוספי מקש בשילוב עם Media Keys.

    • במקלדות רבות של macOS, Alt מתייחס למקש Option.

    • ב-macOS, אפשר להשתמש גם ב-Command או ב-MacCtrl במקום ב-Ctrl או ב-Alt (ראו את הנקודה הבאה ברשימה).

  • ב-macOS, Ctrl מומר אוטומטית ל-Command.

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

מאפיינים

  • תיאור

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

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

  • שם

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

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

  • קיצור דרך

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

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

Methods

getAll()

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (commands: Command[]) => void

החזרות

  • Promise<Command[]>

    גרסה 96 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

אירועים

onCommand

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

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

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

    • פקודה

      מחרוזת

    • כרטיסייה

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