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

معيار AAPT2

‫AAPT2 (أداة تجميع الموارد في Android الإصدار 2) هي أداة إنشاء يستخدمها "استوديو Android" والمكوّن الإضافي لنظام Gradle المتوافق مع Android لتجميع الموارد الخاصة بتطبيقك. يحلّل AAPT2 الموارد ويفهرسها ويحوّلها إلى تنسيق ثنائي محسَّن لمنصة Android.

يتيح الإصدار 3.0.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android والإصدارات الأحدث أداة AAPT2 تلقائيًا. عادةً، لن تحتاج إلى استدعاء aapt2 بنفسك. ومع ذلك، إذا كنت تفضّل استخدام نافذة الأوامر ونظام الإصدار الخاص بك بدلاً من "استوديو Android"، يمكنك استخدام AAPT2 من سطر الأوامر. يمكنك أيضًا تصحيح أخطاء الإنشاء المرتبطة بأداة AAPT2 من سطر الأوامر. لإجراء ذلك، ابحث عن AAPT2 كأداة مستقلة في أدوات إنشاء حزمة تطوير البرامج (SDK) لنظام التشغيل Android الإصدار 26.0.2 والإصدارات الأحدث.

لتنزيل "أدوات إنشاء حزمة تطوير البرامج (SDK) لنظام التشغيل Android" من سطر الأوامر، استخدِم sdkmanager ونفِّذ الأمر التالي:

sdkmanager "build-tools;build-tools-version"

بعد تنزيل أدوات إنشاء حزمة تطوير البرامج (SDK)، ابحث عن AAPT2 في android_sdk/build-tools/version/.

بما أنّ مراجعات أدوات الإصدار في حزمة تطوير البرامج (SDK) لنظام التشغيل Android لا يتم إصدارها بشكل متكرّر، قد لا يكون إصدار أداة AAPT2 المضمّن في أدوات الإصدار في حزمة تطوير البرامج (SDK) هو الأحدث. للحصول على أحدث إصدار من AAPT2، نزِّل AAPT2 من Google Maven.

لاستخدام AAPT2 من سطر الأوامر على نظام التشغيل Linux أو Mac، شغِّل الأمر aapt2. على جهاز Windows، شغِّل الأمر aapt2.exe.

تتيح أداة AAPT2 تجميع الموارد بشكل أسرع من خلال تفعيل التجميع التزايدي. لإجراء تجميع تدريجي، يتم تقسيم معالجة الموارد إلى خطوتَين:

تجميع: لتجميع ملفات الموارد في تنسيقات ثنائية
Link: يدمج جميع الملفات التي تم تجميعها ويحزمها في حزمة واحدة.

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

تنزيل أداة AAPT2 من Google Maven

للحصول على أحدث إصدار من أداة AAPT2 غير المضمّن في أدوات الإصدار، نزِّل أداة AAPT2 من مستودع Maven من Google باتّباع الخطوات التالية:

في فهرس المستودع، انتقِل إلى com.android.tools.build > aapt2.
انسخ اسم أحدث إصدار من AAPT2.
أدرِج اسم الإصدار الذي نسخته في عنوان URL التالي وحدِّد نظام التشغيل المستهدف: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/ aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar

على سبيل المثال، لتنزيل الإصدار 3.2.0-alpha18-4804415 لنظام التشغيل Windows، استخدِم: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/ 3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar
انتقِل إلى عنوان URL في المتصفّح. سيبدأ تنزيل AAPT2 بعد قليل.
فك حزمة ملف JAR الذي نزّلته للتو.

يجب أن يحتوي ملف JAR على ملف تنفيذي aapt2 وبعض المكتبات التي يعتمد عليها الملف التنفيذي.

تجميع

يتيح AAPT2 تجميع جميع أنواع موارد Android، مثل الملفات القابلة للرسم وملفات XML. عند استدعاء AAPT2 للتجميع، مرِّر ملف موارد واحدًا كإدخال لكل استدعاء. بعد ذلك، يحلّل AAPT2 الملف وينشئ ملفًا ثنائيًا وسيطًا بامتداد .flat.

عند تمرير أدلة كاملة، تعيد أداة AAPT2 تجميع كل الملفات في الدليل حتى إذا تم تغيير مورد واحد فقط. على الرغم من أنّه يمكنك تمرير أدلة موارد تحتوي على أكثر من ملف موارد واحد إلى AAPT2 باستخدام العلامة --dir، لن تستفيد من مزايا تجميع الموارد التزايدي بهذه الطريقة.

يمكن أن تختلف أنواع ملفات الإخراج استنادًا إلى الإدخال الذي تقدّمه للتجميع، كما هو موضّح في الجدول التالي:

الجدول 1. أنواع ملفات الإدخال والإخراج الخاصة بالتجميع

الإدخال الإخراج

ملفات موارد XML، مثل السلسلة و النمط، الموجودة في الدليل res/values/ جدول موارد يحتوي على *.arsc.flat كملحق له

جميع ملفات الموارد الأخرى

