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 בלבד), Option (ב-macOS בלבד), ‫Command (ב-macOS בלבד), Search (ב-ChromeOS בלבד)

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

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

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

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

  • ב-macOS, אפשר להשתמש גם ב-Command או ב-MacCtrl במקום ב-Ctrl, ואפשר להשתמש במקש Option במקום במקש 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,
)