A partire dal 27 marzo 2025, ti consigliamo di utilizzare android-latest-release anziché aosp-main per compilare e contribuire ad AOSP. Per ulteriori informazioni, vedi Modifiche ad AOSP.

Questa pagina è stata tradotta dall'API Cloud Translation.

Modifica il valore delle risorse di un'app in fase di runtime
Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Un overlay delle risorse di runtime (RRO) è un pacchetto che modifica i valori delle risorse di un pacchetto di destinazione in fase di runtime. Ad esempio, un'app installata sull'immagine di sistema potrebbe cambiare il proprio comportamento in base al valore di una risorsa. Anziché hardcode il valore della risorsa in fase di compilazione, un RRO installato su una partizione diversa può modificare i valori delle risorse dell'app in fase di esecuzione.

Gli RRO possono essere attivati o disattivati. Puoi impostare programmaticamente lo stato attivo/disattivato per attivare/disattivare la possibilità di un RRO di modificare i valori delle risorse. I RRO sono disattivati per impostazione predefinita (tuttavia, i RRO statici sono attivati per impostazione predefinita).

Risorse in overlay

I livelli sovrapposti funzionano mappando le risorse definite nel pacchetto overlay alle risorse definite nel pacchetto di destinazione. Quando un'app tenta di risolvere il valore di una risorsa nel pacchetto di destinazione, viene restituito il valore della risorsa overlay a cui è mappata la risorsa di destinazione.

Configurare il manifest

Un pacchetto è considerato un pacchetto RRO se contiene un tag <overlay> come elemento figlio del tag <manifest>.

Il valore dell'attributo obbligatorio android:targetPackage specifica il nome del pacchetto che l'RRO intende sovrapporre.
Il valore dell'attributo facoltativo android:targetName specifica il nome del sottoinsieme di risorse sovrapponibile del pacchetto di destinazione che l'RRO intende sovrapporre. Se la destinazione non definisce un insieme di risorse sovrapponibile, questo attributo non deve essere presente.

Il seguente codice mostra un overlay AndroidManifest.xml di esempio.

<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>

Gli overlay non possono sovrapporre il codice, pertanto non possono avere file DEX. Inoltre, l'attributo android:hasCode del tag <application> nel file manifest deve essere impostato su false.

Definisci la mappa delle risorse

In Android 11 o versioni successive, il meccanismo consigliato per definire la mappa delle risorse in overlay è creare un file nella directory res/xml del pacchetto in overlay, enumerare le risorse di destinazione che devono essere sovrapposte e i relativi valori di sostituzione, quindi impostare il valore dell'attributo android:resourcesMap del tag manifest <overlay> su un riferimento al file di mappatura delle risorse.

Il seguente codice mostra un file res/xml/overlays.xml di esempio.

<?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>

Il seguente codice mostra un manifest overlay di esempio.

<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>

Crea il pacchetto

Android 11 o versioni successive supporta una regola di compilazione Soong per gli overlay che impedisce ad Android Asset Packaging Tool 2 (AAPT2) di tentare di eliminare le duplicazioni delle configurazioni delle risorse con lo stesso valore (--no-resource-deduping) e di rimuovere le risorse senza configurazioni predefinite (--no-resource-removal). Il codice seguente mostra un esempio di file Android.bp.

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

Risolvi le risorse

Se una risorsa di destinazione o una risorsa in overlay ha più configurazioni definite per la risorsa su cui viene eseguita la query, il runtime delle risorse restituisce il valore della configurazione che corrisponde meglio alla configurazione del dispositivo. Per determinare quale configurazione è la migliore, unisci l'insieme delle configurazioni delle risorse in overlay all'insieme delle configurazioni delle risorse di destinazione e poi segui il normale flusso di risoluzione delle risorse (per maggiori dettagli, consulta In che modo Android trova la risorsa più adatta).

Ad esempio, se un overlay definisce un valore per la configurazione drawable-en e il target definisce un valore per drawable-en-port, drawable-en-port ha una corrispondenza migliore, pertanto il valore della configurazione target drawable-en-port viene scelto in fase di runtime. Per sovrapporre tutte le configurazioni drawable-en, l'overlay deve definire un valore per ogni configurazione drawable-en definita dal target.

Gli overlay possono fare riferimento alle proprie risorse, con comportamenti diversi tra le release di Android.