الإدخال	الإخراج
ملفات موارد XML، مثل السلسلة و النمط، الموجودة في الدليل `res/values/`	جدول موارد يحتوي على `*.arsc.flat` كملحق له
جميع ملفات الموارد الأخرى	يتم تحويل جميع الملفات غير تلك الموجودة ضمن الدليل `res/values/` إلى ملفات XML ثنائية ذات امتدادات `.flat`. بالإضافة إلى ذلك، يتم ضغط جميع ملفات PNG تلقائيًا وتعتمد امتدادات `.png.flat`. إذا اخترت عدم ضغط ملفات PNG، يمكنك استخدام الخيار `--no-crunch` أثناء التجميع.

يتم تحويل جميع الملفات غير تلك الموجودة ضمن الدليل res/values/ إلى ملفات XML ثنائية ذات امتدادات *.flat.

بالإضافة إلى ذلك، يتم ضغط جميع ملفات PNG تلقائيًا وتعتمد امتدادات *.png.flat. إذا اخترت عدم ضغط ملفات PNG، يمكنك استخدام الخيار --no-crunch أثناء التجميع.

إنّ الملفات التي ينتجها AAPT2 ليست ملفات تنفيذية، ويجب تضمين هذه الملفات الثنائية لاحقًا كمدخلات في مرحلة الربط لإنشاء حزمة APK. ومع ذلك، فإنّ ملف APK الذي تم إنشاؤه ليس ملفًا تنفيذيًا يمكنك نشره على جهاز Android على الفور، لأنّه لا يحتوي على ملفات DEX ولم يتم توقيعه.

بنية التجميع

بناء الجملة العام لاستخدام compile هو كما يلي:

aapt2 compile path-to-input-files [options] -o output-directory/

في المثال التالي، يجمع AAPT2 ملفات الموارد المسماة values.xml وmyImage.png بشكل منفصل:

aapt2 compile project_root/module_root/src/main/res/values-en/strings.xml -o compiled/
aapt2 compile project_root/module_root/src/main/res/drawable/myImage.png -o compiled/

كما هو موضّح في الجدول 1، يعتمد اسم ملف الإخراج على اسم ملف الإدخال واسم الدليل الرئيسي.

في المثال السابق الذي تم فيه استخدام الملف strings.xml كملف إدخال، سيتم تلقائيًا تسمية ملف الإخراج aapt2 باسم values-en_strings.arsc.flat. ومع ذلك، فإنّ ملف drawable الذي تم تجميعه والمخزَّن في دليل drawable يحمل الاسم drawable_img.png.flat.

خيارات التجميع

تتوفّر عدة خيارات يمكنك استخدامها مع الأمر compile، كما هو موضّح في الجدول 2:

الجدول 2. خيارات أمر التجميع

خيار	الوصف
`-o path`	تحدّد هذه السمة مسار الإخراج للموارد التي تم تجميعها. هذه علامة مطلوبة، لأنّه يجب تحديد مسار إلى دليل يمكن لأداة AAPT2 إخراج الموارد المجمَّعة وتخزينها فيه.
`--dir directory`	تحدّد هذه السمة الدليل الذي سيتم البحث فيه عن الموارد. على الرغم من أنّه يمكنك استخدام هذه العلامة لتجميع ملفات موارد متعددة باستخدام أمر واحد، إلا أنّها توقف مزايا التجميع التدريجي. لذلك، يجب عدم استخدام هذا الخيار للمشاريع الكبيرة.
`--pseudo-localize`	تنشئ هذه السمة نُسخًا مزيّفة من السلاسل التلقائية، مثل `en-XA` و`en-XB`.
`--no-crunch`	يتم إيقاف معالجة ملفات PNG. استخدِم هذا الخيار إذا كنت قد عالجت ملفات PNG أو إذا كنت بصدد إنشاء إصدارات تصحيح أخطاء لا تتطلّب تقليل حجم الملف. يؤدي تفعيل هذا الخيار إلى تنفيذ أسرع ولكنه يزيد من حجم ملف الإخراج.
`--legacy`	تعامُل مع الأخطاء المسموح بها عند استخدام إصدارات سابقة من أداة AAPT على أنّها تحذيرات يجب استخدام هذا الخيار للأخطاء غير المتوقّعة في وقت الترجمة البرمجية. لحلّ المشاكل المتعلقة بالتغييرات المعروفة في السلوك التي قد تحدث أثناء استخدام AAPT2، يُرجى قراءة مقالة تغييرات السلوك عند استخدام AAPT2.
`-zip file`	‫`file` هو ملف ZIP يحتوي على الدليل `res` الذي سيتم البحث فيه عن الموارد.
`-output-text-symbols file`	تنشئ هذه السمة ملفًا نصيًا يحتوي على رموز الموارد في الملف المحدّد.
`-preserve-visibility-of-styleables`	في حال تحديدها، يتم تطبيق قواعد الظهور نفسها على العناصر القابلة للتصميم التي يتم استخدامها مع جميع الموارد الأخرى. وإلا، سيتم إتاحة جميع العناصر القابلة للتصميم للجميع.
`-visibility [public\|private\|default\|]`	تضبط هذه السمة مستوى إمكانية رؤية الموارد المجمَّعة.
`-trace-folder folder`	تُنشئ هذه السمة جزء تتبُّع بتنسيق JSON في المجلد المحدّد.`systrace`
`-source-path path`	يضبط مسار ملف المصدر لملف الموارد الذي تم تجميعه على path.
`-h`	تعرض هذه السمة معلومات المساعدة حول الأدوات.
`-v`	تفعِّل هذه السمة التسجيل المطوَّل.

