chrome.commands

תיאור

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

מניפסט

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

"commands"

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

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

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

suggested_key

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

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

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

לפרטים נוספים, אפשר לעיין בדרישות לשילוב מפתחות.

description

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

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

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

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

מפתחות אלפא
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.

פקודה בסיסית

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

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

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

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

תכונות

  • תיאור

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

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

  • name

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

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

  • קיצור דרך

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

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

שיטות

getAll()

הבטחה 
chrome.commands.getAll(
  callback?: function,
)

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

פרמטרים

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

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

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

    (commands: Command[])=>void

החזרות

  • הבטחה<Command[]>

    Chrome 96 ומעלה

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

אירועים

onCommand

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

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

פרמטרים

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

    פונקציה

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

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

    • מקש Command

      מחרוזת

    • tab

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