تغيير قيمة موارد التطبيق في وقت التشغيل

تراكب موارد وقت التشغيل (RRO) عبارة عن حزمة تغير قيم الموارد للحزمة المستهدفة في وقت التشغيل. على سبيل المثال، تطبيق مثبَّت على النظام قد تغير الصورة سلوكها بناءً على قيمة المورد. بدلاً من ترميزًا ثابتًا لقيمة المورد في وقت التصميم، وتم تثبيت RRO على يمكن أن تغير قيم موارد التطبيق في وقت التشغيل.

يمكن تفعيل RROs أو إيقافها. يمكنك تعيين حالة تمكين/تعطيل لتبديل قدرة RRO على تغيير قيم المورد. الموارد المنتظمة المتنقلة بشكل افتراضي (ومع ذلك، يتم تمكين سجلات RRO الثابتة من خلال الافتراضي).

موارد التراكب

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

إعداد البيان

تُعتبَر الحزمة حزمة RRO إذا كانت تحتوي على علامة <overlay> كعلامة التابعة للعلامة <manifest>.

  • تحدّد قيمة السمة android:targetPackage المطلوبة الاسم من الحزمة التي تنوي RRO تركيبها.

  • تحدّد قيمة السمة الاختيارية android:targetName اسم مجموعة فرعية قابلة للتراكب من موارد الحزمة المستهدفة التي تهدف RRO إلى تراكب. وإذا لم يحدد الهدف مجموعة من الموارد قابلة للتراكب، ألّا تكون السمة متوفّرة.

يعرض الرمز التالي مثالاً على التراكب AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.overlay">
    <application android:hasCode="false" />
    <overlay android:targetPackage="com.example.target"
                   android:targetName="OverlayableResources"/>
</manifest>

لا يمكن للتراكبات تراكب التعليمات البرمجية، لذلك لا يمكن أن تحتوي على ملفات DEX. بالإضافة إلى ذلك، السمة android:hasCode للسمة <application> في البيان يجب أن تكون تم الضبط على false

تحديد خريطة الموارد

في نظام Android 11 أو الإصدارات الأحدث، فإن الآلية الموصى بها تحديد خريطة موارد التراكب هو إنشاء ملف في res/xml لحزمة التراكب، قم بتعداد الموارد المستهدفة التي ينبغي المركبة وقيمها البديلة، ثم تعيين قيمة السمة android:resourcesMap لعلامة البيان <overlay> إلى مرجع إلى ملف تعيين الموارد.

يعرض الرمز التالي مثالاً على ملف res/xml/overlays.xml.

<?xml version="1.0" encoding="utf-8"?>
<overlay xmlns:android="http://schemas.android.com/apk/res/android" >
    <!-- Overlays string/config1 and string/config2 with the same resource. -->
    <item target="string/config1" value="@string/overlay1" />
    <item target="string/config2" value="@string/overlay1" />

    <!-- Overlays string/config3 with the string "yes". -->
    <item target="string/config3" value="@android:string/yes" />

    <!-- Overlays string/config4 with the string "Hardcoded string". -->
    <item target="string/config4" value="Hardcoded string" />

    <!-- Overlays integer/config5 with the integer "42". -->
    <item target="integer/config5" value="42" />
</overlay>

يعرض الرمز التالي مثالاً على بيان التراكب.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.overlay">
    <application android:hasCode="false" />
    <overlay android:targetPackage="com.example.target"
                   android:targetName="OverlayableResources"
                   android:resourcesMap="@xml/overlays"/>
</manifest>

بناء الحزمة

يتوافق الإصدار 11 من نظام Android أو الإصدارات الأحدث مع قاعدة إصدار Thatg في العناصر المركّبة التي تمنع أداة Android Asset Packaging Tool 2 (AAPT2) من محاولة إزالة تكرار الإعدادات للموارد التي لها القيمة نفسها (--no-resource-deduping) ومن إزالة الموارد بدون الإعداد التلقائي من الإعدادات (--no-resource-removal). يوضح الرمز التالي مثالاً ملف Android.bp.