رابط

في مرحلة الربط، يدمج AAPT2 جميع الملفات الوسيطة التي تنشئها مرحلة التجميع، مثل جداول الموارد وملفات XML الثنائية وملفات PNG المعالَجة، ثم يحزّم الملفات في حزمة APK واحدة. بالإضافة إلى ذلك، يمكن إنشاء ملفات مساعدة أخرى، مثل R.java وملفات قواعد ProGuard، خلال هذه المرحلة. ومع ذلك، لا تحتوي حزمة APK التي تم إنشاؤها على رمز بايت DEX وهي غير موقَّعة. لا يمكنك نشر حزمة APK هذه على جهاز.

إذا كنت لا تستخدم مكوّن Android Gradle الإضافي من أجل إنشاء تطبيقك من سطر الأوامر، يمكنك استخدام أدوات أخرى من سطر الأوامر، مثل d8 لتجميع رمز بايت Java في رمز بايت DEX، وapksigner لتوقيع حِزمة APK.

بنية الرابط

بناء الجملة العام لاستخدام link هو كما يلي:

aapt2 link path-to-input-files [options] -o
outputdirectory/outputfilename.apk --manifest AndroidManifest.xml

في المثال التالي، يدمج AAPT2 ملفَين وسيطَين، drawable_Image.flat وvalues_values.arsc.flat، والملف AndroidManifest.xml. يربط AAPT2 النتيجة بملف android.jar الذي يحتوي على الموارد المحدّدة في حزمة android:

 aapt2 link -o output.apk
 -I android_sdk/platforms/android_version/android.jar
    compiled/res/values_values.arsc.flat
    compiled/res/drawable_Image.flat --manifest /path/to/AndroidManifest.xml -v

خيارات الربط

يمكنك استخدام الخيارات التالية مع الأمر link:

الجدول 3. خيارات أمر الربط

