البرنامج التعليمي: الانتقال إلى إصدار Manifest V2

تم إيقاف الإصدار 1 من ملف البيان في الإصدار 18 من Chrome، وسيتم إيقاف التوافق وفقًا للجدول الزمني للدعم الخاص بالإصدار 1 من البيان. تندرج التغييرات من الإصدار 1 إلى الإصدار 2 ضمن فئتين عموميتين: تغييرات واجهة برمجة التطبيقات وتغييرات الأمان.

يقدِّم هذا المستند قوائم تحقُّق لنقل بيانات إضافات Chrome من إصدار البيان 1 إلى الإصدار 2، تليها ملخّصات أكثر تفصيلاً لما تعنيه هذه التغييرات وسبب إنشائها.

قائمة التحقّق من تغييرات واجهة برمجة التطبيقات

  • هل تستخدم السمة browser_actions أو واجهة برمجة التطبيقات chrome.browserActions؟

  • استبدِل browser_actions بالسمة المفردة browser_action.

  • استبدِل chrome.browserActions بـ chrome.browserAction.

  • استبدِل السمة icons بسمة default_icon.

  • استبدِل السمة name بسمة default_title.

  • استبدِل السمة popup بسمة default_popup (ويجب أن تكون الآن سلسلة).

  • هل تستخدم السمة page_actions أو واجهة برمجة التطبيقات chrome.pageActions؟

  • استبدِل page_actions بـ page_action.

  • استبدِل chrome.pageActions بـ chrome.pageAction.

  • استبدِل السمة icons بسمة default_icon.

  • استبدِل السمة name بسمة default_title.

  • استبدِل السمة popup بسمة default_popup (ويجب أن تكون الآن سلسلة).

  • هل تستخدم السمة chrome.self؟

  • يجب استبداله بـ "chrome.extension".

  • هل تستخدم السمة Port.tab؟

  • يجب استبداله بـ "Port.sender".

  • هل تستخدم واجهات برمجة التطبيقات chrome.extension.getTabContentses() أم chrome.extension.getExtensionTabs()؟

  • يجب استبداله بـ "chrome.extension.getViews( { "type" : "tab" } )".

  • هل تستخدم إضافتك صفحة خلفية؟

  • استبدِل السمة background_page بالسمة background.

  • أضِف السمة scripts أو page التي تحتوي على رمز الصفحة.

  • أضِف سمة persistent واضبطها على false لتحويل صفحة الخلفية إلى صفحة حدث.

قائمة التحقُّق من تغييرات الأمان

  • هل يتم استخدام كتل النصوص البرمجية المضمّنة في صفحات HTML؟

  • يجب إزالة رمز JavaScript المضمَّن في علامات <script> ووضعه داخل ملف JS خارجي.

  • هل تستخدم معالِجات أحداث مضمّنة (مثل النقرات وما إلى ذلك)؟

  • أزِلها من رمز HTML وانقلها إلى ملف JS خارجي واستخدِم addEventListener() بدلاً منها.

  • هل تُدخل الإضافة نصوصًا برمجية للمحتوى في صفحات الويب التي تحتاج إلى الوصول إلى الموارد (مثل الصور والنصوص البرمجية) المتضمّنة في حزمة الإضافة؟

  • حدِّد السمة web_accessible_resources وأدرِج الموارد (واختياريًا، سياسة أمان محتوى منفصلة لهذه الموارد)

  • هل تتضمن إضافتك صفحات ويب خارجية؟

  • حدِّد سمة sandbox.

  • هل رمزك أو مكتبتك يستخدم eval() أو Function() جديد أو innerHTML أو setTimeout() أو سلاسل من رمز JavaScript يتم تقييمها ديناميكيًا؟

  • استخدِم JSON.parse() إذا كنت تريد تحليل رمز JSON في كائن.

  • استخدِم مكتبة متوافقة مع سياسة أمان المحتوى (CSP)، على سبيل المثال، AngularJS.

  • أنشئ إدخال وضع حماية في البيان وشغِّل الرمز المتأثر في وضع الحماية باستخدام postMessage() للاتصال بالصفحة ذات وضع الحماية.

  • هل أنت بصدد تحميل رمز خارجي، مثل jQuery أو "إحصاءات Google"؟

  • ننصحك بتنزيل المكتبة ووضعها في حزمة في الإضافة، ثم تحميلها من الحزمة المحلية.

  • أضِف نطاق HTTPS الذي يعرض المورد في جزء "content_security_policy" من بيانك إلى القائمة المسموح بها.

