مرجع واجهة برمجة تطبيقات Closure Compiler Service

نظرة عامة

لطلب رمز مجمّع أو معلومات أخرى من خدمة Closure Compiler، عليك إرسال طلب HTTP POST إلى عنوان URL https://closure-compiler.appspot.com/compile. ويجب أن يحتوي نص الطلب على المعلّمات المدرَجة في معلَمات الطلب المطلوبة، ويمكن أن يحتوي أيضًا على أيٍّ من المعلَمات الاختيارية المدرَجة في معلَمات الطلب الاختيارية.

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

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

معامِلات الطلب

معامِلات الطلب المطلوبة

js_code أو code_url

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

يجب أن تكون المعلمة js_code سلسلة تحتوي على جافا سكريبت، مثل alert('hello').

يجب أن تتضمن المعلمة code_url عنوان URL لملف JavaScript. يمكنك تضمين معلمات code_url متعددة لتحديد ملفات إدخال متعددة.

compilation_level

يمكنك الاطّلاع على مستندات compilation_level في العلامات والخيارات.

output_format

تنسيق مخرجات خدمة Closure Compiler. هناك ثلاثة تنسيقات محتملة للإخراج:

xml

يعمل تنسيق الناتج xml على التفاف المعلومات المطلوبة بتنسيق XML صالح.

يظهر مخرجات XML على النحو التالي:

        <compilationResult>
          <compiledCode>var a="hello";alert(a);</compiledCode>
          <statistics>
            <originalSize>98</originalSize>
            <compressedSize>35</compressedSize>
            <compileTime>0</compileTime>
          </statistics>
        </compilationResult>
      

يحتوي القسم compiledCode على ملف JavaScript المضغوط الذي تم إنشاؤه بواسطة خدمة Closure Compiler. ولا يظهر هذا القسم إلا في حال تضمين معلَمة output_info مع قيمة compiled_code في الطلب. وبالمثل، لا يظهر القسم statistics إلا في حال تضمين معلَمة output_info بقيمة statistics.

إذا ضمّنت معلَمة output_info مع القيمة warnings ونتج عن برنامج التجميع تحذير، ستتضمن النتيجة علامة warnings:

        <compilationResult>
         ...
         <warnings>
           <warning type="JSC_NO_SIDE_EFFECT" file="default.js" lineno="12" charno="3"  line="delete 1;">warning 1</warning>
           <warning type="JSC_UNUSED_VAR" file="default.js" lineno="13" charno="13" line="delete 1;">warning 2 </warning>
         </warnings>
          ...
        </compilationResult>
      

في حال تضمين output_info بقيمة errors، ستتضمن خدمة Closure Compiler علامة errors إذا كان رمزك يحتوي على خطأ في البنية أو مشكلة أخرى تمنع التجميع. تظهر العلامة errors على النحو التالي:

        <compilationResult>
          ...
          <errors>
            <error type="JSC_NO_SIDE_EFFECT" file="default.js" lineno="12" charno="3"  line="var x=-'hello';">error 1 </error>
            <error type="JSC_UNUSED_VAR" file="default.js" lineno="13" charno="13" line="var x=-'hello'">error 2 </error>
          </errors>
          ...
        </compilationResult>
      

تشير السمات file وline وcol للعلامات error وwarning إلى المكان الذي واجهت فيه خدمة Closure Compiler الخطأ.

إذا واجهت خدمة Closure Compiler خطأ يمنع معالجة الإدخال، سيظهر الناتج على النحو التالي:

        <compilationResult>
          <serverErrors>
            <error code="1">Over quota</error>
          </serverErrors>
        </compilationResult>
      

json

يعمل تنسيق الناتج json على التفاف المعلومات المطلوبة في سلسلة JavaScript Object Notation (JSON). يؤدي تقييم هذه السلسلة إلى عرض JavaScript إلى "كائن JavaScript".

يبدو الناتج JSON على النحو التالي:

