chrome.commands

תיאור

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

מניפסט

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

"commands"

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

באמצעות 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 בלבד)

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

  • מקשי הקיצור של פקודות תוספים חייבים לכלול 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 (מניפסט V3), _execute_browser_action (מניפסט V2) פקודות _execute_page_action (מניפסט מגרסה V2) שמורות לפעולה של הפעלת הפעולה, פעולת הדפדפן או פעולת הדף, בהתאמה. הפקודות האלה לא נשלחות אירועי command.onCommand כמו פקודות רגילות.

אם עליך לנקוט פעולה בהתאם לפתיחת החלון הקופץ, כדאי להאזין אירוע DOMContentLoaded ב-JavaScript של החלון הקופץ.

היקף

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

מאפיינים

  • תיאור

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

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

  • שם

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

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

  • קיצור דרך

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

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

שיטות

getAll()

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

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

פרמטרים

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

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

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

    (commands: Command[]) => void

החזרות

  • Promise<Command[]>

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

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

אירועים

onCommand

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

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

פרמטרים

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

    פונקציה

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

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

    • מקש Command

      מחרוזת

    • כרטיסייה

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