Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

עיצוב ממשק המשתמש

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

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

הפעלת התוסף בכל הדפים

משתמשים ב-browser_action כשהתכונות של התוסף פועלות ברוב המצבים.

רישום פעולה בדפדפן

השדה "browser_action" רשום במניפסט.

{
  "name": "My Awesome browser_action Extension",
  ...
  "browser_action": {
    ...
  }
  ...
}

הצהרה על "browser_action" שומרת על הצבע של הסמל, כדי לציין שהתוסף זמין למשתמשים.

הוספת תג

התגים מציגים באנר צבעוני עם עד ארבעה תווים מעל סמל הדפדפן. אפשר להשתמש בהם רק בתוספים שמצהירים על "browser_action" במניפסט שלהם.

השתמשו בתגים כדי לציין את מצב התוסף. בדוגמה Drink Water Event מוצג תג עם הכיתוב ON כדי להראות למשתמש שהוא הגדיר בהצלחה שעון מעורר, ולא מוצג כלום כשהתוסף לא פעיל.

מגדירים את הטקסט של התג באמצעות הקריאה chrome.browserAction.setBadgeText ואת צבע הבאנר באמצעות הקריאה chrome.browserAction.setBadgeBackgroundColor .

chrome.browserAction.setBadgeText({text: 'ON'});
chrome.browserAction.setBadgeBackgroundColor({color: '#4688F1'});

הפעלת התוסף בדפים נבחרים

משתמשים ב-page_action כשהתכונות של התוסף זמינות רק בנסיבות מוגדרות.

הצהרה על פעולה בדף

השדה "page_action" רשום במניפסט.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    ...
  }
  ...
}

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

הגדרת כללים להפעלת התוסף

מגדירים כללים למקרים שבהם אפשר להשתמש בתוסף על ידי קריאה ל-chrome.declarativeContent מתחת לרכיב listener‏ runtime.onInstalled בסקריפט לרקע. תוסף לדוגמה Page action by URL מגדיר תנאי שלפיו כתובת ה-URL חייבת לכלול את האות g. אם התנאי מתקיים, התוסף קורא ל-declarativeContent.ShowPageAction().

chrome.runtime.onInstalled.addListener(function() {
  // Replace all rules ...
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    // With a new rule ...
    chrome.declarativeContent.onPageChanged.addRules([
      {
        // That fires when a page's URL contains a 'g' ...
        conditions: [
          new chrome.declarativeContent.PageStateMatcher({
            pageUrl: { urlContains: 'g' },
          })
        ],
        // And shows the extension's page action.
        actions: [ new chrome.declarativeContent.ShowPageAction() ]
      }
    ]);
  });
});

הפעלה או השבתה של התוסף

תוספים שמשתמשים ב-"page_action" יכולים להפעיל ולהשבית את עצמם באופן דינמי באמצעות הקריאות pageAction.show ו-pageAction.hide.

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

chrome.runtime.onMessage.addListener(function(req, sender) {
  chrome.storage.local.set({'address': req.address})
  chrome.pageAction.show(sender.tab.id);
  chrome.pageAction.setTitle({tabId: sender.tab.id, title: req.address});
});

הוספת סמלי התוסף

כדי לייצג תוספים, צריך לפחות סמל אחד. כדי לקבל את התוצאות הוויזואליות הטובות ביותר, מומלץ לספק סמלים בפורמט PNG, אבל אפשר להשתמש בכל פורמט שנתמך על ידי WebKit, כולל BMP,‏ GIF,‏ ICO ו-JPEG.

הגדרת סמלים בסרגל הכלים

סמלים ספציפיים לסרגל הכלים רשומים בשדה "default_icon" בקובץ המניפסט, בקטע browser_action או page_action. מומלץ לכלול כמה גדלים כדי להתאים את התצוגה למרחב של 16 נקודות. מומלץ להשתמש בגודל 16x16 ובגודל 32x32 לפחות.

{
  "name": "My Awesome page_action Extension",
  ...
  "page_action": {
    "default_icon": {
      "16": "extension_toolbar_icon16.png",
      "32": "extension_toolbar_icon32.png"
    }
  }
  ...
}

כל הסמלים צריכים להיות מרובעים, אחרת הם עלולים להיות מעוותים. אם לא מספקים סמלים, Chrome יוסיף סמל כללי לסרגל הכלים.

יצירה ורישום של סמלים נוספים

צריך לכלול סמלים נוספים בגדלים הבאים לשימוש מחוץ לסרגל הכלים.

