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

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

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

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

  • هل تستخدم السمة browser_actions أم chrome.browserActions API؟

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

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

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

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

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

  • هل تستخدم السمة page_actions أم chrome.pageActions API؟

  • استبدِل 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 خارجي.

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

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

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

  • حدِّد السمة web_accessible_resources واعرض الموارد (وبشكل اختياري سياسة أمان محتوى منفصلة لتلك الموارد).

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

  • حدِّد خاصية وضع الحماية.

  • هل تستخدم رمزك أو مكتبتك؟ 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 لسياسة أمان المحتوى. CANNOT TRANSLATE قراءة المزيد عن هذه السياسة لفهم تبعاتها.

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

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

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

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

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

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

لن تعمل هذه الميزات في الإضافات المستنِدة إلى إصدار Manifest v2. أزِل معالِجات الأحداث المضمّنة، ثم ضَعها في ملف 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 Analytics. وهناك طريقتان لذلك:

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

  2. يمكنك الاسترخاء بشكل محدود من خلال إضافة مصادر HTTPS إلى القائمة المسموح بها في &quot;content_security_policy&quot; في البيان. لتضمين مكتبة مثل "إحصاءات Google" هذا هو النهج الذي يجب اتباعه:

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

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

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

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

  1. أنشِئ إدخالاً في وضع الحماية في ملف البيان.
  2. في إدخال وضع الحماية، أدرج الصفحات التي تريد عرضها في وضع الحماية.
  3. استخدام تمرير الرسالة عبر postMessage() للاتصال بالصفحة في وضع الحماية.

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

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

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