Skip to content

Content Script و Service Worker: عقل الإضافة وأدواتها ​

في الدرس السابق جهّزت هيكل الإضافة باستخدام manifest.json. في هذا الدرس ستتعرف على أهم دورين في الإضافة: service worker هو العقل، يبقى في الخلفية يستجيب للأحداث؛ content script هو الأدوات (اليدان والقدمان)، يتسلل إلى صفحة الويب ليقرأها ويعدّلها. حين تميّز بين هذين الدورين، تستطيع أن توضّح متطلباتك، ويستطيع الذكاء الاصطناعي أن يضع الكود في الملف الصحيح.

ماذا ستستطيع أن تفعل بعد هذا الدرس ​

  • توضيح ما يستطيع content script و service worker كلٌّ منهما فعله وما لا يستطيعانه
  • إعلان background service worker و content_scripts في manifest.json وجعلهما يعملان فعلاً
  • التحقق بنفسك من «عالم العزل (isolated world)»: صفحة الويب وسكربتك لا يريان متغيرات JS الخاصة ببعضهما، لكنهما تتشاركان في DOM واحد
  • معرفة أين تظهر سجلات كل منهما — وهذا أساس التصحيح في الدرس القادم

مأزقك الحالي ​

  • طلبت من الذكاء الاصطناعي كتابة إضافة، فأنشأ service-worker.js و content-script.js دفعة واحدة، وأنت لا تعرف لماذا يوجد ملفان وما الذي يديره كل منهما
  • السكربت حُقن في الصفحة فعلًا، لكنه لا يستطيع قراءة متغيرات الصفحة نفسها؛ وحين أردت تعديل الصفحة من الخلفية، قال الذكاء الاصطناعي «مستحيل»
  • كتبت console.log في الكود لكنك لا تجد المخرجات: ليست في صفحة الإضافة ولا في وحدة تحكم صفحة الويب

متى تستخدم هذه الطريقة ​

هذا الدرس مناسب لك إذا كنت: تريد منح إضافتك قدرة «تعديل صفحات الويب» أو «الاستجابة لأحداث المتصفح في الخلفية»، أو تريد فهم بنية ملفات الإضافة التي ينشئها الذكاء الاصطناعي.

ولا تريد: وضع الكود في الملف الخطأ والعودة مرارًا، أو الوقوع في خطأ دون أن تعرف أين تبحث عن السجلات.

🎒 الاستعداد قبل البدء ​

  • أن تقرأ الدرس السابق«شرح manifest.json: مرجع سريع لحقول MV3»
  • أن يكون لديك مشروع إضافة يمكن تحميله محليًا عبر Load unpacked (مثل Hello Extensions يكفي)
  • أن تعرف كيفية فتح chrome://extensions وإعادة تحميل الإضافة (بالنقر على أيقونة التحديث في بطاقة الإضافة)
  • أن تعرف كيفية فتح DevTools لصفحة الويب (زر يمين على الصفحة ← «فحص») لعرض Console

الفكرة الأساسية ​

تخيّل الإضافة كشخص:

  • service worker (العقل، أي سكربت خلفية الإضافة): تسميه الوثائق الرسمية «central event handler» (مركز الأحداث) للإضافة. لا يرتبط بأي صفحة، بل ينتظر الأحداث في خلفية المتصفح — إغلاق التبويبات، والنقر على الإشعارات، والانتقال إلى صفحة جديدة كلها من اختصاصه؛ «يُحمَّل عند الحاجة ويُفرَّغ عند الخمول». وهولا يستطيع الوصول إلى DOM، وإذا أراد تعديل الصفحة فلا يمكنه إلا أن يكلّف content script بذلك.
  • content script (اليدان والقدمان): تعرّفه الوثائق الرسمية بأنه «ملف يعمل في بيئة صفحة الويب»، يستخدم DOM القياسي لقراءة الصفحة وتعديلها وإعادة المعلومات إلى جسم الإضافة.
  • عالم العزل (isolated world): يعيش content script في بيئة تنفيذ خاصة، لا تستطيع صفحة الويب ولا الإضافات الأخرى الوصول إليها؛ وهو بدوره لا يرى متغيرات JS الخاصة بصفحة الويب. لكن DOM مشترك — الطرفان يريان الصفحة نفسها.
