chrome.commands

תיאור

מניפסט

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

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

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

suggested_key

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

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

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

פקודת פעולה

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

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

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

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