الخطوات الأولى

تكون الإضافات مصنوعة من مكونات مختلفة ولكنها متماسكة. ويمكن أن تتضمن المكونات النصوص البرمجية الخلفية والنصوص البرمجية للمحتوى وصفحة الخيارات وعناصر واجهة المستخدم وملفات منطقية مختلفة. يتم إنشاء مكوّنات الإضافات باستخدام تقنيات تطوير الويب، وهي: HTML وCSS وJavaScript. تعتمد مكونات الإضافة على وظائفها وقد لا تتطلب كل الخيارات.

سينشئ هذا الدليل التوجيهي إضافة تتيح للمستخدم تغيير لون خلفية أي صفحة على developer.chrome.com. سيستخدم هذا البرنامج العديد من المكوّنات الأساسية لتقديم عرض تقديمي تعريفي حول العلاقات.

للبدء، أنشئ دليلاً جديدًا للاحتفاظ بملفات الإضافة.

يمكن العثور على الإضافة المكتملة هنا.

إنشاء البيان

تبدأ الإضافات ببيانها. أنشئ ملفًا باسم manifest.json وضمِّن الرمز التالي.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "manifest_version": 2
}

يمكن إضافة الدليل الذي يحتوي على ملف البيان كامتداد في وضع مطوّر البرامج في حالته الحالية.

  1. افتح صفحة "إدارة الإضافات" عن طريق الانتقال إلى chrome://extensions.
    • يمكن أيضًا فتح صفحة إدارة الإضافات من خلال النقر على قائمة Chrome وتمرير مؤشر الماوس فوق المزيد من الأدوات ثم اختيار الإضافات.
  2. فعِّل "وضع مطوّر البرامج" من خلال النقر على مفتاح التبديل بجانب وضع مطوّر البرامج.
  3. انقر على الزر تم إلغاء تحميل الحزمة واختر دليل الإضافة.

تحميل الإضافة

بهذه السهولة! تم تثبيت الإضافة بنجاح. نظرًا لعدم تضمين أي أيقونات في البيان، سيتم إنشاء رمز عام لشريط الأدوات للإضافة.

إضافة تعليمات

على الرغم من أنه قد تم تثبيت الإضافة، فهي لا تحتوي على أي تعليمات. قدِّم نصًا برمجيًا للخلفية من خلال إنشاء ملف بعنوان background.js، ووضعه داخل دليل الإضافة.

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

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "manifest_version": 2
}

أصبحت الإضافة الآن تدرك أنّها تتضمّن نصًا برمجيًا غير دائم للخلفية وستفحص الملف المسجّل بحثًا عن الأحداث المهمة التي يحتاج إلى رصدها.

ستحتاج هذه الإضافة إلى معلومات من متغير دائم فور تثبيتها. ابدأ بتضمين حدث استماع لـ runtime.onInstalled في النص البرمجي للخلفية. داخل أداة معالجة onInstalled، ستضبط الإضافة قيمة باستخدام واجهة برمجة التطبيقات storage. سيسمح هذا لمكونات إضافات متعددة بالوصول إلى هذه القيمة وتحديثها.

chrome.runtime.onInstalled.addListener(function() {
  chrome.storage.sync.set({color: '#3aa757'}, function() {
    console.log("The color is green.");
  });
});

يجب تسجيل معظم واجهات برمجة التطبيقات، بما في ذلك واجهة برمجة التطبيقات storage، ضمن الحقل "permissions" في بيان الإضافة لكي تستخدمها.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "manifest_version": 2
}

انتقِل مرة أخرى إلى صفحة إدارة الإضافة وانقر على الرابط إعادة التحميل. يصبح حقل جديد، وهو فحص الملفات الشخصية، متاحًا مع رابط أزرق، وهو صفحة الخلفية.

فحص طرق العرض

انقر على الرابط لعرض سجل وحدة تحكّم النص البرمجي للخلفية "The color is green."

تقديم واجهة مستخدم

يمكن أن تحتوي الإضافات على أشكال عديدة من واجهة المستخدم، ولكن سيتم استخدام نافذة منبثقة في هذه الإضافة. أنشئ ملفًا بعنوان popup.html وأضِفه إلى الدليل. تستخدم هذه الإضافة زرًا لتغيير لون الخلفية.

