يجب أن تكون واجهة مستخدم الإضافة هادفة وبسيطة. وعلى غرار الإضافات نفسها، يجب أن تخصّص واجهة المستخدم تجربة التصفّح أو تحسّنها بدون أن تشتّت الانتباه عنها.
يستكشف هذا الدليل ميزات واجهة المستخدم المطلوبة والاختيارية. يمكن استخدامه لفهم كيفية تنفيذ عناصر واجهة المستخدم المختلفة ومتى يجب تنفيذها ضمن إحدى الإضافات.
تفعيل الإضافة على جميع الصفحات
يجب استخدام 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 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.
تفحص إضافة عيّنة 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 وحدة مستقلة عن الجهاز. يُنصح باستخدام الحجمَين 16×16 و32×32 على الأقل.
{
"name": "My Awesome page_action Extension",
...
"page_action": {
"default_icon": {
"16": "extension_toolbar_icon16.png",
"32": "extension_toolbar_icon32.png"
}
}
...
}
يجب أن تكون جميع الرموز مربّعة، وإلا قد يتم تشويهها. إذا لم يتم توفير أي رموز، سيضيف Chrome رمزًا عامًا إلى شريط الأدوات.
إنشاء رموز إضافية وتسجيلها
يجب تضمين رموز إضافية بالأحجام التالية لاستخدامها خارج شريط الأدوات.
| حجم الرمز | استخدام الرمز |
|---|---|
| 16x16 | الرمز المفضّل على صفحات الإضافة |
| 32x32 | غالبًا ما تتطلب أجهزة الكمبيوتر التي تعمل بنظام التشغيل Windows هذا الحجم. سيمنع توفير هذا الخيار تشويه الحجم الناتج عن تقليص الخيار 48×48. |
| 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});
});
يتم تنفيذ السلاسل الخاصة بالإعدادات المحلية باستخدام ميزة التدويل. يمكن إنشاء أدلة لتضمين الرسائل الخاصة باللغة ضِمن مجلد باسم _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" في المربّع المتعدد الاستخدامات، يتم تفعيل الإضافة. للإشارة إلى ذلك، يتم عرض الرمز 16×16 المقدَّم باللون الرمادي وتضمينه في المربّع المتعدد الاستخدامات بجانب اسم الإضافة.
تستمع الإضافة إلى الحدث 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"
}
}
...
}
يمكن استخدام الأوامر لتوفير اختصارات جديدة أو بديلة للمتصفّح. تستمع إضافة عيّنة تبديل علامات التبويب إلى الحدث 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 طلبًا صوتيًا لفتح النافذة المنبثقة.
{
"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>