خيار	الوصف
`-o path`	تحدِّد هذه السمة مسار الإخراج لحزمة APK الخاصة بالمورد المرتبط. هذا الخيار هو خيار إلزامي، لأنّه يجب تحديد مسار حزمة APK الناتجة التي يمكنها الاحتفاظ بالمراجع المرتبطة.
`--manifest file`	تحدِّد هذه السمة مسار ملف بيان Android المطلوب إنشاؤه. هذه علامة مطلوبة، لأنّ ملف البيان يتضمّن معلومات أساسية عن تطبيقك، مثل اسم الحزمة ومعرّف التطبيق.
`-I`	توفّر هذه السمة مسار `android.jar` أو حِزم APK أخرى، مثل `framework-res.apk`، التي قد تكون مفيدة أثناء إنشاء الميزات. يجب إضافة هذا العلامة إذا كنت تستخدم سمات مع مساحة الاسم `android` في ملفات الموارد.
`-A directory`	تحدّد هذه السمة دليل مواد العرض المطلوب تضمينه في حزمة APK. يمكنك استخدام هذا الدليل لتخزين الملفات الأصلية غير المعالَجة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الوصول إلى الملفات الأصلية.
`-R file`	تمرير ملف `.flat` فردي إلى `link`، باستخدام دلالات `overlay` بدون استخدام العلامة `<add-resource>` عند تقديم ملف موارد يتراكب مع ملف حالي، يتم استخدام آخر مورد متضارب تم تقديمه.
`--package-id package-id`	تحدّد هذه السمة معرّف الحزمة الذي سيتم استخدامه لتطبيقك. يجب أن يكون رقم تعريف الحزمة الذي تحدّده أكبر من أو يساوي 0x7f ما لم يتم استخدامه مع `--allow-reserved-package-id`.
`--allow-reserved-package-id`	يسمح هذا الإذن باستخدام معرّف حزمة محجوز. أرقام تعريف الحِزم المحجوزة هي أرقام تعريف يتم عادةً تخصيصها للمكتبات المشتركة، وهي تتراوح بين 0x02 و0x7e، بما في ذلك هذان الرقمَان. باستخدام `--allow-reserved-package-id`، يمكنك تعيين أرقام تعريف تندرج ضمن نطاق أرقام تعريف الحِزم المحجوزة. يجب استخدام هذا الخيار فقط للحِزم التي تتضمّن الإصدار `min-sdk` أو إصدارًا أقل من 26.
`--java directory`	تحدِّد هذه السمة الدليل الذي سيتم إنشاء `R.java` فيه.
`--proguard proguard_options`	تُنشئ هذه السمة ملف الإخراج لقواعد ProGuard.
`--proguard-conditional-keep-rules`	تنشئ هذه المهمة ملف الإخراج لقواعد ProGuard الخاصة بملف DEX الرئيسي.
`--no-auto-version`	توقِف هذه السمة إمكانية تحديد إصدار حزمة تطوير البرامج (SDK) تلقائيًا للأنماط والتنسيقات.
`--no-version-vectors`	توقف هذه السمة إنشاء إصدارات تلقائية من الرسومات المتجهة القابلة للرسم. استخدِم هذه العلامة فقط عند إنشاء حزمة APK باستخدام مكتبة Vector Drawable.
`--no-version-transitions`	توقِف هذه السمة إنشاء إصدارات تلقائية من موارد الانتقال. استخدِم هذه العلامة فقط عند إنشاء حزمة APK باستخدام مكتبة Transition Support.
`--no-resource-deduping`	تؤدي هذه السمة إلى إيقاف الإزالة التلقائية لتكرار الموارد التي تتضمّن قيمًا متطابقة في عمليات الضبط المتوافقة.
`--enable-sparse-encoding`	تفعِّل هذه السمة الترميز المتفرّق لإدخالات الموارد. يؤدي ذلك إلى تقليل حجم حِزم APK واستخدام الذاكرة ووقت استجابة بدء التشغيل، وزيادة طفيفة في وقت البحث عن الموارد الفردية بعد بدء التشغيل.
`-z`	يتطلّب ذلك توفير ترجمة للعبارات التي تم وضع علامة "مقترَحة" عليها.
`-c config`	توفّر هذه السمة قائمة بالإعدادات مفصولة بفواصل. على سبيل المثال، إذا كانت لديك تبعيات على مكتبة الدعم التي تحتوي على ترجمات لعدة لغات، يمكنك فلترة الموارد للغة معيّنة فقط، مثل الإنجليزية أو الإسبانية. يجب تحديد إعدادات اللغة باستخدام رمز لغة مكوّن من حرفَين وفق معيار ISO 639-1، ويمكن أن يتبعه بشكل اختياري رمز منطقة مكوّن من حرفَين وفق معيار ISO 3166-1-alpha-2، مع إضافة الحرف "r" صغيرًا قبله. على سبيل المثال، en-rUS.
`--preferred-density density`	يسمح AAPT2 باختيار الكثافة الأقرب تطابقًا وإزالة جميع الكثافات الأخرى. تتوفّر العديد من أدوات تحديد كثافة وحدات البكسل التي يمكنك استخدامها في تطبيقك، مثل ldpi وhdpi وxhdpi. عند تحديد الكثافة المفضّلة، يختار AAPT2 الكثافة الأقرب تطابقًا ويخزّنها في جدول الموارد، ويزيل جميع الكثافات الأخرى.
`--output-to-dir`	يُخرج محتوى حزمة APK إلى دليل محدّد بواسطة `-o`. إذا ظهرت لك أي أخطاء عند استخدام هذا الخيار، يمكنك حلّها من خلال الترقية إلى الإصدار 28.0.0 أو إصدار أحدث من "أدوات إنشاء حزمة تطوير البرامج (SDK) لنظام التشغيل Android".
`--min-sdk-version min-sdk-version`	تضبط هذه السمة الحد الأدنى التلقائي لإصدار حزمة SDK المطلوب استخدامه في `AndroidManifest.xml`.
`--target-sdk-version target-sdk-version`	تضبط هذه السمة إصدار حزمة تطوير البرامج (SDK) المستهدَف التلقائي الذي سيتم استخدامه في `AndroidManifest.xml`.
`--version-code version-code`	تحدّد هذه السمة رمز الإصدار الذي سيتم إدراجه في `AndroidManifest.xml` في حال عدم توفّره.
`--version-name version-name`	تحدّد هذه السمة اسم الإصدار الذي سيتم إدراجه في `AndroidManifest.xml` إذا لم يكن متوفّرًا.
`--revision-code revision-code`	تحدّد هذه السمة رمز المراجعة الذي سيتم إدراجه في ملف `AndroidManifest.xml` إذا لم يكن متوفّرًا.
`--replace-version`	في حال تحديد `--version-code` أو `--version-name` أو `--revision-code`، تحلّ هذه القيم محل أي قيمة مضمّنة في البيان. بشكلٍ تلقائي، لن يحدث أي تغيير إذا كان ملف البيان يحدّد هذه السمات.
`--compile-sdk-version-nacodeme compile-sdk-version-name`	تحدّد هذه السمة رمز الإصدار الذي سيتم إدراجه في ملف `AndroidManifest.xml` في حال عدم توفّره.
`--compile-sdk-version-name compile-sdk-version-name`	تحدِّد هذه السمة اسم الإصدار الذي سيتم إدراجه في ملف `AndroidManifest.xml` إذا لم يكن متوفّرًا.
`--proto-format`	تنشئ هذه السمة موارد مجمّعة بتنسيق Protobuf. مناسب كإدخال إلى `bundletool` لإنشاء "مجموعة حزمات تطبيق Android".
`--non-final-ids`	تنشئ `R.java` مع معرّفات الموارد غير النهائية. لا تتم إضافة مراجع إلى المعرّفات من رمز التطبيق أثناء تجميع `kotlinc` أو `javac`.
`--emit-ids path`	تُصدر هذه الدالة ملفًا في المسار المحدّد يتضمّن قائمة بأسماء أنواع الموارد وعمليات ربط المعرّفات الخاصة بها. هذا النوع مناسب للاستخدام مع `--stable-ids`.
`--stable-ids outputfilename.ext`	يستهلك هذا الإجراء الملف الذي تم إنشاؤه باستخدام `--emit-ids` والذي يحتوي على قائمة بأسماء أنواع الموارد وأرقام التعريف المخصّصة لها. يتيح هذا الخيار بقاء أرقام التعريف المخصّصة ثابتة حتى عند حذف موارد أو إضافة موارد جديدة أثناء الربط.
`--custom-package package_name`	تحدّد هذه السمة حزمة Java المخصّصة التي سيتم إنشاء `R.java` ضمنها.
`--extra-packages package_name`	ينشئ الملف `R.java` نفسه، ولكن بأسماء حِزم مختلفة.
`--add-javadoc-annotation annotation`	تضيف هذه السمة تعليقًا توضيحيًا من JavaDoc إلى جميع فئات Java التي تم إنشاؤها.
`--output-text-symbols path`	تنشئ هذه الأداة ملفًا نصيًا يحتوي على رموز الموارد الخاصة بالفئة `R` في الملف المحدّد. يجب تحديد مسار ملف الإخراج.
`--auto-add-overlay`	يسمح بإضافة موارد جديدة في التراكبات بدون استخدام العلامة `<add-resource>`.
`--rename-manifest-package manifest-package`	تعيد هذه السمة تسمية الحزمة في ملف `AndroidManifest.xml`.
`--rename-instrumentation-target-package instrumentation- target-package`	تغيير اسم الحزمة المستهدَفة لـ `instrumentation` يجب استخدام هذا الخيار مع `--rename-manifest-package`.
`-0 extension`	تحدّد هذه السمة امتدادات الملفات التي لا تريد ضغطها.
`--split path:config[,config[..]]`	تقسّم الموارد استنادًا إلى مجموعة من الإعدادات لإنشاء إصدار مختلف من حزمة APK. يجب تحديد مسار حزمة APK الناتجة مع مجموعة الإعدادات.
`--proguard-main-dex file`	ملف الإخراج لقواعد ProGuard التي تم إنشاؤها لملف DEX الرئيسي
`--proguard-minimal-keep-rules`	تنشئ هذه الأداة مجموعة الحد الأدنى من قواعد الاحتفاظ في ProGuard.
`--no-resource-removal`	يؤدي ذلك إلى إيقاف الإزالة التلقائية للموارد التي لا تتضمّن قيمًا تلقائية. لا تستخدِم هذا الخيار إلا عند إنشاء حِزم تراكب موارد وقت التشغيل.
`-x`	علم قديم يحدّد استخدام معرّف الحزمة 0x01.
`--product products-list`	تحدّد هذه السمة قائمة مفصولة بفواصل تتضمّن أسماء المنتجات المطلوب الاحتفاظ بها.
`--no-xml-namespaces`	يزيل بادئة مساحة اسم XML ومعلومات معرّف الموارد المنتظم (URI) من الملف `AndroidManifest.xml` وملفات XML الثنائية في `res/*`.
`--shared-lib`	تنشئ هذه السمة مكتبة وقت تشغيل Android مشترَكة.
`--static-lib`	تنشئ هذه السمة مكتبة Android ثابتة.
`--no-static-lib-packages`	يدمج جميع موارد المكتبة ضمن حزمة التطبيق.
`--no-proguard-location-reference`	يمنع ملفات قواعد ProGuard من الإشارة إلى الملف المصدر.
`--private-symbols package-name`	تحدّد `package-name` اسم الحزمة المطلوب استخدامه عند إنشاء `R.java` للرموز الخاصة. في حال عدم تحديد ذلك، تستخدم الرموز العامة والخاصة اسم حزمة التطبيق.
`--override-styles-instead-of-overlaying`	تتسبّب في أن تحلّ الأنماط المحدّدة في موارد `-R` محل التعريفات السابقة بدلاً من دمجها.
`--rename-resources-package package-name`	تعيد هذه السمة تسمية الحزمة في جدول الموارد إلى `package-name`.
`--no-compress`	لا يضغط أي موارد.
`--keep-raw-values`	يحافظ على قيم السمات الأولية في ملفات XML.
`--no-compress-regex regular-expression`	لا يضغط الإضافات التي تتطابق مع `regular-expression`. استخدِم الرمز `$` لنهاية السطر. يستخدم قواعد نحوية للتعبيرات العادية في ECMAScript حساسة لحالة الأحرف.
`--warn-manifest-validation`	تعامِل هذه السمة مع أخطاء التحقّق من صحة ملف البيان على أنّها تحذيرات.
`--exclude-configs qualifier[,qualifier[..]]`	يستبعد هذا الحقل قيم الموارد التي تحتوي إعداداتها على المؤهّلات المحدّدة.
`--debug-mode`	يُدرج `android:debuggable="true"` في عقدة التطبيق في البيان، ما يتيح إمكانية تصحيح أخطاء التطبيق حتى على الأجهزة المخصّصة للإصدار العلني.
`--strict-visibility`	لا يسمح بتراكبات بمستويات رؤية مختلفة.
`--exclude-sources`	لا يتم تسلسل معلومات الملف المصدر عند إنشاء موارد بتنسيق Protobuf.
`--trace-folder folder`	تنشئ هذه السمة جزء تتبُّع بتنسيق JSON `systrace` إلى `folder` المحدّد.
`--merge-only`	يتم دمج الموارد فقط بدون التحقّق من مراجع الموارد. يجب استخدام هذه العلامة مع العلامة `--static-lib` فقط.
`-h`	تعرض قائمة المساعدة.
`-v`	تتيح زيادة تفاصيل الإخراج.