In Android 11 o versioni successive, ogni overlay ha il proprio spazio ID risorsa riservato che non si sovrappone allo spazio ID risorsa di destinazione o ad altri spazi ID risorsa degli overlay, pertanto gli overlay che fanno riferimento alle proprie risorse funzionano come previsto.
In Android 10 o versioni precedenti, gli overlay e i pacchetti di destinazione condividono lo stesso spazio ID risorsa, il che può causare collisioni e comportamenti imprevisti quando tentano di fare riferimento alle proprie risorse utilizzando la sintassi @type/name.

Attivare/disattivare gli overlay

Gli overlay possono essere attivati/disattivati manualmente e tramite programmazione.

Disattivare o attivare manualmente gli overlay

Per attivare e verificare manualmente un RRO, esegui:

adb shell cmd overlay enable --user current com.example.carrro
adb shell cmd overlay list --user current | grep -i com.example com.example.carrro

In questo modo viene attivato il RRO per l'utente di sistema (userId = 0) proprietario di SystemUI. Questa istruzione non influisce sulle app avviate dall'utente in primo piano (userId = 10). Per attivare l'RRO per l'utente in primo piano, utilizza il parametro -–user 10:

adb shell cmd overlay enable --user 10 com.example.carrro

Attivare o disattivare gli overlay in modo programmatico

Utilizza l'API OverlayManager per attivare e disattivare gli overlay mutabili (recupera l'interfaccia dell'API utilizzando Context#getSystemService(Context.OVERLAY_SERVICE)). Un overlay può essere attivato solo dal pacchetto di destinazione o da un pacchetto con l'android.permission.CHANGE_OVERLAY_PACKAGES. Quando un overlay viene attivato o disattivato, gli eventi di modifica della configurazione vengono propagati al pacchetto di destinazione e le attività di destinazione vengono riavviate.

Limitare le risorse sovrapponibili

In Android 10 o versioni successive, il tag XML <overlayable> espone un insieme di risorse che gli RRO possono sovrapporre. Nell'esempio seguente, il file res/values/overlayable.xml, string/foo e integer/bar sono risorse utilizzate per impostare il tema dell'aspetto del dispositivo. Per sovrapporre queste risorse, un overlay deve avere come target esplicito la raccolta di risorse sovrapponibili per nome.

<!-- 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>

Un APK può definire più tag <overlayable>, ma ogni tag deve avere un nome univoco all'interno del pacchetto. Ad esempio:

È consentito che due pacchetti diversi definiscano entrambi <overlayable name="foo">.
Non è consentito che un singolo APK abbia due blocchi <overlayable name="foo">.

Il seguente codice mostra un esempio di overlay nel file 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>

Quando un'app definisce un tag <overlayable>, vengono sovrapposti i targeting per quell'app:

Deve essere specificato targetName.
Può sovrapporre solo le risorse elencate all'interno del tag <overlayable>.
Può avere come target un solo nome <overlayable>.

Non puoi attivare un overlay che ha come target un pacchetto che espone risorse sovrapponibili, ma non utilizza android:targetName per scegliere come target un tag <overlayable> specifico.

Limita i criteri

Utilizza il tag <policy> per applicare limitazioni alle risorse sovrapposte. L'attributo type specifica i criteri che un overlay deve soddisfare per eseguire l'override delle risorse incluse. I tipi supportati includono quanto segue.

public. Qualsiasi overlay può sostituire la risorsa.
system. Qualsiasi overlay sulla partizione di sistema può sostituire le risorse.
vendor. Qualsiasi overlay sulla partizione del fornitore può eseguire l'override delle risorse.
product. Qualsiasi overlay sulla partizione del prodotto può sostituire le risorse.
oem. Qualsiasi overlay sulla partizione OEM può sostituire le risorse.
odm. Qualsiasi overlay sulla partizione ODM può sostituire le risorse.
signature. Qualsiasi overlay firmato con la stessa firma dell'APK di destinazione può eseguire l'override delle risorse.
actor. Qualsiasi overlay firmato con la stessa firma dell'APK attore può eseguire l'override delle risorse. L'attore viene dichiarato nel tag named-actor in system config.
config_signature. Qualsiasi overlay firmato con la stessa firma dell'APK overlay-config può sostituire le risorse. La configurazione dell'overlay è dichiarata nel tag overlay-config-signature nella configurazione di sistema.

Il seguente codice mostra un esempio di tag <policy> nel res/values/overlayable.xml file.

<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>

Per specificare più criteri, utilizza le barre verticali (|) come caratteri separatori. Quando sono specificati più criteri, un overlay deve soddisfare solo un criterio per sostituire le risorse elencate nel tag <policy>.