runtime_resource_overlay {
    name: "ExampleOverlay",
    sdk_version: "current",
}

حلّ المراجع

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

على سبيل المثال، إذا كان التراكب يحدّد قيمة لضبط drawable-en ويحدّد الهدف قيمة للمَعلمتَين drawable-en-port وdrawable-en-port مطابقة أفضل، وبالتالي فإن قيمة الإعداد المستهدف drawable-en-port يتم اختيارها في وقت التشغيل لتراكب جميع إعدادات drawable-en، يؤدي التراكب يجب أن يحدد قيمة لكل إعداد drawable-en يحدده الهدف.

يمكن أن تشير التراكبات إلى مواردها الخاصة، بسلوكيات مختلفة بين إصدارات Android

  • في نظام التشغيل Android 11 أو الإصدارات الأحدث، يكون لكل طبقة دورها الخاص مساحة معرف المورد المحجوزة التي لا تتداخل مع مساحة معرّف المورد المستهدف أو مساحات معرفات موارد التراكب الأخرى، بحيث تشير التراكبات إلى مواردها الخاصة كما هو متوقع.

  • في Android 10 أو الإصدارات الأقدم، تشترك العناصر المركّبة وحزم الاستهداف في المورد نفسه. مساحة تعريف الهوية، والتي يمكن أن تتسبب في حدوث تضاربات وحدوث سلوك غير متوقع عند المحاولة للإشارة إلى مواردها الخاصة باستخدام بنية @type/name.

تفعيل/إيقاف التراكبات