نسخ

يُستخدَم dump لعرض معلومات حول حزمة APK التي أنشأتها باستخدام الأمر link.

بنية التفريغ

بناء الجملة العام لاستخدام dump هو كما يلي:

aapt2 dump sub-command filename.apk [options]

يعرض المثال التالي المحتوى من جدول الموارد لحزمة APK المحدّدة:

aapt2 dump resources output.apk

الأوامر الفرعية الخاصة بأداة تفريغ الذاكرة

حدِّد أحد الأوامر الفرعية التالية باستخدام الأمر dump:

الجدول 4. الأوامر الفرعية الخاصة بأداة تفريغ الذاكرة

الأمر الفرعي	الوصف
`apc`	تعرض هذه السمة محتوى حاوية AAPT2 (APC) التي تم إنشاؤها أثناء عملية التجميع.
`badging`	تعرض هذه السمة المعلومات المستخرَجة من ملف البيان الخاص بحزمة APK.
`configurations`	تعرض كل إعداد مستخدَم من خلال أحد الموارد في حزمة APK.
`overlayable`	تعرض هذه السمة الموارد القابلة للتراكب في حزمة APK.
`packagename`	تعرض هذه السمة اسم حزمة APK.
`permissions`	تعرض هذه السمة الأذونات المستخرَجة من ملف بيان حزمة APK.
`strings`	تعرض هذه السمة محتويات مجموعة سلاسل جدول موارد حِزمة APK.
`styleparents`	تعرض هذه السمة العناصر الرئيسية للأنماط المستخدَمة في حزمة APK.
`resources`	تعرض هذه السمة محتويات جدول موارد حزمة APK.
`xmlstrings`	تتم طباعة السلاسل من ملف XML المجمَّع لحزمة APK.
`xmltree`	تعرض شجرة XML المجمَّعة لحزمة APK.