<!DOCTYPE html>
<html>
  <head>
    <style>
      button {
        height: 30px;
        width: 30px;
        outline: none;
      }
    </style>
  </head>
  <body>
    <button id="changeColor"></button>
  </body>
</html>

مثل النص البرمجي للخلفية، يجب تحديد هذا الملف كنافذة منبثقة في ملف البيان ضمن page_action.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html"
  },
  "manifest_version": 2
}

يتم أيضًا تضمين تعيين رموز شريط الأدوات ضمن page_action في حقل default_icons. نزِّل مجلد الصور هنا وفك ضغطه وضَعه في دليل الإضافة. عليك تعديل البيان حتى تعرف الإضافة كيفية استخدام الصور.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/get_started16.png",
      "32": "images/get_started32.png",
      "48": "images/get_started48.png",
      "128": "images/get_started128.png"
    }
  },
  "manifest_version": 2
}

وتعرض الإضافات أيضًا صورًا في صفحة إدارة الإضافات والتحذيرات بشأن الأذونات والرمز المفضّل. تم تحديد هذه الصور في البيان ضمن icons.

{
  "name": "Getting Started Example",
  "version": "1.0",
  "description": "Build an Extension!",
  "permissions": ["storage"],
  "background": {
    "scripts": ["background.js"],
    "persistent": false
  },
  "page_action": {
    "default_popup": "popup.html",
    "default_icon": {
      "16": "images/get_started16.png",
      "32": "images/get_started32.png",
      "48": "images/get_started48.png",
      "128": "images/get_started128.png"
    }
  },
  "icons": {
    "16": "images/get_started16.png",
    "32": "images/get_started32.png",
    "48": "images/get_started48.png",
    "128": "images/get_started128.png"
  },
  "manifest_version": 2
}

وفي حال إعادة تحميل الإضافة في هذه المرحلة، سيتم تضمين رمز تدرّج الرمادي، ولكن لن تحتوي على أي اختلافات في الوظائف. بما أنّه قد تم تعريف page_action في ملف البيان، يعود إلى الإضافة إبلاغ المتصفّح عندما يمكن للمستخدم التفاعل مع popup.html.

يمكنك إضافة القواعد التي تم تضمينها في نموذج البيان إلى النص البرمجي للخلفية باستخدام واجهة برمجة التطبيقات declarativeContent ضمن حدث أداة معالجة الحدث في runtime.onInstalled.

chrome.runtime.onInstalled.addListener(function() {
  chrome.storage.sync.set({color: '#3aa757'}, function() {
    console.log('The color is green.');
  });
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([{
      conditions: [new chrome.declarativeContent.PageStateMatcher({
        pageUrl: {hostEquals: 'developer.chrome.com'},
      })
      ],
          actions: [new chrome.declarativeContent.ShowPageAction()]
    }]);
  });
});

ستحتاج الإضافة إلى إذن للوصول إلى واجهة برمجة التطبيقات declarativeContent في ملف البيان الخاص بها.

{
  "name": "Getting Started Example",
...
  "permissions": ["declarativeContent", "storage"],
...
}

نافذة منبثقة

سيعرض المتصفّح الآن رمز إجراء على الصفحة بالألوان الكاملة في شريط أدوات المتصفّح عندما ينتقل المستخدمون إلى عنوان URL يتضمّن "developer.chrome.com". عندما تكون الأيقونة ملونة بالكامل، يمكن للمستخدمين النقر فوقها لعرض webup.html.

الخطوة الأخيرة في واجهة المستخدم المنبثقة هي إضافة اللون إلى الزر. أنشئ ملفًا اسمه popup.js يتضمّن الرمز التالي وأضِفه إلى دليل الإضافات.

let changeColor = document.getElementById('changeColor');

chrome.storage.sync.get('color', function(data) {
  changeColor.style.backgroundColor = data.color;
  changeColor.setAttribute('value', data.color);
});

يحصل هذا الرمز على الزر من popup.html ويطلب قيمة اللون من مساحة التخزين. ثم يطبق اللون كخلفية للزر. تضمين علامة نص برمجي لـ "popup.js" في popup.html

<!DOCTYPE html>
<html>
...
  <body>
    <button id="changeColor"></button>
    <script src="popup.js"></script>
  </body>
</html>

يُرجى إعادة تحميل الإضافة لعرض الزر الأخضر.

منطق الطبقة