استخدام واجهة برمجة التطبيقات OverlayManager لتفعيل التراكبات القابلة للتغيّر وإيقافها (استرداد واجهة برمجة التطبيقات باستخدام Context#getSystemService(Context.OVERLAY_SERVICE)). إنّ لا يمكن تمكين التراكب إلا من خلال الحزمة التي تستهدفها أو من خلال حزمة تحتوي على إذن android.permission.CHANGE_OVERLAY_PACKAGES. عندما يكون تراكب مُفعَّل أو موقوف، يتم نشر أحداث تغيير الضبط في الحزمة المستهدفة والأنشطة المستهدفة.

تقييد الموارد القابلة للتراكب

في الإصدار Android 10 أو الإصدارات الأحدث، تعرض علامة XML الخاصة بـ <overlayable> مجموعة من الموارد أنه يُسمح بتراكب RROs. في المثال التالي res/values/overlayable.xml ملف وstring/foo وinteger/bar عبارة عن موارد واستخدامها لتحديد موضوع مظهر الجهاز لتراكب هذه الموارد، وتراكب أن يستهدف بشكل صريح مجموعة الموارد القابلة للتراكب حسب الاسم.

<!-- The collection of resources for theming the appearance of the device -->
<overlayable name="ThemeResources">
       <policy type="public">
               <item type="string" name="foo/" />
               <item type="integer" name="bar/" />
       </policy>
       ...
</overlayable>

يمكن أن تحدّد حزمة APK عدة علامات <overlayable>، ولكن يجب أن يكون لكل علامة علامة فريدة. اسم داخل الحزمة. على سبيل المثال:

  • يمكن ضبط حزمتَين مختلفتَين على تحديد <overlayable name="foo">.

  • غير مسموح بأن تشتمل حزمة APK واحدة على كتلتَي <overlayable name="foo">.

يعرض الرمز التالي مثالاً على تراكب في AndroidManifest.xml الملف.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="com.my.theme.overlay">
       <application android:hasCode="false" />
       <!-- This overlay will override the ThemeResources resources -->
       <overlay android:targetPackage="android" android:targetName="ThemeResources">
</manifest>

عندما يحدّد أحد التطبيقات علامة <overlayable>، تعمل العناصر المركّبة التي تستهدف هذا التطبيق على ما يلي:

  • يجب تحديد targetName.

  • يمكن تركيب الموارد المدرَجة ضمن العلامة <overlayable> فقط.

  • يمكن استهداف اسم <overlayable> واحد فقط.

لا يمكنك تمكين تراكب يستهدف حزمة تعرض حزمة قابلة للتراكب الموارد ولكنه لا يستخدم android:targetName لاستهداف نوع معين العلامة <overlayable>

فرض قيود على السياسات

استخدِم العلامة <policy> لفرض قيود على الموارد القابلة للتراكب. تشير رسالة الأشكال البيانية تحدّد السمة type السياسات التي يجب أن يستوفيها المحتوى المركّب الموارد المضمنة. تشمل الأنواع المتوافقة ما يلي.

  • public يمكن لأي تراكب إلغاء المورد.
  • system يمكن لأي تراكب على قسم النظام أن يلغي الموارد.
  • vendor يمكن لأي تراكب في قسم المورِّد إلغاء الموارد.
  • product يمكن لأي تراكب في قسم المنتج إلغاء الموارد.
  • oem يمكن لأي تراكب في قسم المصنّع الأصلي للجهاز إلغاء الموارد.
  • odm يمكن لأي تراكب على قسم odm إلغاء الموارد.
  • signature يمكن لأي تراكب يتم توقيعه بالتوقيع نفسه مثل حزمة APK المستهدفة الموارد.
  • actor يمكن لأي تراكب تم توقيعه بالتوقيع نفسه مثل حزمة APK الممثل الموارد. تم الإعلان عن المُنفِّذ في علامة name-actor في النظام .
  • config_signature أي تراكب يتم توقيعه بالتوقيع نفسه مثل يمكن أن يلغي ملف apk overlay-config الموارد. إن تهيئة التراكب تعريفه في العلامة overlay-config-signature في إعدادات النظام.

يعرض الرمز التالي مثالاً على علامة <policy> في ملف res/values/overlayable.xml.

<overlayable name="ThemeResources">
   <policy type="vendor" >
       <item type="string" name="foo" />
   </policy>
   <policy type="product|signature"  >
       <item type="string" name="bar" />
       <item type="string" name="baz" />
   </policy>
</overlayable>

لتحديد سياسات متعدّدة، استخدِم الأشرطة العمودية (|) كأحرف فاصلة. عند تحديد سياسات متعددة، يجب أن يفي المركّب بعرض سياسة واحدة فقط. لإلغاء الموارد المدرجة في العلامة <policy>.

تهيئة التراكبات

يتوافق Android مع آليات مختلفة لضبط قابلية التغيّر (الإعداد التلقائي). وحالته وأولويته وفقًا لإصدار إصدار Android.

  • يمكن للأجهزة التي تعمل بنظام التشغيل Android 11 أو الإصدارات الأحدث استخدام ملف OverlayConfig (config.xml) بدلاً من سمات البيان. استخدام ملف التراكب هو الطريقة الموصى بها للتراكبات.

  • يمكن لجميع الأجهزة استخدام سمات البيان (android:isStatic و android:priority) لضبط عمليات تسجيل الموارد المنتظمة (RRO) الثابتة.

استخدام OverlayConfig

في الإصدار 11 من Android أو الإصدارات الأحدث، يمكنك استخدام OverlayConfig لإجراء ما يلي: تهيئة قابلية التغيّر والحالة التلقائية وأولوية التراكبات. للتهيئة تراكب أو إنشاء أو تعديل الملف الموجود في partition/overlay/config/config.xml، حيث partition هو قسم التراكب المراد تكوينه. لكي تتم التهيئة، يجب وضع تراكب في دليل overlay/ للقسم الذي تم إعداد التراكب فيه. تشير رسالة الأشكال البيانية يعرض الرمز التالي مثالاً على product/overlay/config/config.xml.

<config>
    <merge path="OEM-common-rros-config.xml" />
    <overlay package="com.oem.overlay.device" mutable="false" enabled="true" />
    <overlay package="com.oem.green.theme" enabled="true" />
</config>"

تتطلّب العلامة <overlay> إضافة السمة package التي تشير إلى نوع التراكب. تهيئة الحزمة. تتحكّم السمة الاختيارية enabled في ما إذا أو لا يتم تفعيل التراكب تلقائيًا (الإعداد التلقائي هو false). دالة اختيارية تحدد السمة mutable ما إذا كان التراكب قابلاً للتغيير ويمكن أن تغيّرت حالة تفعيله آليًا في وقت التشغيل (الإعداد التلقائي هو true). تكون التراكبات غير المدرَجة ضمن ملف الإعداد قابلة للتغيير ويتم إيقافها من خلال الافتراضي.

أولوية التراكب

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

  • system
  • vendor
  • odm
  • oem
  • product
  • system_ext

دمج الملفات

يسمح استخدام علامات <merge> بدمج ملفات الإعداد الأخرى في الموضع المحدد في ملف التهيئة. السمة path للعلامة مسار الملف المطلوب دمجه بالنسبة إلى الدليل الذي يحتوي على ملفات تهيئة التراكب.

استخدام سمات البيان أو سجلّات الموارد المنتظمة (RRO) الثابتة

في نظام التشغيل Android 10 أو الإصدارات الأقدم، يتم ضبط قابلية التغيّر في التراكب وأولوية التطبيقات باستخدام سمات البيان التالية.

  • android:isStatic وعندما يتم ضبط قيمة هذه السمة المنطقية على true، يتم تمكين التراكب افتراضيًا وغير قابل للتغيير، مما يمنع التراكب من الإيقاف.

  • android:priority قيمة هذه السمة الرقمية (التي تؤثر فقط تراكبات ثابتة) تهيئ أولوية التراكب عندما تكون عمليات التراكب الثابتة تستهدف التراكبات قيمة المورد نفسها. يشير الرقم الأعلى إلى أنّ الرقم الأسبقية.

يعرض الرمز التالي مثالاً على AndroidManifest.xml.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.overlay">
    <application android:hasCode="false" />
    <overlay android:targetPackage="com.example.target"
                   android:isStatic="true"
                   android:priority="5"/>
</manifest>

التغييرات التي تم إجراؤها في Android 11

في نظام التشغيل Android 11 أو الإصدارات الأحدث، إذا تم تطبيق في partition/overlay/config/config.xml، يتم إعداد التراكبات باستخدام ذلك الملف وandroid:isStatic وandroid:priority، التراكبات الموجودة في القسم. تحديد ملف تهيئة تراكب في أي على الأقل أولوية قسم التراكب.

بالإضافة إلى ذلك، يزيل نظام Android 11 أو الإصدارات الأحدث هذه الميزة. استخدام تراكبات ثابتة للتأثير على قيم الموارد التي تتم قراءتها أثناء الحزمة التثبيت. بالنسبة إلى حالة الاستخدام الشائعة لاستخدام التراكبات الثابتة لتغيير القيم المنطقية التي تهيئ حالة تفعيل المكون، فاستخدم علامة SystemConfig لبرامج <component-override> (جديدة في Android) 11.

تصحيح أخطاء التراكبات

لتمكين التراكبات وتعطيلها وتفريغها يدويًا، استخدم التراكب التالي مدير المشروعات.

adb shell cmd overlay

يتم استخدام idmap2 من قِبل OverlayManagerService لربط أرقام تعريف الموارد في الهدف. إلى معرفات الموارد في حزمة التراكب. عمليات تعيين المعرفات التي تم إنشاؤها هي تم تخزين البيانات في /data/resource-cache/. إذا كان التراكب لا يعمل بشكل صحيح، فابحث عن ملف idmap المقابل للتراكب في /data/resource-cache/، ثم قم بتشغيل الأمر التالي.

adb shell idmap2 dump --idmap-path [file]

يؤدي هذا الأمر إلى طباعة تعيين الموارد كما هو موضح أدناه.

[target res id] - > [overlay res id] [resource name]
0x01040151 -> 0x01050001 string/config_dozeComponent
0x01040152 -> 0x01050002 string/config_dozeDoubleTapSensorType
0x01040153 -> 0x01050003 string/config_dozeLongPressSensorType