{
"compiledCode":/* raw code here */,
{"errors": [
  {"charno":4321,
   "error":"ERROR: You failed.",
   "lineno":1234,
   "file":"default.js",
   "type":"ERROR_TYPE",
   "line":"var x=-'hello';"}],
"warnings": [
  {"charno":4321,
   "lineno":1234,
   "file":"default.js",
   "type":"ERROR_TYPE",
   "warning":"Warning: You did something wrong!",
   "line":"delete 1;"}]
"serverErrors":[
  {"code":123,"error":"Over quota"}
  ],
"statistics":{
  "originalSize":10,
  "compressedSize":3000
  "compileTime":10
  }
}
      

يكون تنسيق JSON مماثلاً لتنسيق XML، حيث تتوافق كل علامة في نتائج XML مع خاصية تحمل الاسم نفسه في كائن JSON.

text

يعرض تنسيق الإخراج text نصًا أوليًا بدون علامات أو أقواس JSON. إذا تضمّنت السمة output_info compiled_code، سيحتوي النص على JavaScript. إذا تضمّنت السمة output_info warnings، سيحتوي النص على رسائل تحذير. إذا تضمّنت السمة output_info statistics، سيحتوي النص على الإحصاءات.

الإعداد التلقائي للمعلمة output_format هو القيمة text.

output_info

تشير إلى نوع الإخراج الذي تريده من المحول البرمجي. هناك أربعة أنواع محتملة من المخرجات:

compiled_code

نسخة مضغوطة ومحسّنة من JavaScript الذي تم إدخاله.

warnings

الرسائل التي تشير إلى أخطاء محتملة في JavaScript.

errors

الرسائل التي تشير إلى أخطاء في البنية أو أخطاء أخرى في JavaScript

statistics

تمثّل هذه الخاصية معلومات عن درجة الضغط التي يحققها مجمِّع الموسيقى. بالنسبة إلى مخرجات xml، تعرض خدمة Closure Compiler إحصاءات بالتنسيق التالي:

        <compilationResult>
          ...
          <statistics>
            <firstStatisticName>24</firstStatisticName>
            <secondStatisticName>15</secondStatisticName>
          </statistics>
        </compilationResult>
      

معامِلات الطلب الاختيارية

js_externs

يجب أن تكون قيمة هذه المعلمة عبارة عن رمز JavaScript يعلن عن أسماء الدوال أو الرموز الأخرى. استخدِم js_externs للاحتفاظ برموز محدّدة خارج الرمز الذي تنشئه. ولا يكون للمعلَمة js_externs أي تأثير إلا إذا كنت تستخدم compilation_level من ADVANCED_OPTIMIZATIONS. راجع التجميع المتقدم لمزيد من المعلومات.

externs_url

يجب أن تكون قيمة هذه المعلّمة هي عنوان URL لملف يحتوي على JavaScript يعلن عن أسماء الدوال أو الرموز الأخرى. يتم الاحتفاظ بالرموز الموضّحة في هذا الملف بالطريقة نفسها المتّبعة مع الرموز المدرَجة مباشرةً في المعلَمة js_externs. لا يكون للمعلَمة externs_url أي تأثير إلا إذا كنت تستخدم compilation_level من ADVANCED_OPTIMIZATIONS. راجع التجميع المتقدم لمزيد من المعلومات.

يمكنك تحديد هذه المعلمة عدة مرات إذا كانت لديك عدة ملفات خارجية.

exclude_default_externs

وبشكل تلقائي، تستخدم خدمة Closure Compiler ملفًا خارجيًا قياسيًا يعلن عن الرموز الشائعة التي يتم تعريفها خارجيًا مثل document وجميع طرقها. إذا كنت لا تريد استخدام عناصر خارجية مشتركة، فأدرج في طلبك معلَمة exclude_default_externs بقيمة true.

اطّلِع على القسم التجميع المتقدّم وعمليات الإدخال الخارجي للحصول على مزيد من المعلومات حول العناصر الخارجية.

output_file_name

وفي حال توفّر هذه الخدمة، تخزّن خدمة Closure Compiler رمزًا مجمّعًا لمدة ساعة واحدة وتجعله متاحًا من خلال عنوان URL خاص. وخلال هذه الساعة، يمكنك اختبار الرمز المجمّع من خلال توجيه المتصفّح إلى عنوان URL هذا. ويكون عنوان URL على النحو التالي:

https://closure-compiler.appspot.com/code/bf067f356d510e1c7b81347eb84f65d2/[value of output_file_name]

formatting

يمكنك الاطّلاع على مستندات formatting في العلامات والخيارات. ويمكنك توفير معلمات formatting متعدّدة في الطلب نفسه.

use_closure_library

إذا منحت المعلَمة use_closure_library قيمة true، سيبحث المجمِّع عن عبارات goog.require() في رمز المصدر ويزوّد رمز "مكتبة الإغلاق" الذي تطلبه هذه العبارات. كما يتم إجراء تحسينات مصممة خصيصًا لرمز مكتبة الإغلاق. للحصول على مزيد من المعلومات حول مكتبة الإغلاق، يُرجى مراجعة مستندات مكتبة الإغلاق. يُرجى الاطّلاع على مقالة العثور على طريقك في مكتبة الإغلاق للحصول على مزيد من المعلومات حول الدالة goog.require().

القيمة التلقائية للمعلمة use_closure_library هي false.

warning_level

يمكنك الاطّلاع على مستندات warning_level في العلامات والخيارات.

language

يمكنك الاطّلاع على مستندات الخيار language_in المكافئ في العلامات والخيارات.

language_out

يمكنك الاطّلاع على مستندات language_out في العلامات والخيارات.

rewrite_polyfills

يمكنك الاطّلاع على مستندات rewrite_polyfills في العلامات والخيارات.

use_types_for_optimization

يمكنك الاطّلاع على مستندات use_types_for_optimization في العلامات والخيارات.

رسائل الخطأ

إذا أخفق الخادم في معالجة طلبك، فستتلقى إحدى رسائل خطأ الخادم المدرجة في الجدول أدناه. لاحظ أن رسائل خطأ الخادم هذه تختلف عن أخطاء برامج التجميع والتحذيرات. تشير أخطاء وتحذيرات العارضين إلى أن Closure Compiler وجد مشكلة في شفرة جافا سكريبت. تشير رسائل خطأ الخادم إلى أن المحول البرمجي لا يمكنه معالجة الشفرة على الإطلاق بسبب خطأ في طلبك.

رمز الخطأ	رسالة الخطأ	المعنى
2	وضع الإخراج غير معروف.	قيمة المعلَمة output_format مختلفة عن قيمة xml أو json أو text.
4	مستوى الضغط غير معروف.	قيمة المعلَمة compilation_level مختلفة عن قيمة WHITESPACE_ONLY أو SIMPLE_OPTIMIZATIONS أو ADVANCED_OPTIMIZATIONS.
8	بيانات POST كبيرة جدًا.	يتجاوز حجم البيانات التي أرسلتها إلى خدمة Closure Compiler 200000 بايت. تستخدم كل من واجهة مستخدم خدمة "مقدّم الخدمة" وواجهة برمجة التطبيقات طلب HTTP POST للتواصل مع الخدمة، ولا يمكن أن يتجاوز إجمالي حجم البيانات المرسَلة في هذا الطلب 200,000 بايت. بالنسبة إلى طلبات البيانات من واجهة برمجة التطبيقات، ينطبق هذا الحد على إجمالي النص في جميع معلَمات الطلب. بالنسبة إلى واجهة مستخدم Closure Compiler، ينطبق هذا الحد على إجمالي حجم النص في كل من رمز المصدر وخيارات برنامج التجميع مثل @code_url. إذا كان طلبك كبيرًا جدًا، عليك إما نقل رمز المصدر إلى ملفات منفصلة والإشارة إليه باستخدام @code_url أو استخدام تطبيق Closure Compiler على جهازك المحلي.
9	الملف كبير جدًا.	إجمالي حجم الرمز من جميع ملفات code_url، وكل ملفات externs_url، وكل رموز js_code وكل رموز js_externs يتجاوز 1024000 بايت.
10	لا يمكن استرداد المحتوى من عنوان URL.	حدث خطأ عند محاولة خدمة Closure Compiler استرداد إما ملف JavaScript مُشار إليه في المعلَمة code_url أو ملف خارجي تمت الإشارة إليه في المعلَمة externs_url. تحقق من أن عنوان URL صحيح وأن أذونات الملف تسمح بعرضه.
12	عنوان URL غير مكتوب بشكل صحيح.	قيمة المَعلمة code_url أو المَعلمة externs_url ليست عنوان URL بتنسيق صحيح.
13	ليست هناك معلومات مخرجات لإنتاجها، ومع ذلك تم طلب التجميع.	لم يتم تحديد معلمة output_info.
14	قيمة معلومات_إخراج غير معروفة	قيمة المعلَمة output_info مختلفة عن قيمة compiled_code أو warnings أو statistics.
16	مستوى تحذير غير معروف	قيمة المعلَمة warning_level مختلفة عن قيمة QUIET أو DEFAULT أو VERBOSE.
17	خيار تنسيق غير معروف.	قيمة المعلَمة formatting مختلفة عن قيمة pretty_print.
18	معلمة غير معروفة في طلب HTTP	يحتوي طلب HTTP على معلمة بخلاف واحدة من المعلمات المدرجة في هذا المستند.
19	قيمة غير مسموح بها للملف الناتج_file_name	يحتوي اسم ملف الناتج على حرف أو حرف أو نقطة أو شرطة سفلية أو شرطة أو يحتوي على نقطتين متتاليتين (..)
22	تم إجراء الكثير من التجميعات مؤخرًا. حاول مرة أخرى في وقت لاحق.	لقد أرسلت عمليات تجميع كثيرة جدًا من جهازك. وبعد ساعة، من المفترض أن تتمكن من إجراء عمليات التجميع مرة أخرى.
23	استثناء برامج التجميع (مع تتبُّع عمليات الرجوع)	تعطّل المحول البرمجي. سيتضمن نص الخطأ معلومات لمساعدة Google في تصحيح المشكلة.
24	نوع مورد الإدخال غير متوافق	نوع المورد ليس http:، ولذلك لن يتم استرداد ملف الإدخال.