เปลี่ยนค่าของทรัพยากรของแอพเมื่อรันไทม์

การ ซ้อนทับทรัพยากรรันไทม์ (RRO) เป็นแพ็คเกจที่เปลี่ยนค่าทรัพยากรของแพ็คเกจเป้าหมายที่รันไทม์ ตัวอย่างเช่น แอพที่ติดตั้งบนอิมเมจระบบอาจเปลี่ยนลักษณะการทำงานตามมูลค่าของทรัพยากร แทนที่จะฮาร์ดโค้ดค่าทรัพยากรในขณะสร้าง RRO ที่ติดตั้งบนพาร์ติชันอื่นสามารถเปลี่ยนค่าทรัพยากรของแอปในขณะรันไทม์ได้

RRO สามารถเปิดใช้งานหรือปิดใช้งานได้ คุณสามารถตั้งค่าสถานะเปิด/ปิดโดยทางโปรแกรมเพื่อสลับความสามารถของ RRO ในการเปลี่ยนแปลงค่าทรัพยากร 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 > ในไฟล์ Manifest เป็น 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>

สร้างแพ็คเกจ

Android 11 ขึ้นไปรองรับกฎการสร้าง Soong สำหรับการซ้อนทับที่ป้องกันไม่ให้ 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 ขึ้นไป การซ้อนทับแต่ละรายการจะมีพื้นที่ ID ทรัพยากรที่สงวนไว้ของตัวเองซึ่งไม่ทับซ้อนพื้นที่ ID ทรัพยากรเป้าหมายหรือพื้นที่ ID ทรัพยากรที่ซ้อนทับอื่นๆ ดังนั้นการซ้อนทับที่อ้างอิงทรัพยากรของตนเองจะทำงานตามที่คาดไว้

• ใน Android 10 หรือต่ำกว่า การซ้อนทับและแพ็กเกจเป้าหมายจะใช้พื้นที่รหัสทรัพยากรเดียวกัน ซึ่งอาจทำให้เกิดการชนกันและพฤติกรรมที่ไม่คาดคิดเมื่อพยายามอ้างอิงทรัพยากรของตนเองโดยใช้ไวยากรณ์ @type/name

การเปิด/ปิดการซ้อนทับ

ใช้ OverlayManager API เพื่อเปิดใช้งานและปิดใช้งานการซ้อนทับที่ไม่แน่นอน (เรียกอินเทอร์เฟซ API โดยใช้ Context#getSystemService(Context.OVERLAY_SERVICE) ) การซ้อนทับสามารถเปิดใช้งานโดยแพ็คเกจที่เป็นเป้าหมายหรือโดยแพ็คเกจที่มีสิทธิ์ android.permission.CHANGE_OVERLAY_PACKAGES เท่านั้น เมื่อเปิดใช้งานหรือปิดใช้งานโอเวอร์เลย์ เหตุการณ์การเปลี่ยนแปลงการกำหนดค่าจะเผยแพร่ไปยังแพ็คเกจเป้าหมายและเปิดกิจกรรมเป้าหมายอีกครั้ง

การจำกัดทรัพยากรที่ซ้อนทับได้

ใน Android 10 ขึ้นไป แท็ก <overlayable> XML เปิดเผยชุดของทรัพยากรที่ RRO ได้รับอนุญาตให้ซ้อนทับ ในไฟล์ 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 การซ้อนทับใด ๆ บนพาร์ติชัน oem สามารถแทนที่ทรัพยากรได้
• odm การซ้อนทับใดๆ บนพาร์ติชัน odm สามารถแทนที่ทรัพยากรได้
• signature การวางซ้อนใดๆ ที่ลงชื่อด้วยลายเซ็นเดียวกันกับ APK เป้าหมายสามารถลบล้างทรัพยากรได้
• actor การซ้อนทับใดๆ ที่ลงนามด้วยลายเซ็นเดียวกับ APK ของ นักแสดง สามารถลบล้างทรัพยากรได้ นักแสดงถูกประกาศในแท็ก ชื่อนักแสดง ในการกำหนดค่าระบบ
• config_signature การวางซ้อนใด ๆ ที่ลงนามด้วยลายเซ็นเดียวกันกับ apk overlay-config สามารถแทนที่ทรัพยากรได้ 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 แบบคงที่

การใช้โอเวอร์เลย์คอนฟิก

ใน Android 11 ขึ้นไป คุณสามารถใช้ 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 เลย์/config/config.xml โอเวอร์เลย์จะได้รับการกำหนดค่าโดยใช้ไฟล์นั้น และ android:isStatic และ android:priority จะไม่มีผลกับโอเวอร์เลย์ที่อยู่ในพาร์ติชัน การกำหนดไฟล์คอนฟิกูเรชันโอเวอร์เลย์ในพาร์ติชั่นใดๆ

นอกจากนี้ Android 11 หรือสูงกว่าจะลบความสามารถในการใช้การซ้อนทับแบบคงที่เพื่อส่งผลต่อค่าของทรัพยากรที่อ่านระหว่างการติดตั้งแพ็คเกจ สำหรับกรณีการใช้งานทั่วไปของการใช้สแตติกโอเวอร์เลย์เพื่อเปลี่ยนค่าบูลีนที่กำหนดค่าสถานะเปิดใช้งานคอมโพเนนต์ ให้ใช้แท็ก <component-override> SystemConfig (ใหม่ใน Android 11)

การดีบักการซ้อนทับ

หากต้องการเปิดใช้งาน ปิดใช้งาน และดัมพ์โอเวอร์เลย์ด้วยตนเอง ให้ใช้คำสั่งเชลล์ตัวจัดการโอเวอร์เลย์ต่อไปนี้

adb shell cmd overlay

OverlayManagerService ใช้ idmap2 เพื่อแมป ID ทรัพยากรในแพ็คเกจเป้าหมายกับ ID ทรัพยากรในแพ็คเกจโอเวอร์เลย์ การแมป ID ที่สร้างขึ้นจะถูกเก็บไว้ใน /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