การ ซ้อนทับทรัพยากรรันไทม์ (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