رابط کاربری را طراحی کنید

رابط کاربری افزونه باید هدفمند و مینیمال باشد. درست مانند خود افزونه‌ها، رابط کاربری باید تجربه مرور را بدون اینکه حواس کاربر را پرت کند، سفارشی یا بهبود بخشد.

این راهنما ویژگی‌های رابط کاربری مورد نیاز و اختیاری را بررسی می‌کند. از آن برای درک چگونگی و زمان پیاده‌سازی عناصر مختلف رابط کاربری در یک افزونه استفاده کنید.

فعال کردن افزونه در تمام صفحات

وقتی ویژگی‌های یک افزونه در بیشتر مواقع کاربردی هستند، از 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 در یک اسکریپت پس‌زمینه ، قوانینی را برای زمان قابل استفاده بودن افزونه تعریف کنید. افزونه Page action by URL sample شرطی را تعیین می‌کند که 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 به صورت پویا فعال و غیرفعال شوند.

The Mappy sample extension scans a web page for an address and shows its location on a static map in the popup . Because the extension is dependent on page content, it cannot declare rules to predict which pages will be relevant. Instead, if an address is found on a page it calls pageAction.show to colorize the icon and signal the extension is usable on that tab.

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 در فایل مانیفست ثبت می‌شوند. برای مقیاس‌بندی فضای ۱۶-dip، گنجاندن چندین اندازه توصیه می‌شود. حداقل، اندازه‌های ۱۶x۱۶ و ۳۲x۳۲ توصیه می‌شوند.

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

همه آیکون‌ها باید مربع باشند، در غیر این صورت ممکن است کج و معوج شوند. اگر هیچ آیکونی ارائه نشده باشد، کروم یک آیکون عمومی به نوار ابزار اضافه می‌کند.

ایجاد و ثبت آیکون‌های اضافی

برای استفاده‌های خارج از نوار ابزار، آیکون‌های اضافی در اندازه‌های زیر اضافه کنید.

آیکن‌ها را در فایل مانیفست، زیر فیلد "icons" ثبت کنید.

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

ویژگی‌های رابط کاربری اضافی

پاپ‌آپ

یک پنجره بازشو (popup) یک فایل HTML است که وقتی کاربر روی آیکون نوار ابزار کلیک می‌کند، در یک پنجره خاص نمایش داده می‌شود. یک پنجره بازشو بسیار شبیه به یک صفحه وب عمل می‌کند؛ می‌تواند شامل لینک‌هایی به stylesheets و تگ‌های اسکریپت باشد، اما جاوا اسکریپت درون‌خطی را مجاز نمی‌داند.

پنجره‌ی بازشو مثال رویداد نوشیدن آب، گزینه‌های تایمر موجود را نمایش می‌دهد. کاربران با کلیک روی یکی از دکمه‌های ارائه شده، زنگ هشدار را تنظیم می‌کنند.

<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 ، Tooltipها را تنظیم یا به‌روزرسانی کرد.

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" را در مانیفست وارد کنید و یک کلمه کلیدی تعیین کنید. افزونه نمونه Omnibox New Tab Search از "nt" به عنوان کلمه کلیدی استفاده می‌کند.

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

وقتی کاربر "nt" را در omnibox تایپ می‌کند، افزونه فعال می‌شود. برای اطلاع دادن به کاربر، آیکون 16x16 ارائه شده را خاکستری می‌کند و آن را در omnibox کنار نام افزونه قرار می‌دهد.

این افزونه به رویداد omnibox.onInputEntered گوش می‌دهد. پس از فعال شدن، افزونه یک تب جدید حاوی جستجوی گوگل برای ورودی کاربر باز می‌کند.

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"
  }
  ...
}

آیکون ۱۶x۱۶ در کنار ورودی جدید منو نمایش داده می‌شود.

با فراخوانی 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'
};

مثال منوی زمینه جستجوی سراسری گوگل، چندین گزینه از لیست موجود در locales.js ایجاد می‌کند. وقتی یک افزونه شامل بیش از یک منوی زمینه باشد، گوگل کروم به طور خودکار آنها را در یک منوی والد واحد قرار می‌دهد.

دستورات

افزونه‌ها می‌توانند دستورات خاصی را تعریف کرده و آنها را به یک ترکیب کلید متصل کنند. یک یا چند دستور را در مانیفست، در قسمت "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" جایگزین کرد. هر دو دستور مرورگر و افزونه را می‌توان در یک افزونه استفاده کرد.

صفحات را نادیده بگیرید

یک افزونه می‌تواند صفحه وب History، New Tab یا Bookmarks را با یک فایل HTML سفارشی لغو و جایگزین کند. مانند یک پنجره بازشو ، می‌تواند شامل منطق و سبک خاصی باشد، اما جاوا اسکریپت درون خطی را مجاز نمی‌کند. یک افزونه واحد محدود به لغو تنها یکی از سه صفحه ممکن است.

یک صفحه‌ی بازنویسی‌شده را در مانیفست، زیر فیلد "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>