خيارات التفريغ

استخدِم الخيارات التالية مع dump:

الجدول 5. خيارات التفريغ

خيار	الوصف
`--no-values`	يؤدي إلى إيقاف عرض قيم الموارد.
`--file file`	تحدّد هذه السمة ملفًا كوسيطة سيتم تفريغه من حزمة APK.
`-v`	تزيد من تفاصيل الناتج.

Diff

استخدِم diff لمقارنة حزمتَي APK وتحديد أي اختلافات بينهما.

بنية الاختلاف

بناء الجملة العام لاستخدام diff هو كما يلي:

aapt2 diff first.apk second.apk

لا تتوفّر خيارات للأمر diff.

تحسين

يتم استخدام optimize لتنفيذ عمليات تحسين على الموارد المدمجة وresources.arsc قبل تجميعها في حِزمة APK. يمكن أن يؤدي هذا التحسين إلى تقليل حجم حزمة APK بنسبة تتراوح بين %1 و%3 تقريبًا، وذلك حسب حجم وعدد الموارد المستخدَمة.

تحسين البنية

بناء الجملة العام لاستخدام optimize هو كما يلي:

aapt2 optimize options file[,file[..]]

يحسّن المثال التالي الموارد في input.apk وينشئ حزمة APK جديدة ومحسّنة في output.apk. ويحلّ هذا التنسيق محلّ التمثيل العادي للجدول الثابت بتمثيل أكثر إحكامًا، ما يؤدي إلى تقليل حجم حِزمة APK واستخدام الذاكرة ووقت الاستجابة عند بدء التشغيل، وزيادة طفيفة في وقت البحث عن الموارد الفردية بعد بدء التشغيل.

aapt2 optimize -o output.apk --enable-sparse-encoding input.apk

خيارات التحسين

يمكنك استخدام الخيارات التالية مع optimize:

الجدول 6. خيارات التحسين

خيار	الوصف
`-o path`	تحدِّد هذه السمة مسار الإخراج لحزمة APK الخاصة بالمورد المرتبط. هذا الخيار هو خيار إلزامي، لأنّه يجب تحديد مسار حزمة APK الناتجة التي يمكنها الاحتفاظ بالمراجع المرتبطة.
`-d directory`	تحدِّد هذه السمة مسار دليل الإخراج للتقسيمات.
`-x path`	تحدِّد هذه السمة مسار ملف إعداد XML.
`-p`	يطبع عناصر حِزم APK المتعددة ويخرج.
`--target-densities density[,density[..]]`	تحدّد هذه السمة قائمة مفصولة بفواصل بكثافات الشاشة التي تم تحسين حِزمة APK لها. تتم إزالة جميع الموارد التي لن يتم استخدامها على الأجهزة ذات الكثافات المحدّدة من حِزمة APK.
`--resources-config-path path`	تحدّد هذه السمة مسار ملف `resources.cfg` الذي يحتوي على قائمة بالمراجع وتوجيهات لكل مرجع. التنسيق: `type/resource_name#[directive][,directive]`
`-c config[,config[..]]`	تحدّد هذه السمة قائمة مفصولة بفواصل تتضمّن الإعدادات المطلوب تضمينها. القيمة التلقائية هي جميع عمليات الإعداد.
`--split path:config[,config[..]]`	تقسّم الموارد استنادًا إلى مجموعة من الإعدادات لإنشاء إصدار مختلف من حزمة APK. يجب تحديد مسار حزمة APK الناتجة مع مجموعة الإعدادات.
`--keep-artifacts artifact[,artifact[..]]`	تحدّد هذه السمة قائمة مفصولة بفواصل للعناصر المطلوب الاحتفاظ بها. إذا لم يتم تحديد أي منها، سيتم الاحتفاظ بجميع العناصر.
`--enable-sparse-encoding`	تفعِّل هذه السمة الترميز المتفرّق لإدخالات الموارد. يؤدي ذلك إلى تقليل حجم حِزم APK واستخدام الذاكرة ووقت استجابة بدء التشغيل، وزيادة طفيفة في وقت البحث عن الموارد الفردية بعد بدء التشغيل.
`--collapse-resource-names`	يؤدي إلى تصغير أسماء الموارد إلى قيمة واحدة في مجموعة سلاسل المفاتيح. يتم استثناء الموارد باستخدام التوجيه `no_collapse` في ملف محدّد بواسطة `--resources-config-path`.
`--shorten-resource-paths`	تقصير مسارات الموارد داخل حِزمة APK
`--resource-path-shortening-map path`	تحدّد هذه السمة المسار الذي سيتم فيه إخراج خريطة مسارات الموارد القديمة إلى مسارات مختصرة.
`-v`	تزيد من تفاصيل الناتج.
`-h`	تعرض هذه السمة مساعدة الأداة.

