Come assegnare nomi alle risorse con i qualificatori (HTML)

Articolo
01/28/2016

[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]

Puoi assegnare nomi alle risorse usando i qualificatori. I qualificatori identificano il contesto in cui deve essere usata una versione di una risorsa.

Qualificatori di risorse

Puoi personalizzare le risorse di tipo file e stringa per supportare più proporzioni di visualizzazione, lingue dell'interfaccia utente, impostazioni di contrasto elevato e altro. I qualificatori di risorse sono modificatori di cartelle e nomi di file che identificano il contesto in cui deve essere usata una versione di una risorsa.

la convenzione di denominazione standard è

foldername/qualifiername-value_qualifiername-value/filename.qualifiername-value_qualifiername-value.ext

Ad esempio,

Images/en-US/homeregion-USA/logo.scale-100_contrast-white.png

viene caricata facendo riferimento a

Images/logo.png

Nota Ti consigliamo di contrassegnare la lingua predefinita nei file di risorse stringa (ad esempio en-US\resources.resw) e la scala predefinita nelle immagini (ad esempio logo.scale-100.png), anche se questi file non verranno localizzati né verranno fornite immagini con più risoluzioni.

Interi nomi di cartelle vengono analizzati in funzione dei qualificatori e devono corrispondere a un set di qualificatori o vengono considerati parte del percorso di file logico. Il segmento tratteggiato nel file subito prima dell'estensione di file viene considerato un token che indica i qualificatori. Più qualificatori sono separati da un carattere di sottolineatura e i qualificatori sono in genere specificati dal nome e dal valore (eccetto la lingua quando viene usata in un nome cartella).

Gli sviluppatori di app possono scegliere di usare nomi di file o di cartelle per specificare le risorse per un determinato set di contesti o usare un insieme delle due strategie, a seconda del loro flusso di lavoro e delle esigenze dell'app.

La risorsa corretta viene scelta automaticamente in fase di esecuzione in base al qualificatore di ogni risorsa e al contesto corrente. Puoi fornire ad esempio le seguenti risorse:

en-us\logo.scale-100.png
en-us\logo.scale-140.png
fr-fr\logo.scale-100.png
fr-fr\logo.scale-140.png

Un utente che preferisce la lingua Inglese (Stati Uniti) su uno schermo con una scala impostata su 140 vedrà quindi l'immagine en-us\logo.scale-140.png. Per informazioni sulla scelta delle risorse in scenari di fallback più complessi, vedi l'argomento relativo al contesto di risorse.

Le sezioni rimanenti di questo argomento descrivono il set di qualificatori e i possibili valori per ogni dimensione supportata dall'infrastruttura di risorse.

Importante I formati qui descritti sono per il segmento qualificatore di un nome file (o del nome cartella nel caso delle lingue). I qualificatori dovrebbero apparire tutti come segmento nel nome file completo dopo il nome della risorsa e prima dell'estensione di file, come in questo formato usato per lo più per i segnaposto: name**.qualifiers.**ext I punti (.) qui sono importanti perché forniscono il separatore a livello di sintassi tra i segmenti. Non puoi usare un carattere punto se non in uno dei formati del qualificatore.

Lingua (app)

Il qualificatore della lingua specifica la lingua BCP-47 della risorsa. I nomi di file richiedono il qualificatore lang o language insieme al tag della lingua, ma le cartelle richiedono solo il tag della lingua. Per l'elenco delle lingue, vedi Registro IANA dei sottocodici di lingua.

Formati di nomi di cartelle:

<Any BCP-47 language tag>
lang-<Any BCP-47 language tag>
language-<Any BCP-47 language tag>

Formati di nomi di file:

lang-<Any BCP-47 language tag>
language-<Any BCP-47 language tag>

Esempi:

es-MX/resources.resw
language-de-DE/UI.resw
images/logo.lang-fr-FR.png

Il qualificatore della lingua viene confrontato con l'elenco di lingue dell'app. Le modifiche alla lingua dell'app in fase di esecuzione vengono propagate come eventi (vedi ResourceContext.QualifierValues). Un'app non deve impostare o eseguire l'override della lingua.

Scala

Il qualificatore della scala specifica il fattore di scala della risorsa. Viene in genere usato per le immagini visualizzate su un dispositivo con DPI superiore o quando l'app viene ingrandita. La scala di una risorsa corrisponde al valore di Windows.Graphics.Display.DisplayProperties.ResolutionScale o della successiva risorsa in scala più grande. Se usi il qualificatore della scala su una risorsa, non dovresti usare il qualificatore targetsize.

Qualificatori della scala:

