דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

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

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

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

הוספת תג

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

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

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

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

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

<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>

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

{
  "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" ב: את המניפסט ולהגדיר מילת מפתח. התוסף לדוגמה של חיפוש בכרטיסייה חדשה בסרגל הכתובות משתמש ב-"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 בסקריפט הרקע. הזה צריך לבצע אותו במסגרת אירוע ההאזנה 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>