Personalizzare le risorse di lingua, scala, contrasto elevato e altri qualificatori

  • Articolo

Questo argomento descrive il concetto generale di qualificatori di risorse, il relativo uso e lo scopo di ognuno dei nomi qualificatori. Per una tabella di riferimento di tutti i possibili valori qualificatori, vedere ResourceContext.QualifierValues.

L'app può caricare asset e risorse personalizzate in contesti di runtime, ad esempio linguaggio di visualizzazione, contrasto elevato, fattore di scala di visualizzazione e molti altri. Il modo in cui si esegue questa operazione consiste nel assegnare un nome alle cartelle o ai file delle risorse in modo che corrispondano ai nomi dei qualificatori e ai valori qualificatori corrispondenti a tali contesti. Ad esempio, è possibile che l'app carichi un set diverso di asset di immagine in modalità a contrasto elevato.

Per altre informazioni sulla proposta di valore associata alla localizzazione dell'app, vedi Globalizzazione e localizzazione.

Nome qualificatore, valore qualificatore e qualificatore

Un nome qualificatore è una chiave che esegue il mapping a un set di valori di qualificatore. Ecco i valori di qualificatore e qualificatore per il contrasto.

Contesto Nome qualificatore Valori qualificatori
Impostazione di contrasto elevato contrasto standard, alto, nero, bianco

È possibile combinare un nome qualificatore con un valore qualificatore per formare un qualificatore. <qualifier name>-<qualifier value> è il formato di un qualificatore. contrast-standard è un esempio di qualificatore.

Pertanto, per il contrasto elevato, il set di qualificatori è contrast-standard, contrast-high, contrast-blacke contrast-white. I nomi dei qualificatori e i valori qualificatori non fanno distinzione tra maiuscole e minuscole. Ad esempio, contrast-standard e Contrast-Standard sono gli stessi qualificatori.

Usare qualificatori nei nomi delle cartelle

Di seguito è riportato un esempio di utilizzo dei qualificatori per assegnare un nome alle cartelle che contengono file di asset. Usare i qualificatori nei nomi delle cartelle se sono presenti diversi file di asset per qualificatore. In questo modo, si imposta il qualificatore una volta a livello di cartella e il qualificatore si applica a tutti gli elementi all'interno della cartella.

\Assets\Images\contrast-standard\<logo.png, and other image files>
\Assets\Images\contrast-high\<logo.png, and other image files>
\Assets\Images\contrast-black\<logo.png, and other image files>
\Assets\Images\contrast-white\<logo.png, and other image files>

Se denomina le cartelle come nell'esempio precedente, l'app usa l'impostazione a contrasto elevato per caricare i file di risorse dalla cartella denominata per il qualificatore appropriato. Pertanto, se l'impostazione è Nero a contrasto elevato, i file di risorse nella \Assets\Images\contrast-black cartella vengono caricati. Se l'impostazione è None (ovvero il computer non è in modalità a contrasto elevato), i file di risorse nella \Assets\Images\contrast-standard cartella vengono caricati.

Usare qualificatori nei nomi di file

Invece di creare e denominare cartelle, è possibile usare un qualificatore per denominare i file di risorse stessi. È consigliabile eseguire questa operazione se si dispone di un solo file di risorse per qualificatore. Ecco un esempio.

\Assets\Images\logo.contrast-standard.png
\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.contrast-black.png
\Assets\Images\logo.contrast-white.png

Il file il cui nome contiene il qualificatore più appropriato per l'impostazione è quello caricato. Questa logica di corrispondenza funziona allo stesso modo per i nomi di file come per i nomi delle cartelle.

Fare riferimento a una stringa o a una risorsa immagine in base al nome

Vedi Fare riferimento a un identificatore di risorsa stringa dal markup XAML, fare riferimento a un identificatore di risorsa stringa dal codice e fare riferimento a un'immagine o a un altro asset dal markup e dal codice XAML.

Corrispondenze effettive e neutre del qualificatore

Non è necessario specificare un file di risorse per ogni valore qualificatore. Ad esempio, se si scopre che è necessario un solo asset visivo per il contrasto elevato e uno per il contrasto standard, è possibile denominare tali asset come questo.

\Assets\Images\logo.contrast-high.png
\Assets\Images\logo.png

Il primo nome file contiene il contrast-high qualificatore. Tale qualificatore è una corrispondenza effettiva per qualsiasi impostazione a contrasto elevato quando il contrasto elevato è attivo. In altre parole, è una corrispondenza ravvicinata, quindi è preferibile. Una corrispondenza effettiva può verificarsi solo se il qualificatore contiene un valore effettivo , come in questo caso. In questo caso, high è un valore effettivo per contrast.