Configurare gli overlay

Android supporta diversi meccanismi per configurare la mutabilità, lo stato predefinito e la priorità degli overlay a seconda della versione della release di Android.

I dispositivi con Android 11 o versioni successive possono utilizzare un file OverlayConfig (config.xml) anziché gli attributi manifest. L'utilizzo di un file di overlay è il metodo consigliato per gli overlay.
Tutti i dispositivi possono utilizzare gli attributi manifest (android:isStatic e android:priority) per configurare RRO statici.

Utilizzare OverlayConfig

In Android 11 o versioni successive, puoi usare OverlayConfig per configurare la mutabilità, lo stato predefinito e la priorità degli overlay. Per configurare un overlay, crea o modifica il file situato in partition/overlay/config/config.xml, dove partition è la partizione dell'overlay da configurare. Per essere configurato, un overlay deve trovarsi nella directoryoverlay/ della partizione in cui è configurato. Il seguente codice mostra un esempio di 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>"

Il tag <overlay> richiede un attributo package che indichi il pacchetto di overlay in fase di configurazione. L'attributo facoltativo enabled controlla se l'overlay è abilitato o meno per impostazione predefinita (il valore predefinito è false). L'attributo facoltativo mutable controlla se l'overlay è mutabile o meno e se il suo stato attivo può essere modificato tramite programmazione in fase di esecuzione (il valore predefinito è true). Gli overlay non elencati in un file di configurazione sono mutabili e disattivati per impostazione predefinita.

Priorità dell'overlay

Quando più overlay sostituiscono le stesse risorse, l'ordine degli overlay è importante. Un overlay ha la precedenza sugli overlay con configurazioni precedenti alla propria configurazione. L'ordine di precedenza degli overlay in diverse partizioni (dalla precedenza minima alla massima) è il seguente.

system
vendor
odm
oem
product
system_ext

Unisci file

L'utilizzo dei tag <merge> consente di unire altri file di configurazione nella posizione specificata nel file di configurazione. L'attributo path del tag rappresenta il percorso del file da unire rispetto alla directory contenente i file di configurazione dell'overlay.

Utilizza gli attributi manifest/RRO statici

In Android 10 o versioni precedenti, l'immutabilità e la precedenza dell'overlay vengono configurate utilizzando i seguenti attributi manifest.

android:isStatic. Quando il valore di questo attributo booleano è impostato su true, l'overlay è abilitato per impostazione predefinita ed è immutabile, il che impedisce la sua disabilitazione.
android:priority. Il valore di questo attributo numerico (che influisce solo sugli overlay statici) configura la precedenza dell'overlay quando più overlay statici hanno come target lo stesso valore della risorsa. Un numero più alto indica una priorità maggiore.

Il seguente codice mostra un esempio 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>

Modifiche in Android 11

In Android 11 o versioni successive, se un file di configurazione si trova in partition/overlay/config/config.xml, gli overlay vengono configurati utilizzando quel file e android:isStatic e android:priority non influiscono sugli overlay nella partizione. La definizione di un file di configurazione dell'overlay in qualsiasi partizione impone la precedenza della partizione dell'overlay.

Inoltre, Android 11 o versioni successive rimuove la possibilità di utilizzare overlay statici per modificare i valori delle risorse lette durante l'installazione del pacchetto. Per il caso d'uso comune di utilizzare overlay statici per modificare il valore dei valori booleani che configurano lo stato di attivazione del componente, utilizza il tag <component-override> SystemConfig (novità in Android 11).

Overlay di debug

Per attivare, disattivare e scaricare manualmente gli overlay, utilizza il seguente comando della shell di overlay manager.

adb shell cmd overlay

L'utilizzo di enable senza specificare un utente interessa l'utente corrente, ovvero l'utente di sistema (userId = 0), proprietario dell'interfaccia utente di sistema. Ciò non influisce sull'utente in primo piano (userId = 10), proprietario delle app. Per attivare l'RRO per l'utente in primo piano, utilizza il parametro –-user 10:

adb shell cmd overlay enable --user 10 com.example.carrro

OverlayManagerService utilizza idmap2 per mappare gli ID risorsa nel package di destinazione agli ID risorsa nel package overlay. Le mappature degli ID generate vengono memorizzate in /data/resource-cache/. Se l'overlay non funziona correttamente, individua il file idmap corrispondente in /data/resource-cache/, quindi esegui il seguente comando.

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

Questo comando stampa la mappatura delle risorse come mostrato di seguito.

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