scale-80 (valido solo per le risorse specificate nel manifesto dell'app)
scale-100
scale-140
scale-180 (Windows)
scale-240 (Windows Phone)

Le modifiche alla scala in fase di esecuzione vengono propagate come eventi (vedi ResourceContext.QualifierValues).

Contrasto

Il qualificatore del contrasto specifica l'impostazione del tema del contrasto del sistema. Standard viene usato quando tutti i temi a contrasto elevato sono disattivati. High è valido in qualsiasi modalità di contrasto elevato. Black indica quando sono preferite le immagini con sfondo nero e colore di primo piano bianco. White indica quando sono preferite le immagini con sfondo bianco e colore di primo piano nero. Le impostazioni del tema High Contrast #1 e High Contrast #2 corrispondono al valore del qualificatore Black.

contrast-standard
contrast-high
contrast-black
contrast-white

Area di residenza

Il qualificatore dell'area di residenza rappresenta la località di residenza dell'utente. Viene in genere specificato durante l'installazione di Windows ed è accessibile dal Pannello di controllo. Il qualificatore (ResourceContext.QualifierValues) viene solitamente ignorato se per la località è noto un altro provider di dati. Il valore può essere qualsiasi tag di area BCP-47 valido, ovvero qualsiasi codice area geografica di due lettere iso-3166-1 alpha 2, più il set di codici geografici di tre cifre iso-3166-1 numerico per le aree composite (vedi il documento relativo alla composizione di codici di area geografica M49 della Divisione Statistica delle Nazioni Unite). Nota che i codici per i "raggruppamenti selezionati economici e di altro tipo" non sono validi.

Formato dell'area di residenza:

homeregion-<Region Code>

Esempi:

homeregion-us
homeregion-jp
homeregion-419

Il qualificatore dell'area di residenza corrisponde a qualsiasi regione composta principale.

Dimensione delle destinazioni

Il qualificatore targetsize può specificare risorse di una particolare dimensione (in pixel). Viene usato soprattutto per specificare le icone delle associazioni dei tipi di file o le icone dei protocolli visualizzate in Esplora risorse per il desktop. Questo qualificatore viene usato in genere per le immagini quadrate o le icone e specifica solo le dimensioni di una singola immagine. Il sistema o l'app che richiede la risorsa (ResourceContext.QualifierValues) deve specificare un targetsize in modo esplicito. Non esiste un valore predefinito. Se usi il qualificatore targetsize su una risorsa, non dovresti usare il qualificatore della scala.

Formato di targetsize:

targetsize-<any positive integer>

Esempi:

targetsize-16
targetsize-96

Il contesto targetsize corrisponde alla risorsa qualificato più grande.

Direzione del layout

Usa il qualificatore layout per specificare le risorse relative alla direzionalità di un ordine di lettura e un allineamento del testo specifici. Ad esempio, un'immagine potrebbe essere riflessa nel caso di una lingua da destra a sinistra come l'arabo o l'ebraico. La maggior parte delle app può usare meccanismi di capovolgimento automatico per riflettere le immagini in fase di esecuzione, tuttavia questo qualificatore è destinato ai casi in cui il semplice capovolgimento non è appropriato. Per altre informazioni, vedi Come modificare il layout per le lingue RTL e localizzare i caratteri.

Formato della direzione del layout:

layoutdir-LTR
layoutdir-RTL
layoutdir-TTBLTR
layoutdir-TTBRTL

Configurazione

Usa il qualificatore di configurazione per specificare le risorse applicabili solo a un determinato ambiente di modifica, come le risorse di solo testo. La maggior parte degli sviluppatori di app non dovrebbe prevedere di usarlo. La variabile di ambiente MS_CONFIGURATION_ATTRIBUTE_VALUE può essere impostata sul valore di stringa assegnato alle risorse rilevanti (ad esempio test).

Formato della configurazione:

config-<MS_CONFIGURATION_ATTRIBUTE_VALUE>

Esempi:

config-test
config-designer

Forma alternativa

Il qualificatore di forma alternativa può essere usato per fornire una forma alternativa di una risorsa per uno scopo speciale. Viene in genere usato solo dagli sviluppatori di app giapponesi per fornire una stringa di caratteri furigana, per la quale è riservato il valore msft-phonetic. Il sistema o l'app deve fornire un valore per usare questo qualificatore in situazioni particolari. Non esiste un valore predefinito. Non usare il prefisso msft- per i tuoi valori personalizzati.

Formato della forma alternativa:

altform-<Any string between 1 and 16 chars>

Esempi:

altform-msft-phonetic
altform-myapp-special

Livello di funzionalità DirectX

Il qualificatore Livello di funzionalità DirectX rappresenta il livello di funzionalità DirectX delle schede grafiche che verranno usate per il rendering delle risorse. Viene in genere usato per le risorse di visualizzazione Direct3D presenti nei giochi. Il livello di funzionalità DirectX di una risorsa corrisponde a un valore impostato esplicitamente in un contesto di risorsa dall'app. Se non è disponibile una risorsa con un livello di funzionalità DirectX esattamente uguale al valore specificato, verrà usata la risorsa con il valore inferiore più vicino.

Nota Il qualificatore del livello della funzionalità DirectX è supportato a partire da Windows 8.1.

Per tale qualificatore sono disponibili due formati. I valori supportati sono DX9, DX10 e DX11.

Formato del livello di funzionalità DirectX

DXFeatureLevel-<value>
DXFL-<value>

Esempi:

DXFeatureLevel-DX10
DXFL-DX11

Osservazioni

Come accennato in precedenza, è possibile combinare qualsiasi formato del set di qualificatori se c'è bisogno di supportare più modelli di qualificatore per lo stesso scenario di risorse. Il separatore da usare tra i modelli di qualificatore è il carattere di sottolineatura (_). Ecco ad esempio un percorso di un file di risorse che supporta direzione di configurazione, scala e layout in modo esplicito: logo.config-test_scale-100_layoutdir-LTR.png