التحويل

بشكلٍ تلقائي، يجمع الأمر AAPT compile الموارد في تنسيق ثنائي مناسب لحِزم APK. يمكنك أيضًا تحديد تنسيق protobuf المناسب لحِزم AAB من خلال تحديد --proto-format. يحوّل الأمر convert حِزم APK بين التنسيقَين.

بنية التحويل

بناء الجملة العام لـ convert هو كما يلي:

aapt2 convert -o output-file options file[,file[..]]

يحوّل المثال التالي الموارد في input.apk وينشئ حزمة APK جديدة في output.apk تحتوي على موارد بتنسيق protobuf. ويحلّ هذا التنسيق محل التمثيل العادي للجدول المسطّح، ما يؤدي إلى تقليل حجم حزمة APK واستخدام الذاكرة ووقت استجابة بدء التشغيل، بالإضافة إلى زيادة طفيفة

aapt2 convert -o output.apk --output-format proto --enable-sparse-encoding input.apk

خيارات التحويل

استخدِم الخيارات التالية مع convert:

الجدول 7. خيارات التحويل

خيار	الوصف
`-o path`	تحدِّد هذه السمة مسار الإخراج لحزمة APK الخاصة بالمورد المرتبط. هذا الخيار هو خيار إلزامي، لأنّه يجب تحديد مسار حزمة APK الناتجة التي يمكنها الاحتفاظ بالمراجع المرتبطة.
`--output-format [proto\|binary]`	تنسيق الإخراج القيمتان المقبولتان هما `proto` و`binary`. في حال عدم ضبطها، تكون القيمة التلقائية `binary`.
`--enable-sparse-encoding`	تفعِّل هذه السمة الترميز المتفرّق لإدخالات الموارد. يؤدي ذلك إلى تقليل حجم حِزم APK واستخدام الذاكرة ووقت استجابة بدء التشغيل، وزيادة طفيفة في وقت البحث عن الموارد الفردية بعد بدء التشغيل.
`--keep-raw-values`	يحافظ على قيم السمات الأولية في ملفات XML.
`-v`	تزيد من تفاصيل الناتج.
`-h`	تعرض هذه السمة مساعدة الأداة.

وضع البرنامج الخفي

قدّم الإصدار 2.19 من "أداة اختبار تطبيقات Android" وضع البرنامج الخفي لإصدار الأوامر. يتيح لك وضع Daemon إدخال أوامر متعددة في جلسة AAPT واحدة.

بنية البرنامج الخفي

ابدأ وضع البرنامج الخفي باستخدام الأمر التالي:

aapt2 daemon

بعد تشغيل وضع البرنامج الخفي، يمكنك إدخال الأوامر. يجب أن تكون كل وسيطة من وسيطات الأمر في سطر منفصل، مع ترك سطر فارغ في نهاية الأمر. اخرُج من وضع البرنامج الخفي عن طريق كتابة Control+D.

ضَع في اعتبارك أوامر compile الفردية التالية:

aapt2 compile project_root/module_root/src/main/res/values-en/strings.xml -o compiled/
aapt2 compile project_root/module_root/src/main/res/drawable/myImage.png -o compiled/

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

aapt2 daemon
Ready
compile
project_root/module_root/src/main/res/values-en/strings.xml
-o
compiled/

Done
compile
project_root/module_root/src/main/res/drawable/myImage.png
-o
compiled/

Done
^D
Exiting daemon

خيارات وضع التشغيل كخدمة

الخيار الوحيد لوضع البرنامج الخفي هو --trace-folder folder، الذي ينشئ جزء تتبُّع بتنسيق systrace JSON إلى folder المحدّد.

الإصدار

حدِّد إصدار AAPT2 الذي تستخدمه باستخدام الأمر version:

aapt2 version
Android Asset Packaging Tool (aapt) 2.19-8678579

تغييرات السلوك عند استخدام AAPT2

