تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

إضافة خيارات عامة

توفّر R8 خيارات عامة تعدّل تحسينات R8 في جميع أنحاء التطبيق أو تؤثّر في كل قاعدة keep. يتم الاحتفاظ بهذه الخيارات في ملف proguard-rules.pro، بالإضافة إلى قواعد الاحتفاظ بالبيانات. تتيح بعض هذه الخيارات العامة ضبط إعدادات تحسين إضافية، بينما توقف خيارات أخرى جوانب معيّنة من التحسين.

خيارات عامة للتحسين الإضافي

تتيح الخيارات العامة التالية إجراء تحسينات إضافية:

-repackageclasses [<optional-package-name>]: إعادة تجميع الفئات في حزمة واحدة لتقليل حجم التطبيق في حال عدم توفير اسم الحزمة الاختياري، يتم نقل الفئات إلى الحزمة التلقائية التي ليس لها اسم. هذا هو الإعداد المقترَح للتطبيقات لأنّه يؤدي إلى إنشاء ملفات DEX أصغر حجمًا من خلال حذف بادئة الحزمة من أسماء الفئات.
‫-allowaccessmodification: يتيح هذا الخيار لبرنامج R8 تغيير (توسيع عادةً) مستوى ظهور الفئات والحقول والطرق من أجل إجراء تحسينات أكثر شمولاً. يتم تفعيلها عند استخدام proguard-android-optimize.txt. منذ الإصدار 8.2 من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP)، أصبح هذا الإعداد هو الإعداد التلقائي إذا كنت تستخدم R8 في الوضع الكامل.

في ما يلي مثال على إعدادات تم تفعيل ميزة التحسين الإضافي فيها:

-repackageclasses
-allowaccessmodification

الخيارات العامة للحدّ من التحسين

تتيح لك الخيارات العامة التالية إيقاف جوانب معيّنة من تحسين التطبيق، وهي مفيدة عند تحسين قواعد الاحتفاظ أو تفعيل R8 لأول مرة.

‫-dontoptimize: يمنع تحسين الرمز، مثل تضمين الدوال البرمجية. يمكن استخدام هذا الخيار أثناء التطوير، ولكن يجب عدم استخدامه في الإصدارات المخصّصة للإنتاج.
‫-dontshrink: يمنع إزالة الرمز غير المرجعي وتحسين الرمز. يمكن استخدام هذا الخيار أثناء التطوير، ولكن يجب عدم استخدامه في إصدارات الإنتاج.
-dontobfuscate: يمنع تقصير أسماء الفئات والطرق. ويمكن أن يكون إيقاف التشويش مفيدًا بشكل خاص أثناء تصحيح الأخطاء لتسهيل قراءة عمليات تتبُّع تسلسل استدعاء الدوال البرمجية. يمكن استخدام هذا الخيار أثناء التطوير، ولكن يجب عدم استخدامه في إصدارات الإنتاج.
‫-keepattributes <attributes>: تقبل قائمة مفصولة بفواصل تتضمّن السمات التي يجب الحفاظ عليها. إذا لم تكن تستخدم proguard-android-optimize.txt التلقائي، ستزيل أداة R8 جميع السمات، بما في ذلك RuntimeVisibleAnnotations وSignature، ولكن قد يكون من المفيد الاحتفاظ بهذه السمات إذا كانت مطلوبة في حالات مثل الانعكاس. للحصول على قائمة بالسمات التي يمكنك تحديدها، اطّلِع على السمات التي يجب الاحتفاظ بها.

إبقاء السمات

السمات هي أجزاء إضافية من المعلومات مرتبطة بأجزاء مختلفة من الرمز. تخزّن السمات معلومات مثل التعليقات التوضيحية والتوقيعات العامة من الرمز البرمجي.

تتطلّب بعض العمليات الانعكاسية الاحتفاظ بسمات معيّنة لتنفيذها بنجاح. مثلاً:

عند الوصول إلى بنية الفئة الداخلية أو الخارجية باستخدام getEnclosingMethod() أو getDeclaredClasses()، يجب استخدام السمتَين EnclosingMethod وInnerClasses.
عند الوصول إلى التواقيع العامة باستخدام getTypeParameters()، يجب توفير السمة Signature.
عند الوصول إلى التعليقات التوضيحية باستخدام getAnnotation()، يجب توفُّر السمة RuntimeVisibleAnnotations.

ملاحظة: عند العمل على قاعدة إبقاء لتعليق توضيحي، احرص على إبقاء التعليق التوضيحي والفئات التي يتم تطبيق التعليق التوضيحي عليها.

السمات المطلوبة بشكل شائع

عند استخدام ملف Proguard التلقائي (proguard-android-optimize.txt أو proguard-android.txt)، يحتفظ المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP) بالسمات التالية. يُرجى العِلم أنّ بعض هذه السمات تتطلّب إصدارات أحدث من "مكوّن Android الإضافي في Gradle":

السمة	الوصف
`AnnotationDefault`	تتوفّر هذه السمة في أنواع التعليقات التوضيحية نفسها وتخزِّن القيمة التلقائية لعنصر التعليق التوضيحي. ملاحظة: يتم الاحتفاظ بهذه السمة تلقائيًا منذ الإصدار 7.1 من "مكوّن Android الإضافي في Gradle"، ولا يلزم الاحتفاظ بها بشكل صريح إلا في التطبيقات التي تستخدم إصدارات أقدم من "مكوّن Android الإضافي في Gradle".
`EnclosingMethod`	تتوفّر هذه السمة في الفئات الداخلية التي ليست فئات محلية أو مجهولة. تحدّد هذه السمة الطريقة أو أداة التهيئة التي تحتوي على الفئة مباشرةً.
`InnerClasses`	تسجّل هذه السمة معلومات عن الفئات المتداخلة (الفئات الداخلية والفئات الثابتة المتداخلة والفئات المحلية والفئات المجهولة) المحدّدة ضمن فئة أخرى.
`LineNumberTable`	تربط هذه السمة تعليمات الرمز الثانوي بأرقام الأسطر المقابلة لها في ملف المصدر الأصلي. ملاحظة: يتم الاحتفاظ بهذه السمة تلقائيًا منذ الإصدار 8.6 من المكوّن الإضافي لنظام Gradle المتوافق مع Android (AGP)، ويجب الاحتفاظ بها بشكل صريح فقط في التطبيقات التي تستخدم إصدارات أقدم من المكوّن الإضافي لنظام Gradle المتوافق مع Android.
`RuntimeVisibleAnnotations`	تخزّن هذه السمة التعليقات التوضيحية التي يمكن عرضها في وقت التشغيل باستخدام الانعكاس. في العادة، إذا تم استخدام التعليقات التوضيحية في وقت التشغيل، يكون هذا هو التعليق التوضيحي الوحيد من سمات `*Annotation` الذي تحتاجه التطبيقات وفي قواعد المستهلكين في المكتبة.
`RuntimeVisibleParameterAnnotations`	تخزِّن هذه السمة التعليقات التوضيحية التي تكون مرئية في وقت التشغيل من خلال الانعكاس على مَعلمات إحدى الطرق.
`RuntimeVisibleTypeAnnotations`	تخزّن هذه السمة التعليقات التوضيحية التي تنطبق على استخدامات الأنواع بدلاً من التصريحات فقط. تظهر هذه السمة في وقت التشغيل.
`Signature`	تخزِّن هذه السمة توقيع نوع أكثر عمومية للفئات والطُرق والحقول، خاصةً عندما تستخدم الأنواع العامة (مثل `List<String>`).
`SourceFile`	يخزِّن هذا التصنيف اسم ملف المصدر (ملف `.kt` أو `.java`) الذي تم تجميع صف منه. يستخدمه مصحّحو الأخطاء بشكل أساسي لعرض أسطر رمز المصدر الأصلي عند تتبُّع رمز Java مجمَّع. ويساعد المطوّرين في تتبُّع التنفيذ وصولاً إلى الرمز البرمجي المكتوب. ملاحظة: يتم الاحتفاظ بهذه السمة تلقائيًا منذ الإصدار 8.2 من "مكوّن Android الإضافي لبرنامج Gradle"، ولا يلزم الاحتفاظ بها بشكلٍ صريح إلا في التطبيقات التي تستخدم إصدارات أقدم من "مكوّن Android الإضافي لبرنامج Gradle".