تدرك الإضافة الآن أنّ النافذة المنبثقة يجب أن تكون متاحة للمستخدمين على developer.chrome.com وتعرض زرًّا ملوّنًا، ولكنّها تحتاج إلى منطق لإجراء مزيد من تفاعل المستخدمين. يجب تحديث popup.js لتضمين الرمز التالي.

let changeColor = document.getElementById('changeColor');
...
changeColor.onclick = function(element) {
  let color = element.target.value;
  chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
    chrome.tabs.executeScript(
        tabs[0].id,
        {code: 'document.body.style.backgroundColor = "' + color + '";'});
  });
};

يضيف الرمز المعدّل حدث onclick على الزر، ما يؤدي إلى تشغيل نص برمجي للمحتوى الذي تم إدخاله آليًا. يؤدي هذا إلى تحويل لون خلفية الصفحة إلى لون الزر نفسه. يسمح استخدام ميزة "الإدخال الآلي" بالنصوص البرمجية للمحتوى التي يستدعيها المستخدم، بدلاً من الإدراج التلقائي للرمز غير المرغوب فيه في صفحات الويب.

سيحتاج البيان إلى إذن activeTab للسماح للإضافة بالوصول المؤقت إلى واجهة برمجة التطبيقات tabs. يسمح هذا للإضافة بطلب tabs.executeScript.

{
  "name": "Getting Started Example",
...
  "permissions": ["activeTab", "declarativeContent", "storage"],
...
}

تعمل الإضافة الآن بكامل طاقتها. أعد تحميل الإضافة، وحدّث هذه الصفحة، وافتح النافذة المنبثقة، وانقر على الزر لتحويلها إلى اللون الأخضر! ومع ذلك، قد يرغب بعض المستخدمين في تغيير الخلفية إلى لون مختلف.

منح المستخدمين خيارات

تسمح الإضافة حاليًا للمستخدمين بتغيير الخلفية إلى اللون الأخضر فقط. إنّ تضمين صفحة خيارات يمنح المستخدمين مزيدًا من التحكّم في وظائف الإضافة، ما يؤدي إلى تخصيص تجربة التصفّح بشكل أكبر.

ابدأ بإنشاء ملف في الدليل يُسمى options.html وضمّن الرمز التالي.

<!DOCTYPE html>
<html>
  <head>
    <style>
      button {
        height: 30px;
        width: 30px;
        outline: none;
        margin: 10px;
      }
    </style>
  </head>
  <body>
    <div id="buttonDiv">
    </div>
    <div>
      <p>Choose a different background color!</p>
    </div>
  </body>
  <script src="options.js"></script>
</html>

ثم قم بتسجيل صفحة الخيارات في البيان،

{
  "name": "Getting Started Example",
  ...
  "options_page": "options.html",
  ...
  "manifest_version": 2
}

أعِد تحميل الإضافة وانقر على التفاصيل.

فحص طرق العرض

مرر لأسفل صفحة التفاصيل وحدد خيارات الإضافة لعرض صفحة الخيارات، على الرغم من أنها ستظهر فارغة حاليًا.

خيارات الإضافات

الخطوة الأخيرة هي إضافة منطق الخيارات. أنشئ ملفًا يسمى options.js في دليل الإضافات باستخدام الرمز التالي.

let page = document.getElementById('buttonDiv');
const kButtonColors = ['#3aa757', '#e8453c', '#f9bb2d', '#4688f1'];
function constructOptions(kButtonColors) {
  for (let item of kButtonColors) {
    let button = document.createElement('button');
    button.style.backgroundColor = item;
    button.addEventListener('click', function() {
      chrome.storage.sync.set({color: item}, function() {
        console.log('color is ' + item);
      })
    });
    page.appendChild(button);
  }
}
constructOptions(kButtonColors);

يتم تقديم أربعة خيارات للألوان بعد ذلك يتم إنشاؤها كأزرار في صفحة الخيارات مع مستمعي أحداث نقرة. عندما ينقر المستخدم على زر، يتم تحديث قيمة اللون في مساحة التخزين العامة للإضافة. نظرًا لأن جميع ملفات الإضافات تسحب معلومات اللون من مساحة التخزين العامة، فلا حاجة إلى تحديث أي قيم أخرى.

اتخاذ الخطوة التالية

تهانينا! يتضمن الدليل الآن إضافة Chrome كاملة الوظائف، وإن كانت بسيطة،

ما هي الخطوات التالية؟