content script (اليدان والقدمان)service worker (العقل)
مكان التشغيلداخل صفحة ويب محددةخلفية المتصفح، دون ارتباط بأي صفحة
هل يمكنه التعامل مع DOM✅ يقرأ ويعدّل❌ لا يمكن
دورة الحياةيتبع الصفحةيُقلع عند الحاجة ويتوقف عند الخمول
واجهات برمجة الإضافات المتاحة مباشرةعدد قليل (dom، و i18n، و storage، وبعض دوال runtime)كمركز أحداث يستجيب لمختلف أحداث الإضافة
المهام النموذجيةتعديل مظهر الصفحة وقراءة محتواهاالاستماع لأحداث التبويبات/الإشعارات وغيرها وإدارة التبويبات
أين تُشاهد السجلاتوحدة Console لصفحة الويب المضيفةInspect views في صفحة الإضافة

💡 الدروس القديمة لا تتطابق؟

‏"background script" في دروس MV2 القديمة هو نفسه service worker اليوم — الاسم تغيّر، لكن الدور لم يتغير. الآن تُكتب الإضافات بنمط MV3 فقط، فلا تنسخ الكود القديم كما هو.

اتبعني خطوة بخطوة ​

الخطوة 1: إعلان service worker (سكربت خلفية الإضافة) ​

لماذا: يجب تسجيل العقل أولاً حتى تعرف Chrome من تُطلقه في الخلفية.

أضف هذا المقطع إلى manifest.json background:

json
"background": {
  "service_worker": "service-worker.js"
}

أنشئ service-worker.js في المجلد الجذري للإضافة:

js
console.log("service worker 已启动");

عُد إلى chrome://extensions وأعد تحميل الإضافة.

ينبغي أن ترى: ظهور منطقة Inspect views على بطاقة الإضافة، وبجانبها رابط أزرق لـ service worker؛ انقر عليه وستجد سجلاتك في Console ضمن DevTools.

💡 السجلات «تختفي» بعد قليل؟

‏service worker يُقلع عند الحاجة ويتوقف عند الخمول. إذا نام بعد قليل فهذا لا يعني أنه تعطّل — عند وقوع الحدث التالي سيستيقظ من تلقاء نفسه.

  • فحص صغير: أن ترى «service worker قد بدأ» في DevTools الذي يُفتح من Inspect views

الخطوة 2: كتابة أول content script (حقن ثابت عبر content_scripts) ​

لماذا: الأطراف لا تنمو من تلقاء نفسها — يجب الإعلان عنها بشكل ثابت في manifest باستخدام content_scripts حتى تُحقن تلقائيًا في المواقع التي تحددها.

أضِف في manifest.json (matches إلزامي، ويحدد الصفحات التي ستُحقن فيها؛ فيما يلي مثال من الوثائق الرسمية، استبدل اسم النطاق بالموقع الذي تريد التأثير فيه فعلًا):

json
"content_scripts": [
  {
    "matches": ["https://*.nytimes.com/*"],
    "js": ["content-script.js"]
  }
]

يوجد في المثال الرسمي أيضًا سطر "css": ["my-styles.css"] — يمكن لـ content script أن يحقن JS فقط، أو CSS فقط، أو كليهما، حسب الحاجة.

أنشئ content-script.js في الدليل الجذري للإضافة:

js
console.log("[content script] 注入成功,页面标题:", document.title);
document.body.style.border = "5px solid red";

أعد تحميل الإضافة، ثم حدّث الصفحة المستهدفة — بعد تعديل content script يجب تنفيذ الخطوتين معًا: «إعادة تحميل الإضافة + تحديث الصفحة المضيفة».

يجب أن ترى: إطار أحمر حول الصفحة المستهدفة؛ وفي Console في DevTools الخاص بالصفحة توجد السجلات التي طبعتها (انتبه: المقصود Console الصفحة، وليس Console صفحة الإضافة).

  • تحقق سريع: الإطار الأحمر يظهر، ويمكن رؤية سجلات content script في Console الصفحة

الخطوة 3: تحقق بنفسك من العالم المعزول (isolated world) ​