גודל הסמל	שימוש בסמלים
‫16x16	סמל האתר בדפים של התוסף
32x32	במחשבים עם Windows נדרש בדרך כלל הגודל הזה. הוספת האפשרות הזו תמנע את הצטמקות האפשרות 48x48 בגלל עיוות הגודל.
‫48x48	מוצג בדף של ניהול התוספים
‫128x128	מוצג במהלך ההתקנה ובחנות האינטרנט של Chrome

רושמים את הסמלים במניפסט בשדה "icons".

{
  "name": "My Awesome Extension",
  ...
  "icons": {
    "16": "extension_icon16.png",
    "32": "extension_icon32.png",
    "48": "extension_icon48.png",
    "128": "extension_icon128.png"
  }
  ...
}

תכונות נוספות בממשק המשתמש

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

בדוגמה Drink Water Event (אירוע שתייה) מוצגות אפשרויות הטיימר הזמינות. המשתמשים מגדירים שעון מעורר בלחיצה על אחד מהלחצנים שמוצגים.

צילום מסך לדוגמה של חלון קופץ

<html>
  <head>
    <title>Water Popup</title>
  </head>
  <body>
      <img src='./stay_hydrated.png' id='hydrateImage'>
      <button id='sampleSecond' value='0.1'>Sample Second</button>
      <button id='15min' value='15'>15 Minutes</button>
      <button id='30min' value='30'>30 Minutes</button>
      <button id='cancelAlarm'>Cancel Alarm</button>
    <script src="popup.js"></script>
  </body>
</html>

אפשר לרשום את החלון הקופץ במניפסט, בקטע browser action או page action.

{
  "name": "Drink Water Event",
  ...
  "browser_action": {
    "default_popup": "popup.html"
  }
  ...
}

אפשר גם להגדיר חלונות קופצים באופן דינמי באמצעות קריאה ל-browserAction.setPopup או ל-pageAction.setPopup.

chrome.storage.local.get('signed_in', function(data) {
  if (data.signed_in) {
    chrome.browserAction.setPopup({popup: 'popup.html'});
  } else {
    chrome.browserAction.setPopup({popup: 'popup_sign_in.html'});
  }
});

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

צילום מסך של הסבר קצר לדוגמה

ההסברים הקצרים רשומים בשדה "default_title" browser_action או page_action במניפסט.

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "Press Ctrl(Win)/Command(Mac)+Shift+Right/Left to flip tabs"
  }
...
}

אפשר גם להגדיר או לעדכן את ההסברים הקצרים באמצעות הקריאות browserAction.setTitle ו-pageAction.setTitle.

chrome.browserAction.onClicked.addListener(function(tab) {
  chrome.browserAction.setTitle({tabId: tab.id, title: "You are on tab:" + tab.id});
});

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

_locales/en/messages.json
_locales/es/messages.json

עיצוב הודעות בתוך כל messages.json של שפה.

{
  "__MSG_tooltip__": {
      "message": "Hello!",
      "description": "Tooltip Greeting."
  }
}

{
  "__MSG_tooltip__": {
      "message": "Hola!",
      "description": "Tooltip Greeting."
  }
}

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

{
"name": "Tab Flipper",
  ...
  "browser_action": {
    "default_title": "__MSG_tooltip__"
  }
...
}

סרגל הכתובות

המשתמשים יכולים להפעיל את הפונקציות של התוסף דרך סרגל הכתובות. כוללים את השדה "omnibox" במניפסט ומציינים מילת מפתח. תוסף לדוגמה Omnibox New Tab Search משתמש ב-nt כמילת המפתח.

{
  "name": "Omnibox New Tab Search",\
  ...
  "omnibox": { "keyword" : "nt" },
  "default_icon": {
    "16": "newtab_search16.png",
    "32": "newtab_search32.png"
  }
  ...
}

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

תוסף פעיל בסרגל הכתובות

התוסף מאזין לאירוע omnibox.onInputEntered. אחרי שהיא מופעלת, התוסף פותח כרטיסייה חדשה שמכילה חיפוש ב-Google של הערך שהמשתמש הזין.

chrome.omnibox.onInputEntered.addListener(function(text) {
  // Encode user input for special characters , / ? : @ & = + $ #
  var newURL = 'https://www.google.com/search?q=' + encodeURIComponent(text);
  chrome.tabs.create({ url: newURL });
});

תפריט הקשר

כדי להוסיף אפשרויות חדשות לתפריט ההקשר, צריך להעניק את ההרשאה "contextMenus" במניפסט.