قبل AAPT2، كان AAPT هو الإصدار التلقائي من "أداة تجميع حِزم مواد العرض في Android"، الذي تم إيقافه نهائيًا الآن. على الرغم من أنّ AAPT2 من المفترض أن يعمل على الفور مع المشاريع القديمة، يوضّح هذا القسم بعض التغييرات في السلوك التي يجب أن تكون على دراية بها.

العروض الهرمية للعناصر في ملف بيان Android

في الإصدارات السابقة من AAPT، كان يتم تجاهل العناصر المتداخلة في عُقد غير صحيحة في ملف AndroidManifest.xml أو كان يتم عرض تحذير بشأنها. على سبيل المثال، إليك المثال التالي:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
   package="com.example.myname.myapplication">
   <application
       ...
       <activity android:name=".MainActivity">
           <intent-filter>
               <action android:name="android.intent.action.MAIN" />
               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>
           <action android:name="android.intent.action.CUSTOM" />
       </activity>
   </application>
</manifest>

كانت الإصدارات السابقة من أداة AAPT تتجاهل ببساطة العلامة <action> في غير موضعها.

عند استخدام AAPT2، يظهر لك الخطأ التالي:

AndroidManifest.xml:15: error: unknown element <action> found.

لحلّ المشكلة، تأكَّد من أنّ عناصر البيان متداخلة بشكل صحيح. لمزيد من المعلومات، يُرجى الاطّلاع على نظرة عامة على بيان التطبيق.

تعريف الموارد

لم يعُد بإمكانك تحديد نوع المرجع من السمة name. يوضّح المثال التالي تعريفًا غير صحيح لعنصر المورد attr:

<style name="childStyle" parent="parentStyle">
    <item name="attr/my_attr">@color/pink</item>
</style>

يؤدي تعريف نوع مورد بهذه الطريقة إلى ظهور خطأ الإنشاء التالي:

Error: style attribute 'attr/attr/my_attr (aka my.package:attr/attr/my_attr)'
not found.

لحلّ هذا الخطأ، عليك تحديد النوع بشكل صريح باستخدام type="attr":

<style name="childStyle" parent="parentStyle">
  <item type="attr" name="my_attr">@color/pink</item>
</style>

بالإضافة إلى ذلك، عند تعريف عنصر <style>، يجب أن يكون العنصر الرئيسي أيضًا من نوع مورد نمط. وإلا، سيظهر لك خطأ مشابه لما يلي:

Error: (...) invalid resource type 'attr' for parent of style

استخدام غير صحيح لرموز مرجع المورد @

يُصدر AAPT2 أخطاء في الإنشاء عند حذف رموز مراجع الموارد (@) أو وضعها بشكل غير صحيح، مثلاً عند حذف الرمز عند تحديد سمة نمط:

<style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
  ...
  <!-- Note the missing '@' symbol when specifying the resource type. -->
  <item name="colorPrimary">color/colorPrimary</item>
</style>

عند إنشاء الوحدة، يعرض AAPT2 خطأ الإنشاء التالي:

ERROR: expected color but got (raw string) color/colorPrimary

بالإضافة إلى ذلك، إذا أدرجت الرمز بشكل غير صحيح عند الوصول إلى مورد من مساحة الاسم android، سيحدث ما يلي:

...
<!-- When referencing resources from the 'android' namespace, omit the '@' symbol. -->
<item name="@android:windowEnterAnimation"/>

عند إنشاء الوحدة، يعرض AAPT2 خطأ الإنشاء التالي:

Error: style attribute '@android:attr/windowEnterAnimation' not found

إعداد المكتبات بشكل غير صحيح

إذا كان تطبيقك يعتمد على مكتبة تابعة لجهة خارجية تم إنشاؤها باستخدام إصدارات قديمة من أدوات إنشاء حزمة تطوير البرامج (SDK) لنظام التشغيل Android، قد يتعطّل تطبيقك أثناء وقت التشغيل بدون عرض أي أخطاء أو تحذيرات. قد يحدث هذا التعطُّل لأنّه أثناء إنشاء المكتبة، يتم تعريف الحقول R.java على أنّها final. نتيجةً لذلك، يتم تضمين جميع معرّفات الموارد في فئات المكتبة.

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

لحلّ هذا الخطأ، تواصَل مع مؤلف المكتبة لإعادة إنشائها باستخدام أحدث إصدار من أدوات تصميم حزمة تطوير البرامج (SDK) لنظام Android، وأعِد نشر المكتبة.

معيار AAPT2 تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تنزيل أداة AAPT2 من Google Maven

تجميع

بنية التجميع

خيارات التجميع

رابط

بنية الرابط

خيارات الربط

نسخ

بنية التفريغ

الأوامر الفرعية الخاصة بأداة تفريغ الذاكرة

خيارات التفريغ

Diff

بنية الاختلاف

تحسين

تحسين البنية

خيارات التحسين

التحويل

بنية التحويل

خيارات التحويل

وضع البرنامج الخفي

بنية البرنامج الخفي

خيارات وضع التشغيل كخدمة

الإصدار

تغييرات السلوك عند استخدام AAPT2

العروض الهرمية للعناصر في ملف بيان Android

تعريف الموارد

استخدام غير صحيح لرموز مرجع المورد @

إعداد المكتبات بشكل غير صحيح

معيار AAPT2