لماذا: هذا أكثر ما يربك المبتدئين — «السكربت يعمل في الصفحة بوضوح، فلماذا لا يقرأ متغيراتها؟» الإجابة هي العالم المعزول، ورؤيته بيديك أوضح طريقة.

عدّل content-script.js ليصبح:

js
var extVar = "我来自插件";
console.log("[content script] 我能读到页面标题:", document.title);
document.body.style.border = "5px solid red";

// 5 秒后再读网页变量,留时间给你在网页控制台定义它
setTimeout(function () {
  console.log("[content script] 读网页变量 pageVar:", window.pageVar);
}, 5000);

أعد تحميل الإضافة + حدّث الصفحة، ثم خلال 5 ثوانٍ انتقل إلى Console الصفحة وأدخِل:

js
var pageVar = "我是网页自己的变量";

بعد ظهور سجل الـ 5 ثوانٍ، أدخِل في Console الصفحة كلًا من extVar وdocument.body.style.border.

يجب أن ترى:

  • content script يطبع 读网页变量 pageVar:undefined — لا يرى متغيرات الصفحة

  • إدخال extVar في Console الصفحة يرمي ReferenceError — الصفحة أيضًا لا ترى متغيراتك

  • document.body.style.border يُرجع "5px solid red" — DOM مشترك بين الطرفين

  • تحقق سريع: رأيت الظواهر الثلاث بعينيك، وتطابق مع عبارة «المتغيرات معزولة، وDOM مشترك»

الخطوة 4: وزّع المهام على الدور الصحيح (متى تستخدم من) ​

لماذا: عندما تفرّق بين الدماغ والأطراف، تستطيع إيصال متطلباتك إلى الذكاء الاصطناعي بشكل صحيح، فلا يكتب الكود في الملف الخطأ.

متطلبكإلى من تُسنده
حقن كود في صفحة معينة وتعديل الصفحةcontent script
لا يعتمد على الصفحة، ينتظر الأحداث في الخلفية، يراقب سلوك المتصفح، يعرض الإشعارات / يدير علامات التبويبservice worker
نافذة صغيرة (popup) تظهر عند النقر على أيقونة شريط الأدواتaction + popup
اعتراض طلبات الشبكة أو حظرها أو تعديلهاdeclarativeNetRequest

واجهات برمجة التطبيقات (API) الخاصة بالإضافة التي يمكن لـ content script استخدامها مباشرة قليلة جدًا — ما تذكره الوثائق الرسمية هو أجزاء من dom وi18n وstorage وruntime (مثل runtime.sendMessage() وruntime.onMessage). لاستخدام واجهات أخرى، يجب التحويل عبر الرسائل إلى service worker لينجزها نيابة عنك — لهذا يظهر هذان الملفان معًا غالبًا، وليس لأن الذكاء الاصطناعي كتب زيادة.

يجب أن ترى: قارن الكود الذي أنشأه الذكاء الاصطناعي بهذا الجدول — منطق تعديل الصفحة موجود في content-script.js، ومراقبة الأحداث في service-worker.js — كلٌّ في مكانه، فتفهم بنية الإضافة.

نقطة التحقق ✅ ​

  • يمكن لـ Inspect views في صفحة الإضافة فتح DevTools الخاص بـ service worker ورؤية سجلات الإقلاع
  • تعديلات content script تظهر على الصفحة المستهدفة، والسجلات في Console الصفحة
  • يمكنك التوضيح: متغيرات الصفحة ومتغيرات content script لا يرى أحدهما الآخر، وDOM مشترك
  • يمكنك تحديد الدور الذي يُسند إليه كل نوع من أنواع 4 من المتطلبات
  • تعرف أنه بعد تعديل content script يجب تنفيذ الخطوتين «إعادة تحميل الإضافة + تحديث الصفحة»

تنبيهات للمزالق ​

❌ كتابة document.querySelector(...) داخل service worker ​

السبب: لا يستطيع service worker الوصول إلى DOM، لذا سيفشل هذا الكود حتمًا.

الطريقة الصحيحة: سلّم كل ما يخص تعديل الصفحة إلى content script؛ أما service worker فلا يهتم إلا بالأحداث، وعند الحاجة إلى تعديل الصفحة يكلّف content script عبر الرسائل.

❌ استدعاء واجهات برمجة تطبيقات أخرى للإضافة مباشرة داخل content script ​

