أداة AAPT2

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

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

لتنزيل أدوات إصدار حزمة تطوير البرامج (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 التجميع الأسرع للموارد من خلال تفعيل التجميع التزايدي. لإنجاز التجميع المتزايد، يتم تقسيم معالجة الموارد إلى خطوتَين:

  • تجميع: لجمع ملفات الموارد في تنسيقات ثنائية.
  • الربط: يدمج كل الملفات المجمّعة ويضعها في حزمة واحدة.

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

تنزيل AAPT2 من Google Maven

للحصول على أحدث إصدار من AAPT2 غير مضمَّن في أدوات الإصدار، يمكنك تنزيل AAPT2 من مستودع Maven من Google على النحو التالي:

  1. في فهرس المستودع، انتقِل إلى com.android.tools.build > aapt2.
  2. انسخ اسم أحدث إصدار من AAPT2.
  3. أدرِج اسم الإصدار الذي نسخته في عنوان 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-4418-4

  4. انتقِل إلى عنوان URL في متصفّح. سيبدأ تنزيل AAPT2 بعد قليل.

  5. فُكَّ حزمة ملف JAR الذي نزّلته.

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

تجميع

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

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

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

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

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

يتم تحويل جميع الملفات الأخرى غير الملفات المدرَجة في الدليل 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_img.png.flat.

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

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

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

Option الوصف
-o path

تُحدِّد مسار الإخراج للموارد المجمَّعة.

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

--dir directory

تحدِّد هذه العلامة الدليل الذي يمكن من خلاله البحث عن الموارد.

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

--pseudo-localize تنشئ إصدارات pseudolocalized من السلاسل التلقائية، مثل 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 ينشئ جزء تتبُّع systrace JSON إلى المجلد المحدَّد.
-source-path path لضبط مسار ملف المصدر المجمّع على path.
-h تعرض مساعدة الأدوات.
-v تعمل هذه السياسة على تفعيل التسجيل المطوَّل.

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

إذا كنت لا تستخدم مكوّن Gradle الإضافي لنظام التشغيل Android من أجل إنشاء تطبيقك من سطر الأوامر، يمكنك استخدام أدوات سطر أوامر أخرى، مثل d8 لتجميع رمز بايت Java إلى رمز بايت DEX وsitemapsigner لتوقيع ملف 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. خيارات أوامر الرابط

Option الوصف
-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، يمكنك تحديد أرقام تعريف تقع ضمن نطاق أرقام تعريف الحِزم المحجوزة.

لا يجب استخدام هذا الخيار إلّا للحزم التي تتضمّن الإصدار 26 من min-sdk أو الإصدارات الأقدم.

--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 باستخدام مكتبة دعم النقل.
--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. استخدِم الرمز $ لنهاية السطر. وتستخدم قواعد تعبير عادي حساسة لحالة الأحرف.
--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. خيارات التفريغ

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

الفرق

يمكنك استخدام 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. خيارات "أدوات تحسين الأداء"

Optionالوصف
-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. من الممكن أيضًا تحديد تنسيق النموذج الأوّلي المناسب لشبكات 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. خيارات التحويل

Optionالوصف
-o path

تحدِّد مسار الإخراج لحزمة APK للمورد المرتبطة.

هذه علامة مطلوبة، لأنّه يجب تحديد مسار ملف APK الناتج الذي يمكن أن يحتوي على الموارد المرتبطة.

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

الوضع الخفي

قدّم الإصدار 2.19 من AAPT الوضع الخفي لإصدار الأوامر. يتيح لك الوضع الخفي إدخال أوامر متعددة في جلسة 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، ثم إعادة نشر المكتبة.