بالنسبة إلى التطبيقات التي تستخدم proguard-android-optimize.txt، تكون قواعد الاحتفاظ المحدّدة من خلال AGP كافية في معظم السيناريوهات. ومع ذلك، إذا كنت تكتب رمزًا برمجيًا لمكتبة، عليك تحديد جميع السمات التي تتطلبها مكتبتك في قواعد الاحتفاظ بالمستهلك، حتى إذا كانت هذه السمات محدّدة في هذه القائمة. يضمن ذلك أن تكون مكتبتك قوية في حال قرّر المطوّرون عدم تضمين proguard-android-optimize.txt.

سمات إضافية يجب الاحتفاظ بها

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

السمة	الوصف
`MethodParameters`	تقدّم هذه السمة معلومات عن مَعلمات إحدى الطرق، وتحديدًا أسماءها وعلامات الوصول إليها.
`Exceptions`	تسرد هذه السمة الاستثناءات التي تم التحقّق منها والتي تم الإعلان عن أنّ إحدى الطرق ستطرحها. لا تُستخدَم هذه السمة عادةً للتطبيقات. بالنسبة إلى مطوّري المكتبات، لا يتم استخدامها عادةً في قواعد الاحتفاظ بالمستهلكين، ولكن يتم استخدامها غالبًا عند إنشاء المكتبات. لمزيد من التفاصيل حول تحسين المكتبات، يُرجى الاطّلاع على تحسين المكتبات لمطوّريها.
`RuntimeInvisibleAnnotations`	تخزّن هذه السمة التعليقات التوضيحية التي لا تظهر مع الانعكاس في وقت التشغيل على فئة أو حقل أو طريقة. يجب ألا يحتفظ مطوّرو التطبيقات بهذه السمة. بالنسبة إلى مؤلفي المكتبات، لا تكون هذه السمة ذات صلة بقواعد الاحتفاظ بالمستهلكين، ولكن يتم استخدامها غالبًا عند إنشاء المكتبات. لمزيد من التفاصيل حول تحسين المكتبات، يُرجى الاطّلاع على تحسين المكتبات لمطوّريها.
`RuntimeInvisibleParameterAnnotations`	تخزِّن هذه السمة التعليقات التوضيحية التي لا تظهر مع الانعكاس في وقت التشغيل على مَعلمات إحدى الطرق. يجب ألا يحتفظ مطوّرو التطبيقات بهذه السمة. بالنسبة إلى مؤلفي المكتبات، لا تكون هذه السمة ذات صلة بقواعد الاحتفاظ بالمستهلكين، ولكن يتم استخدامها غالبًا عند إنشاء المكتبات. لمزيد من التفاصيل حول تحسين المكتبات، يُرجى الاطّلاع على تحسين المكتبات لمطوّريها.
`RuntimeInvisibleTypeAnnotations`	تخزّن هذه السمة التعليقات التوضيحية التي تنطبق على استخدامات الأنواع بدلاً من التصريحات فقط. لا تظهر هذه السمة في وقت التشغيل. يجب ألا يحتفظ مطوّرو التطبيقات بهذه السمة. بالنسبة إلى مؤلفي المكتبات، لا تكون هذه السمة ذات صلة بقواعد الاحتفاظ بالمستهلكين، ولكن يتم استخدامها غالبًا عند إنشاء المكتبات. لمزيد من التفاصيل حول تحسين المكتبات، يُرجى الاطّلاع على تحسين المكتبات لمطوّريها.