السبب: تقول الوثائق الرسمية بوضوح إن content script «unable to access other APIs directly» — لا يستطيع استخدام سوى أجزاء من dom وi18n وstorage وruntime مباشرة.

الطريقة الصحيحة: استخدم runtime.sendMessage() لإعادة توجيه الطلب إلى service worker، لينجزه ثم يعيد النتيجة.

❌ عدّلت content script لكن الصفحة لم تتغير ​

السبب: تعديلات content script تتطلب خطوتين: «إعادة تحميل الإضافة + تحديث الصفحة المضيفة»، وبأي خطوة ناقصة لن ترى التأثير.

الطريقة الصحيحة: عد أولًا إلى chrome://extensions لإعادة التحميل، ثم حدّث الصفحة المستهدفة.

❌ البحث عن console.log الخاص بـ content script في صفحة الإضافة ​

السبب: زر Errors في صفحة الإضافة يسجل فقط runtime errors وconsole.warning وconsole.error، ولا يسجل console.log العادي؛ أما سجلات content script فهي في Console الصفحة المضيفة.

الطريقة الصحيحة: سجلات content script تُرى في الصفحة؛ وسجلات service worker فقط في Inspect views بصفحة الإضافة. وإذا لم تجد رسالة الخطأ، عد أولًا إلى«حلقة الأخطاء: أعد تغذية رسالة الخطأ كما هي» وأعطِ رسالة الخطأ للذكاء الاصطناعي كما هي.

نصائح متقدمة ​

  • إلى جانب الإعلان الثابت توجد طريقتان أخريان للحقن: الإعلان الديناميكي chrome.scripting.registerContentScripts (Chrome 96+)، والحقن البرمجي scripting.executeScript (تحقنه الإضافة عند الحاجة، مثلًا عند النقر على أيقونة شريط الأدوات؛ ويتطلب إذن host أو تفويضًا مؤقتًا activeTab).
  • الدرجات التالية من الدرس الرسمي تتناول الأدوار بالترتيب: Run scripts on every page وInject scripts into the active tab وHandle events with service workers — يمكنك متابعتها مباشرة بعد إنهاء هذا الدرس.
  • لإختبار سُبات service worker واستيقاظه: افتح في DevTools الخاص به لوحة Application → Service Workers وشغّله/أوقفه يدويًا. انتبه: فحص (Inspect) service worker يبقيه نشطًا باستمرار، فتذكّر إغلاق DevTools بعد الانتهاء من الاختبار.

خلاصة الدرس ​

✅ تذكّر الدورين بجملة واحدة:

  • service worker = الدماغ: مركز أحداث الإضافة، يبدأ عند الحاجة ويتوقف عند الخمول، ولا يستطيع لمس DOM
  • content script = الأطراف: يعيش داخل الصفحة، يستطيع قراءة الصفحة وتعديلها، ويحميه العالم المعزول
  • العالم المعزول: متغيرات JS لا يرى أحدها الآخر، وDOM مشترك بين الطرفين
  • موقع السجلات: content script → Console الصفحة المضيفة؛ service worker → Inspect views في صفحة الإضافة

مراجعة حقول الإعدادات الرئيسية

الحقلالقيمة الموصى بهاالشرح
background.service_worker"service-worker.js"الإعلان عن MV3 سكربت الخلفية (background script في MV2 هو بالضبط)
content_scripts[].matchesنمط المطابقة (match pattern) للمواقع المستهدفةإلزامي، ويحدد الصفحات التي سيتم الحقن فيها
content_scripts[].js["content-script.js"]قائمة ملفات JS التي سيتم حقنها

استعراض الدرس التالي ​

سجلات الدورين أحدهما مخفي داخل صفحة الويب والآخر داخل صفحة الإضافة — الدرس التالي 《الإضافة لا تظهر: أين تجد السجلات وكيف تقرأ الأخطاء》 يشرح هذه المواضع كلها دفعة واحدة. ستتعلم:

  • أين تظهر الأخطاء عند كتابة manifest بشكل خاطئ أو كتابة صلاحية غير صحيحة
  • أين تُعرض سجلات popup وcontent script وservice worker على التوالي
  • كيفية استخدام زر Errors في صفحة الإضافة لتحديد المشكلة بسرعة
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.