chrome.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, ‏ Shift, ‏ MacCtrl (macOS בלבד), ‏ Command (macOS בלבד), ‏ Search (ChromeOS בלבד)

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

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

  • אי אפשר להשתמש במקשי שינוי בשילוב עם מקשי מדיה.

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

פקודה בסיסית

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

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

chrome.commands.getAll(): Promise<Command[]>

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