تصميم واجهة المستخدم

يجب أن تكون واجهة مستخدم الإضافة هادفة وبسيطة. وتمامًا مثل الإضافات نفسها، يجب أن تخصص واجهة المستخدم تجربة التصفح أو تحسّنها بدون تشتيت انتباهها.

يستكشف هذا الدليل الميزات المطلوبة والاختيارية لواجهة المستخدم. استخدمها لفهم كيف ومتى يتم تنفيذ عناصر واجهة المستخدم المختلفة داخل الإضافة.

تفعيل الإضافة في جميع الصفحات

استخدِم 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	الرمز المفضّل على صفحات الإضافات
32×32	غالبًا ما تتطلب أجهزة الكمبيوتر التي تعمل بنظام التشغيل Windows هذا الحجم. سيؤدي توفير هذا الخيار إلى منع تشوّه الحجم من تقليص خيار 48×48.
48×48	على صفحة إدارة الإضافات
128×128	عند التثبيت وفي سوق 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});
});

يتم تنفيذ السلاسل المحلية المتخصّصة من خلال الانتشار على نطاق عالمي. أنشئ أدلة لرسائل خاصة بلغة محدّدة داخل مجلد يسمى _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"
  }
  ...
}

يتم عرض الرمز 16×16 بجوار إدخال القائمة الجديد.

أنشِئ قائمة سياقات من خلال استدعاء 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});
  });
});

ويمكن للأوامر أيضًا إنشاء ربط مفتاح يعمل بشكل خاص مع الإضافة. يعطي مثال إضافات مرحبًا أمرًا لفتح النافذة المنبثقة.

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