Il file denominato logo.png non dispone di alcun qualificatore di contrasto. L'assenza di un qualificatore è un valore neutro . Se non è possibile trovare alcuna corrispondenza preferita, il valore neutro funge da corrispondenza di fallback. In questo esempio, se il contrasto elevato è disattivato, non esiste alcuna corrispondenza effettiva. La corrispondenza neutra è la corrispondenza migliore che è possibile trovare e quindi l'asset logo.png viene caricato.

Se si desidera modificare il nome di logo.png in logo.contrast-standard.png, il nome del file conterrà un valore qualificatore effettivo. Con contrasto elevato, ci sarebbe una corrispondenza effettiva con logo.contrast-standard.pnge questo è il file di asset che verrebbe caricato. Quindi, gli stessi file verranno caricati, nelle stesse condizioni, ma a causa di corrispondenze diverse.

Se è necessario un solo set di asset per il contrasto elevato e un set per il contrasto standard, è possibile usare i nomi delle cartelle anziché i nomi di file. In questo caso, omettendo completamente il nome della cartella si ottiene la corrispondenza neutra.

\Assets\Images\contrast-high\<logo.png, and other images to load when high contrast theme is not None>
\Assets\Images\<logo.png, and other images to load when high contrast theme is None>

Per altre informazioni sul funzionamento della corrispondenza dei qualificatori, vedere Sistema di gestione risorse.

Qualificatori multipli

È possibile combinare qualificatori in nomi di file e cartelle. Ad esempio, potresti voler che l'app carichi asset immagine quando la modalità a contrasto elevato è attiva e il fattore di scala dello schermo è 400. Un modo per eseguire questa operazione consiste nell'usare cartelle nidificate.

\Assets\Images\contrast-high\scale-400\<logo.png, and other image files>

Per logo.png e gli altri file da caricare, le impostazioni devono corrispondere a entrambi i qualificatori.

Un'altra opzione consiste nel combinare più qualificatori in un nome di cartella.

\Assets\Images\contrast-high_scale-400\<logo.png, and other image files>

In un nome di cartella si combinano più qualificatori separati con un carattere di sottolineatura. Il formato è <qualifier1>[_<qualifier2>...].

È possibile combinare più qualificatori in un nome file nello stesso formato.

\Assets\Images\logo.contrast-high_scale-400.png

A seconda degli strumenti e del flusso di lavoro usati per la creazione di asset o di ciò che si trova più semplice da leggere e/o gestire, è possibile scegliere una singola strategia di denominazione per tutti i qualificatori oppure combinarli per qualificatori diversi.

AlternateForm

Il alternateform qualificatore viene usato per fornire una forma alternativa di una risorsa per uno scopo speciale. Questo viene in genere usato solo dagli sviluppatori di app giapponesi per fornire una stringa furigana per cui il valore msft-phonetic è riservato (vedere la sezione "Supporto furigana per le stringhe giapponesi che possono essere ordinate" in Come preparare la localizzazione).

Il sistema di destinazione o l'app deve fornire un valore rispetto alternateform ai qualificatori corrispondenti. Non usare il msft- prefisso per i propri valori di qualificatore personalizzati alternateform .

Impostazione

È improbabile che sia necessario il nome del configuration qualificatore. Può essere usato per specificare le risorse applicabili solo a un determinato ambiente in fase di creazione, ad esempio risorse di sola prova.

Il configuration qualificatore viene usato per caricare una risorsa che corrisponda al valore della MS_CONFIGURATION_ATTRIBUTE_VALUE variabile di ambiente. È quindi possibile impostare la variabile sul valore stringa assegnato alle risorse pertinenti, ad esempio designer, o test.

Contrasto

Il contrast qualificatore viene usato per fornire risorse che corrispondano meglio alle impostazioni di contrasto elevato.

Personalizzazione

L'app può impostare un valore per il custom qualificatore e quindi le risorse vengono caricate in base a tale valore. Ad esempio, potresti voler caricare le risorse in base alla licenza dell'app. Quando l'app viene avviata, controlla la licenza e la usa come valore per il custom qualificatore chiamando SetGlobalQualifierValue, come illustrato nell'esempio di codice.

public void SetLicenseLevel(BrandID brand)
{
    if (brand == BrandID.Premium)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Premium", ResourceQualifierPersistence.LocalMachine);
    }
    else if (brand == BrandID.Standard)
    {
        ResourceContext.SetGlobalQualifierValue("Custom", " Standard", ResourceQualifierPersistence.LocalMachine);
    }
    else
    {
        ResourceContext.SetGlobalQualifierValue("Custom", "Trial", ResourceQualifierPersistence.LocalMachine);
    }
}