ملخّص التغييرات في واجهة برمجة التطبيقات

يقدّم الإصدار 2 من ملف البيان بعض التغييرات على واجهات برمجة التطبيقات الخاصة بإجراءات المتصفّح وإجراءات على الصفحة، ويستبدل بعض واجهات برمجة التطبيقات القديمة بواجهات برمجة أحدث.

تغييرات إجراءات المتصفّح

تقدّم واجهة برمجة تطبيقات إجراءات المتصفّح بعض تغييرات التسمية:

  • تم استبدال السمتَين browser_actions وchrome.browserActions بنظيرتهما المفردتَين browser_action وchrome.browserAction.

  • ضمن الموقع الإلكتروني القديم على browser_actions، كانت هناك مواقع icons وname وpopup. تم استبدال الكلمات الرئيسية بما يلي:

  • default_icon لرمز شارة إجراء المتصفّح

  • default_name للنص الذي يظهر في التلميح عند تمرير مؤشر الماوس فوق الشارة

  • default_popup لصفحة HTML التي تمثل واجهة المستخدم لإجراء المتصفح (ويجب أن تكون هذه الآن سلسلة، ولا يمكن أن تكون كائنًا)

تغييرات إجراءات الصفحة

مثل التغييرات التي طرأت على إجراءات المتصفح، تمّ أيضًا تغيير واجهة برمجة التطبيقات لإجراءات الصفحة:

  • تم استبدال الخاصيتين page_actions وchrome.pageActions بنظيرتهما المفردة page_action وchrome.pageAction.

  • ضمن الموقع الإلكتروني القديم على page_actions، كانت هناك مواقع icons وname وpopup. وقد تم استبدال هذه العناصر بما يلي:

  • default_icon لرمز شارة إجراء الصفحة

  • default_name للنص الذي يظهر في التلميح عند تمرير مؤشر الماوس فوق الشارة

  • default_popup لصفحة HTML التي تمثل واجهة المستخدم لإجراء الصفحة (ويجب أن تكون هذه الآن سلسلة، ولا يمكن أن تكون كائنًا)

واجهات برمجة التطبيقات التي تمت إزالتها وتغييرها

تمت إزالة بعض واجهات برمجة التطبيقات للإضافات واستبدالها بواجهات برمجة تطبيقات جديدة:

  • تم استبدال السمة background_page بخلفية.
  • تمت إزالة السمة chrome.self. استخدِم chrome.extension.
  • تم استبدال السمة Port.tab بالسمة Port.sender.
  • تم استبدال واجهات برمجة التطبيقات chrome.extension.getTabContentses() وchrome.extension.getExtensionTabs() بـ chrome.extension.getViews( { "type" : "tab" } ).

ملخّص التغييرات في إعدادات الأمان

هناك عدد من التغييرات المتعلقة بالأمان التي يصاحب الانتقال من إصدار البيان 1 إلى الإصدار 2. ينشأ العديد من هذه التغييرات من اعتماد Chrome لسياسة أمان المحتوى، لذا ننصحك بقراءة المزيد حول هذه السياسة لفهم الآثار المترتبة عليها.

لا يُسمح بالنصوص البرمجية المضمّنة ومعالجات الأحداث.

بسبب استخدام سياسة أمان المحتوى، لم يعُد بإمكانك استخدام علامات <script> المضمَّنة مع محتوى HTML. ويجب نقل هذه الملفات إلى ملفات JS خارجية. بالإضافة إلى ذلك، لا يُسمح أيضًا بمعالجات الأحداث المضمّنة. على سبيل المثال، لنفترض أن لديك الرمز التالي في إضافتك:

<html>
<head>
  <script>
    function myFunc() { ... }
  </script>
</head>
</html>

من المفترض أن يؤدي هذا الرمز إلى حدوث خطأ في وقت التشغيل. لحلّ هذه المشكلة، انقل محتوى علامة <script> إلى ملفات خارجية وأشِر إليها باستخدام سمة src='path_to_file.js'.

وبالمثل، لن يتم تنفيذ معالِجات الأحداث المضمّنة، وهي ميزة شائعة الحدوث والملاءمة يستخدمها العديد من مطوّري البرامج على الويب. على سبيل المثال، ضع في اعتبارك الحالات الشائعة، مثل:

<body onload="initialize()">
<button onclick="handleClick()" id="button1">

لن تعمل هذه الميزات في الإصدار 2 من بيان الإضافات. عليك إزالة معالِجات الأحداث المضمّنة، ووضعها في ملف JavaScript الخارجي واستخدام addEventListener() لتسجيل معالِجات الأحداث لها بدلاً من ذلك. على سبيل المثال، في رمز JavaScript، استخدِم:

window.addEventListener("load", initialize);
...
document.getElementById("button1").addEventListener("click",handleClick);

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

تضمين المحتوى

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

محتوى الإضافة في صفحات الويب: إذا كانت الإضافة تتضمّن موارد (مثل الصور والنصوص البرمجية وأنماط CSS وغيرها) المستخدَمة في النصوص البرمجية للمحتوى التي تم إدخالها في صفحات الويب، عليك استخدام السمة web_accessible_resources لإضافة هذه الموارد إلى القائمة المسموح بها حتى تتمكّن صفحات الويب الخارجية من استخدامها:

{
...
  "web_accessible_resources": [
    "images/image1.png",
    "script/myscript.js"
  ],
...
}

تضمين المحتوى الخارجي: تسمح "سياسة أمان المحتوى" بتحميل النصوص البرمجية والكائنات المحلية من الحزمة فقط، ما يمنع المهاجمين الخارجيين من تقديم رمز غير معروف إلى الإضافة. ومع ذلك، هناك أوقات تريد فيها تحميل الموارد المعروضة خارجيًا، مثل رمز jQuery أو رمز "إحصاءات Google". ثمة طريقتان لتنفيذ هذا الإجراء:

  1. يمكنك تنزيل المكتبة ذات الصلة محليًا (مثل jQuery) ووضعها في حزمة باستخدام الإضافة.

  2. يمكنك تخفيف سياسة CSP بشكل محدود من خلال إدراج مصادر HTTPS في القائمة المسموح بها في قسم "content_security_policy" في البيان. لتضمين مكتبة مثل Google Analytics، هذا هو الأسلوب الذي يجب اتباعه:

    {
  ...,
  "content_security_policy": "script-src 'self'
  https://ssl.google-analytics.com; object-src 'self'",
  ...
}

استخدام تقييم النص البرمجي الديناميكي

ربما يكون أحد أكبر التغييرات في مخطط الإصدار 2 من البيان الجديد هو أنّه لم يعُد بإمكان الإضافات استخدام أساليب تقييم النص البرمجي الديناميكي، مثل eval() أو Function() الجديد، أو تمرير سلاسل من رمز JavaScript إلى دوال تؤدي إلى استخدام eval()، مثل setTimeout(). بالإضافة إلى ذلك، تُعرف بعض مكتبات JavaScript شائعة الاستخدام مثل خرائط Google وبعض مكتبات النماذج باستخدام بعض هذه التقنيات.

يوفّر Chrome وضع حماية للصفحات ليتم تشغيلها في المصدر الخاص بها، والتي يتم رفض الوصول إليها على Chrome.* واجهات برمجة التطبيقات. لاستخدام eval() وما شابه ذلك بموجب سياسة أمان المحتوى الجديدة:

  1. إنشاء إدخال وضع حماية في ملف البيان
  2. في إدخال وضع الحماية، اذكر الصفحات التي تريد تشغيلها في وضع الحماية.
  3. يمكنك استخدام الرسائل التي تم تمريرها عبر postMessage() للتواصل مع الصفحة المحمية في وضع الحماية.

لمزيد من التفاصيل عن كيفية إجراء ذلك، راجع مستندات تقييم وضع الحماية.

محتوى إضافي للقراءة

صُممت التغييرات في الإصدار 2 من ملف البيان لتوجيه المطوّرين نحو إنشاء إضافات وتطبيقات أكثر أمانًا وقوةً. للاطّلاع على قائمة كاملة بالتغييرات من إصدار البيان 1 إلى الإصدار 2، يمكنك الاطّلاع على وثائق ملف البيان. لمزيد من المعلومات حول استخدام وضع الحماية لعزل الرموز غير الآمنة، اقرأ مقالة تقييم وضع الحماية. يمكنك معرفة المزيد عن "سياسة أمان المحتوى" من خلال الانتقال إلى البرنامج التعليمي المتعلق بالإضافات ومقدمة جيدة عن HTML5Rocks.