{
  "name": "Global Google Search",
  ...
  "permissions": [
    "contextMenus",
    "storage"
  ],
  "icons": {
    "16": "globalGoogle16.png",
    "48": "globalGoogle48.png",
    "128": "globalGoogle128.png"
  }
  ...
}

הסמל בגודל 16x16 מוצג לצד רשומת התפריט החדשה.

יוצרים תפריט הקשר על ידי קריאה ל-contextMenus.create בסקריפט הרקע. הפעולה הזו צריכה להתבצע במסגרת אירוע ה-listener‏ runtime.onInstalled.

chrome.runtime.onInstalled.addListener(function() {
  for (let key of Object.keys(kLocales)) {
    chrome.contextMenus.create({
      id: key,
      title: kLocales[key],
      type: 'normal',
      contexts: ['selection'],
    });
  }
});

const kLocales = {
  'com.au': 'Australia',
  'com.br': 'Brazil',
  'ca': 'Canada',
  'cn': 'China',
  'fr': 'France',
  'it': 'Italy',
  'co.in': 'India',
  'co.jp': 'Japan',
  'com.ms': 'Mexico',
  'ru': 'Russia',
  'co.za': 'South Africa',
  'co.uk': 'United Kingdom'
};

הדוגמה של תפריט ההקשר הגלובלי של חיפוש Google יוצרת כמה אפשרויות מהרשימה ב-locales.js . אם תוסף מכיל יותר מתפריט הקשר אחד, Google Chrome מכווץ אותם באופן אוטומטי לתפריט הראשי.

כמה תפריטי הקשר יצטמצמו

פקודות

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

{
  "name": "Tab Flipper",
  ...
  "commands": {
    "flip-tabs-forward": {
      "suggested_key": {
        "default": "Ctrl+Shift+Right",
        "mac": "Command+Shift+Right"
      },
      "description": "Flip tabs forward"
    },
    "flip-tabs-backwards": {
      "suggested_key": {
        "default": "Ctrl+Shift+Left",
        "mac": "Command+Shift+Left"
      },
      "description": "Flip tabs backwards"
    }
  }
  ...
}

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

chrome.commands.onCommand.addListener(function(command) {
  chrome.tabs.query({currentWindow: true}, function(tabs) {
    // Sort tabs according to their index in the window.
    tabs.sort((a, b) => { return a.index < b.index; });
    let activeIndex = tabs.findIndex((tab) => { return tab.active; });
    let lastTab = tabs.length - 1;
    let newIndex = -1;
    if (command === 'flip-tabs-forward')
      newIndex = activeIndex === 0 ? lastTab : activeIndex - 1;
    else  // 'flip-tabs-backwards'
      newIndex = activeIndex === lastTab ? 0 : activeIndex + 1;
    chrome.tabs.update(tabs[newIndex].id, {active: true, highlighted: true});
  });
});

פקודות יכולות גם ליצור שיוך מקשים שפועל במיוחד עם התוסף שלהן. בדוגמה Hello Extensions (שלום תוספים) מופיעה פקודה לפתיחת החלון הקופץ.

{
  "name": "Hello Extensions",
  "description" : "Base Level Extension",
  "version": "1.0",
  "browser_action": {
    "default_popup": "hello.html",
    "default_icon": "hello_extensions.png"
  },
  "manifest_version": 2,
  "commands": {
    "_execute_browser_action": {
      "suggested_key": {
        "default": "Ctrl+Shift+F",
        "mac": "MacCtrl+Shift+F"
      },
      "description": "Opens hello.html"
    }
  }
}

מכיוון שהתוסף מגדיר browser_action, הוא יכול לציין את "execute_browser_action" בפקודות לפתיחת קובץ החלון הקופץ בלי לכלול סקריפט לרקע. אם משתמשים ב-page_action, אפשר להחליף אותו ב-"execute_page_action". אפשר להשתמש באותה תוסף גם בפקודות של הדפדפן וגם בפקודות של התוסף.

שינוי דפים

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

רושמים דף חלופי במניפסט בשדה "chrome_url_overrides".

{
  "name": "Awesome Override Extension",
  ...

  "chrome_url_overrides" : {
    "newtab": "override_page.html"
  },
  ...
}

כשמבטלים את ההגדרה של הדפים האלה, צריך להחליף את השדה "newtab" ב-"bookmarks" או ב-"history".

<html>
  <head>
  <title>New Tab</title>
  </head>
  <body>
    <h1>Hello World</h1>
  <script src="logic.js"></script>
  </body>
</html>