In questo scenario si assegnano quindi i nomi delle risorse che includono i qualificatori custom-premium, custom-standarde custom-trial.

DeviceFamily

È improbabile che sia necessario il nome del devicefamily qualificatore. È possibile evitare di usarlo quando possibile perché esistono tecniche che è possibile usare invece che sono molto più convenienti e robuste. Queste tecniche sono descritte in Rilevamento della piattaforma in cui è in esecuzione l'app e Codice adattivo versione.

Ma come ultima risorsa è possibile usare qualificatori devicefamily per denominare le cartelle che contengono le visualizzazioni XAML (una visualizzazione XAML è un file XAML che contiene layout e controlli dell'interfaccia utente).

\devicefamily-desktop\<MainPage.xaml, and other markup files to load when running on a desktop computer>
\devicefamily-mobile\<MainPage.xaml, and other markup files to load when running on a phone>

In alternativa, è possibile denominare i file.

\MainPage.devicefamily-desktop.xaml
\MainPage.devicefamily-mobile.xaml

In entrambi i casi ogni copia di MainPage.[<qualifier>].xaml condivide un comune MainPage.xaml.cs, che rimane invariato nel progetto in termini di nome, posizione e contenuto.

È anche possibile usare un qualificatore devicefamily per denominare un file di risorse (.resw) o una cartella. Ad esempio, quando l'app è in esecuzione nella famiglia di dispositivi mobili, l'elemento <TextBlock x:Uid="DeviceFriendlyName"/> dell'interfaccia utente userà il testo e le risorse in primo piano definite nel Resources.devicefamily-mobile.resw file se contiene

<data name="DeviceFriendlyName.Foreground">
    <value>Red</value>
</data>
<data name="DeviceFriendlyName.Text">
    <value>Mobile device</value>
</data>

Per altre informazioni sull'uso di un file di risorse, vedere Localizzare le stringhe dell'interfaccia utente.

DXFeatureLevel

È improbabile che sia necessario il nome del dxfeaturelevel qualificatore. È stato progettato per essere usato con asset di gioco Direct3D, per far sì che le risorse di livello inferiore vengano caricate in modo che corrispondano a una particolare configurazione hardware di livello inferiore del tempo. Ma la prevalenza della configurazione hardware è ora così bassa che è consigliabile non usare questo qualificatore.

HomeRegion

Il homeregion qualificatore corrisponde all'impostazione dell'utente per il paese o l'area geografica. Rappresenta la posizione iniziale dell'utente. I valori includono qualsiasi tag BCP-47 region. Ovvero, qualsiasi codice di area geografica ISO 3166-1 alfa-2 a due lettere, più il set di codici geografici numerici ISO 3166-1 per le aree composte (vedere Composizione M49 della Divisione statistica delle Nazioni Unite M49 dei codici di area). I codici per "Gruppi economici selezionati e altri raggruppamenti" non sono validi.

Lingua

Un language qualificatore corrisponde all'impostazione della lingua di visualizzazione. I valori includono qualsiasi tag BCP-47 language. Per un elenco delle lingue, vedere registro dei sottotag della lingua IANA.

Se desideri che la tua app supporti lingue di visualizzazione diverse e disponi di valori letterali stringa nel codice o nel markup XAML, sposta tali stringhe dal codice/markup e in un file di risorse (.resw). Puoi quindi creare una copia tradotta del file di risorse per ogni lingua supportata dall'app.

In genere si usa un language qualificatore per denominare le cartelle che contengono i file di risorse (.resw).

\Strings\language-en\Resources.resw
\Strings\language-ja\Resources.resw

È possibile omettere la language- parte di un language qualificatore (ovvero il nome del qualificatore). Non puoi farlo con gli altri tipi di qualificatori; ed è possibile farlo solo in un nome di cartella.

\Strings\en\Resources.resw
\Strings\ja\Resources.resw

Invece di denominare le cartelle, è possibile usare language qualificatori per denominare i file di risorse stessi.

\Strings\Resources.language-en.resw
\Strings\Resources.language-ja.resw

Vedi Localizzare le stringhe dell'interfaccia utente per altre informazioni su come localizzare l'app usando le risorse stringa e su come fare riferimento a una risorsa stringa nell'app.

LayoutDirection

Un layoutdirection qualificatore corrisponde alla direzione del layout dell'impostazione della lingua di visualizzazione. Ad esempio, potrebbe essere necessario eseguire il mirroring di un'immagine per una lingua da destra a sinistra, ad esempio arabo o ebraico. I pannelli di layout e le immagini nell'interfaccia utente rispondono in modo appropriato alla direzione del layout se imposti la proprietà FlowDirection (vedi Regolare layout e tipi di carattere e supportare RTL). Tuttavia, il layoutdirection qualificatore è per i casi in cui il semplice capovolgimento non è adeguato e consente di rispondere alla direzionalità di ordine di lettura e allineamento del testo specifici in modi più generali.

Ridimensiona

Windows imposta automaticamente il fattore di scala per ogni visualizzazione in base ai relativi valori DPI (punti per pollice) e alla distanza di visualizzazione del dispositivo. Vedere Pixel effettivi e fattore di scala. È consigliabile creare le immagini con diverse dimensioni consigliate (almeno 100, 200 e 400) in modo che Windows possa scegliere le dimensioni perfette o usare le dimensioni più vicine e ridimensionarla. In modo che Windows possa identificare il file fisico contenente le dimensioni corrette dell'immagine per il fattore di scala di visualizzazione, si usa un scale qualificatore. La scala di una risorsa corrisponde al valore di DisplayInformation.ResolutionScale o alla risorsa con scalabilità successiva.

Ecco un esempio di impostazione del qualificatore a livello di cartella.

\Assets\Images\scale-100\<logo.png, and other image files>
\Assets\Images\scale-200\<logo.png, and other image files>
\Assets\Images\scale-400\<logo.png, and other image files>

E questo esempio lo imposta a livello di file.

\Assets\Images\logo.scale-100.png
\Assets\Images\logo.scale-200.png
\Assets\Images\logo.scale-400.png

Per informazioni sulla qualificazione di una risorsa per e scaletargetsize, vedere Qualificare una risorsa immagine per le destinazioni.

TargetSize

Il targetsize qualificatore viene usato principalmente per specificare icone di associazione del tipo di file o icone del protocollo da visualizzare in Esplora file. Il valore del qualificatore rappresenta la lunghezza laterale di un'immagine quadrata in pixel non elaborati (fisici). La risorsa il cui valore corrisponde all'impostazione Visualizza in Esplora file viene caricata oppure la risorsa con il valore più grande successivo in assenza di una corrispondenza esatta.

È possibile definire asset che rappresentano diverse dimensioni del valore del targetsize qualificatore per l'icona dell'app (/Assets/Square44x44Logo.png) nella scheda Asset visivi della finestra di progettazione del manifesto del pacchetto dell'app.

Per informazioni sulla qualificazione di una risorsa per e scaletargetsize, vedere Qualificare una risorsa immagine per le destinazioni.

Tema

Il theme qualificatore viene usato per fornire risorse che corrispondano meglio all'impostazione predefinita della modalità app o all'override dell'app usando Application.RequestedTheme.

Tema chiaro shell e risorse senza sfondo

Il Aggiornamento di Windows 10 (maggio 2019) ha introdotto un nuovo tema "chiaro" per la shell di Windows. Di conseguenza, alcuni asset dell'applicazione visualizzati in precedenza su uno sfondo scuro verranno ora visualizzati su uno sfondo chiaro. Per le app che hanno fornito asset altform-unplated per i commutatori della barra delle applicazioni e delle finestre (ALT+TAB, Visualizzazione attività e così via), è necessario verificare che abbiano un contrasto accettabile su uno sfondo chiaro.

Fornire asset specifici del tema chiaro

Le app che vogliono fornire una risorsa personalizzata per il tema chiaro della shell possono usare un nuovo qualificatore di risorsa modulo alternativo: altform-lightunplated. Questo qualificatore rispecchia il qualificatore altform-unplated esistente.

Considerazioni di livello inferiore

Le app non devono usare il theme-light qualificatore con il altform-unplated qualificatore. Questo causerà un comportamento imprevedibile in RS5 e versioni precedenti di Windows a causa del modo in cui le risorse vengono caricate per la barra delle applicazioni. Nelle versioni precedenti di windows, la versione theme-light potrebbe essere usata in modo non corretto. Il altform-lightunplated qualificatore evita questo problema.

Comportamento di compatibilità

Per la compatibilità con le versioni precedenti, Windows include la logica per rilevare icone monocromatiche e verificare se è in contrasto con lo sfondo previsto. Se l'icona non soddisfa i requisiti di contrasto, Windows cercherà una versione bianca a contrasto dell'asset. Se non è disponibile, Windows eseguirà il fallback all'uso della versione con targhetta dell'asset.

API importanti