Compartir a través de

Adapta tus recursos para el idioma, la escala, el alto contraste y otros atributos

En este tema se explica el concepto general de calificadores de recursos, cómo usarlos y el propósito de cada uno de los nombres de calificador. Consulte ResourceContext.QualifierValues para obtener una tabla de referencia de todos los valores de calificador posibles.

Su aplicación puede cargar activos y recursos adaptados a los contextos en tiempo de ejecución, como el lenguaje de visualización, contraste alto, factor de escala de visualización, y muchos otros. La forma de hacerlo es asignar un nombre a las carpetas o archivos de los recursos para que coincidan con los nombres de calificador y los valores de calificador que corresponden a esos contextos. Por ejemplo, puede que quieras que la aplicación cargue un conjunto diferente de recursos de imagen en modo de contraste alto.

Para obtener más información sobre el valor de localizar tu app, consulta Globalización y localización.

Nombre del calificador, el valor del calificador y el calificador

Un nombre de calificador es una clave que se asocia con un conjunto de valores de calificador. Aquí están el nombre del calificador y los valores del calificador para el contraste.

Contexto Nombre del calificador Valores de clasificador
Configuración de contraste alto contraste estándar, alto, negro, blanco

Unes un nombre de calificador con un valor de calificador para formar un calificador. <qualifier name>-<qualifier value> es el formato de un calificador. contrast-standard es un ejemplo de cualificador.

Así que, para contraste alto, el conjunto de calificadores es contrast-standard, contrast-high, contrast-blacky contrast-white. Los nombres de calificador y los valores de calificador no distinguen entre mayúsculas y minúsculas. Por ejemplo, contrast-standard y Contrast-Standard son el mismo calificativo.

Usa calificadores en nombres de carpeta

Este es un ejemplo de uso de calificadores para asignar nombres a carpetas que contienen archivos de recursos. Usa calificadores en los nombres de las carpetas si tiene varios archivos de recursos por calificador. De este modo, se establece el calificador una vez en el nivel de carpeta y el calificador se aplica a todo lo que hay dentro de la carpeta.

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

Si asigna un nombre a las carpetas como en el ejemplo anterior, la aplicación usa la configuración de contraste alto para cargar archivos de recursos de la carpeta denominada para el calificador adecuado. Por lo tanto, si la configuración es Negro de contraste alto, los archivos de recursos de la \Assets\Images\contrast-black carpeta se cargan. Si la configuración es None (es decir, el equipo no está en modo de contraste alto), los archivos de recursos de la \Assets\Images\contrast-standard carpeta se cargan.

Use calificadores en nombres de archivo

En lugar de crear y asignar nombres a carpetas, puede usar un calificador para asignar un nombre a los propios archivos de recursos. Es posible que prefiera hacerlo si solo tiene un archivo de recursos por calificador. Este es un ejemplo.

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

El archivo cuyo nombre contiene el calificador más adecuado para la configuración es el que se carga. Esta lógica coincidente funciona de la misma manera para los nombres de archivo que para los nombres de carpeta.

Hacer referencia a un recurso de cadena o imagen por nombre

Consulta Referencia un identificador de recurso de cadena en el marcado XAML, referencia un identificador de recurso de cadena desde el código, y referencia una imagen u otro recurso desde el marcado XAML y el código.

Coincidencias reales y neutrales del calificador

No es necesario proporcionar un archivo de recursos para cada valor cualificador de en . Por ejemplo, si encuentra que solo necesita un recurso visual para contraste alto y otro para el contraste estándar, puede asignar un nombre a esos recursos como este.

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

El nombre del primer archivo contiene el calificador contrast-high. Ese calificador es una coincidencia de real para cualquier configuración de contraste alto cuando se contraste alto en. En otras palabras, es una coincidencia cercana, por lo que es preferible. Una coincidencia real de solo puede producirse si el calificador contiene un valor real de , como es el caso de este. En este caso, es un valor de real para .

El archivo denominado logo.png no tiene ningún calificador de contraste en él. La ausencia de un calificador es un valor neutro de. Si no se puede encontrar ninguna coincidencia preferida, el valor neutro sirve como opción de respaldo. En este ejemplo, si el contraste alto es desactivado, no hay coincidencia real. El emparejamiento neutral es el mejor que se puede encontrar y, por tanto, se carga el activo logo.png.

Si cambiaras el nombre de logo.png a logo.contrast-standard.png, el nombre de archivo contendría un valor calificativo real. Con el alto contraste desactivado, habría una coincidencia real con logo.contrast-standard.pngy ese es el archivo de activos que se cargaría. Por lo tanto, se cargarían los mismos archivos, en las mismas condiciones, pero debido a coincidencias diferentes.

Si solo necesita un conjunto de recursos para contraste alto y otro para el contraste estándar, puede usar nombres de carpeta en lugar de nombres de archivo. En este caso, omitir completamente el nombre de la carpeta te da la coincidencia neutral.

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

Para obtener más información sobre cómo funciona la coincidencia de calificadores, consulte el Sistema de Gestión de Recursos .

Varios calificadores

Puede combinar calificadores en nombres de carpeta y archivo. Por ejemplo, es posible que quieras que la aplicación cargue los recursos de imagen cuando el modo de contraste alto esté activado y el factor de escala de pantalla sea 400. Una manera de hacerlo es con una estructura de carpetas anidadas.

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

Para que y los demás archivos se carguen, la configuración debe coincidir con ambos calificadores de .

Otra opción es combinar varios calificadores en un nombre de carpeta.

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

En un nombre de carpeta, se combinan varios calificadores separados con un carácter de subrayado. <qualifier1>[_<qualifier2>...] es el formato.

Puede combinar varios calificadores en un nombre de archivo con el mismo formato.

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

Dependiendo de las herramientas y el flujo de trabajo que utilice para la creación de recursos, o en función de lo que le resulte más fácil de leer o gestionar, puede elegir una única estrategia de nomenclatura para todos los calificadores, o puede combinarlos para distintos calificadores.

Forma Alternativa

El alternateform calificador se usa para proporcionar una forma alternativa de un recurso para algún propósito especial. Normalmente, esto solo lo usan los desarrolladores de aplicaciones japoneses para proporcionar una cadena de furigana para la que se reserva el valor msft-phonetic (consulte la sección "Compatibilidad con Furigana para cadenas japonesas que se pueden ordenar" en Cómo prepararse para la localización).

El sistema de destino o la aplicación deben proporcionar un valor contra el cual se comparen los calificadores alternateform. No utilice el prefijo msft- para sus propios valores personalizados del calificador alternateform.

Configuración

Es poco probable que necesites el nombre del calificador configuration. Se puede usar para especificar recursos que solo son aplicables a un entorno durante la fase de autoría, como los recursos utilizados solo para pruebas.

El configuration calificador se usa para cargar un recurso que mejor coincida con el valor de la MS_CONFIGURATION_ATTRIBUTE_VALUE variable de entorno. Por lo tanto, puede establecer la variable en el valor de cadena que se ha asignado a los recursos pertinentes, por ejemplo designer, o test.

Contraste

El contrast calificador se usa para proporcionar recursos que mejor coincidan con la configuración de contraste alto.

Personalizado

La aplicación puede establecer un valor para el calificador de custom y, a continuación, se cargan los recursos que mejor se ajusten a ese valor. Por ejemplo, puede que quiera cargar recursos en función de la licencia de la aplicación. Cuando se inicia la aplicación, comprueba su licencia y la usa como valor para el custom calificador mediante una llamada a SetGlobalQualifierValue, como se muestra en el ejemplo de código.

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);
    }
}

En este escenario, darías a tus recursos nombres que incluyan los calificadores custom-premium, custom-standardy custom-trial.

Familia de Dispositivos

Es poco probable que necesites el nombre del calificador devicefamily. Puede y debe evitar usarlo siempre que sea posible porque hay técnicas que puede usar en su lugar que son mucho más cómodas y sólidas. Estas técnicas se describen en Detección de la plataforma en la que se ejecuta la aplicación y código adaptable de versión.

Pero como último recurso, es posible usar calificadores devicefamily para asignar nombres a las carpetas que contienen las vistas XAML (una vista XAML es un archivo XAML que contiene el diseño y los controles de la interfaz de usuario).

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

O bien, puede asignar un nombre a los archivos.

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

En cualquier caso, cada copia de MainPage.[<qualifier>].xaml comparte el mismo MainPage.xaml.cs, que permanece sin cambios en tu proyecto en términos de nombre, ubicación y contenido.

También puede usar un calificador devicefamily para asignar un nombre a un archivo de recursos (.resw) o una carpeta. Por ejemplo, cuando tu aplicación se ejecuta en la familia de dispositivos móviles, el elemento UI <TextBlock x:Uid="DeviceFriendlyName"/> usará el texto y los recursos de primer plano definidos en tu archivo Resources.devicefamily-mobile.resw si este los contiene.

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

Para obtener más información sobre el uso de un archivo de recursos, consulte Localización de las cadenas de interfaz de usuario.

DXFeatureLevel

Es poco probable que necesites el nombre del calificador dxfeaturelevel. Se diseñó para usarse con recursos de juego de Direct3D, de modo que los recursos de nivel inferior se cargaran para coincidir con una configuración de hardware de nivel inferior específica de aquella época. Pero la prevalencia de esa configuración de hardware es ahora tan baja que se recomienda no usar este calificador.

Región de origen

El homeregion calificador corresponde a la configuración del usuario para el país o región. Representa la ubicación principal del usuario. Los valores incluyen cualquier etiqueta de región de BCP-47 válida. Es decir, cualquier código de región ISO 3166-1 alfa-2 de dos letras, además del conjunto de códigos geográficos ISO 3166-1 numéricos de tres dígitos para regiones compuestas (véase la composición de la División Estadística de las Naciones Unidas M49 de códigos de región). Los códigos para "Selecciones económicas y otras agrupaciones" no son válidos.

Lenguaje

Un calificador language corresponde a la configuración de idioma de visualización. Los valores incluyen cualquier etiqueta de idioma válida BCP-47 . Para obtener una lista de idiomas, consulte el registro de subtag del idioma IANA.

Si quieres que tu aplicación admita diferentes lenguajes de visualización y tienes literales de cadena en el código o en el marcado XAML, mueve esas cadenas fuera del código o marcado y a un archivo de recursos (.resw). A continuación, puedes realizar una copia traducida de ese archivo de recursos para cada idioma que admita la aplicación.

Normalmente, utilizas un language calificador para nombrar las carpetas que contienen tus archivos de recursos (.resw).

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

Puede omitir la parte language- de un calificador language (es decir, el nombre del calificador). No puedes hacerlo con los otros tipos de calificadores. Solo puedes hacerlo en un nombre de carpeta.

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

En lugar de asignar nombres a carpetas, puede usar etiquetas language para nombrar los archivos de recursos.

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

Consulte Localizar las cadenas de interfaz de usuario para obtener más información sobre cómo hacer que la aplicación sea localizable mediante recursos de cadena y cómo hacer referencia a un recurso de cadena en la aplicación.

Dirección de maquetación

Un calificador layoutdirection corresponde a la dirección de disposición de la configuración del idioma de la pantalla. Por ejemplo, es posible que una imagen tenga que reflejarse para un idioma de derecha a izquierda, como árabe o hebreo. Los paneles de diseño y las imágenes de la interfaz de usuario responderán adecuadamente a la dirección del diseño si establece su propiedad FlowDirection (ver Ajustar diseño y fuentes, y soporte RTL). Sin embargo, el calificador de layoutdirection es para los casos en los que el cambio simple no es adecuado y permite responder a la direccionalidad de un orden de lectura y una alineación de texto específicos de maneras más generales.

Escala

Windows selecciona automáticamente un factor de escala para cada pantalla en función de su PPP (puntos por pulgada) y la distancia de visualización del dispositivo. Consulte la sección píxeles efectivos y factor de escalado. Debes crear tus imágenes con varios tamaños recomendados (al menos 100, 200 y 400) para que Windows pueda elegir el tamaño perfecto o puede usar el tamaño más cercano y escalarlo. Para que Windows pueda identificar qué archivo físico contiene el tamaño correcto de la imagen para el factor de escala de visualización, se usa un scale calificador. La escala de un recurso coincide con el valor de DisplayInformation.ResolutionScale o el siguiente recurso a mayor escala.

Este es un ejemplo de cómo establecer el calificador en el nivel de carpeta.

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

Y este ejemplo lo establece en el nivel de archivo.

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

Para obtener información sobre cómo calificar un recurso para scale y targetsize, consulte Calificar un recurso de imagen para tamaño objetivo.

Tamaño objetivo

El calificador targetsize se utiliza principalmente para especificar iconos de asociación de tipo de archivo o iconos de protocolo que se mostrarán en el Explorador de archivos. El valor del calificador representa la longitud lateral de una imagen cuadrada en píxeles en bruto (físicos). Recurso cuyo valor coincide con la configuración Ver en el Explorador de archivos se carga; o el recurso con el siguiente valor más grande en ausencia de una coincidencia exacta.

Puede definir recursos que representen varios tamaños del valor de calificador targetsize para el icono de la aplicación (/Assets/Square44x44Logo.png) en la pestaña Recursos Visuales del diseñador de manifiestos del paquete de la aplicación.

Para obtener información sobre cómo calificar un recurso para scale y targetsize, consulte Calificar un recurso de imagen para tamaño objetivo.

Tema

El calificador de theme se usa para proporcionar recursos que coincidan mejor con la configuración predeterminada del modo de aplicación o la invalidación de la aplicación mediante Application.RequestedTheme.

Tema claro de Shell y recursos no revestidos

La actualización de mayo de 2019 de Windows 10 introdujo un nuevo tema «claro» para el Shell de Windows. Como resultado, algunos recursos de aplicación que se mostraron anteriormente en un fondo oscuro ahora se mostrarán en un fondo claro. En el caso de las aplicaciones que han proporcionado recursos de formatos alternativos no estándar para la barra de tareas y los conmutadores de ventana (Alt+Tab, Vista de tareas, etc.), debe comprobar que tienen un contraste aceptable en un fondo claro.

Proporcionar recursos específicos del tema claro

Las aplicaciones que quieran proporcionar un recurso personalizado para el tema claro del shell pueden usar un nuevo cualificador de recursos alternativo: altform-lightunplated. Este calificador refleja al calificador existente llamado altform-unplated.

Consideraciones de nivel inferior

Las aplicaciones no deberían usar el calificador theme-light junto con el calificador altform-unplated. Esto provocará un comportamiento impredecible en RS5 y versiones anteriores de Windows debido a la forma en que se cargan los recursos para la barra de tareas. En versiones anteriores de las ventanas, la versión de theme-light puede usarse incorrectamente. El calificador altform-lightunplated evita este problema.

Comportamiento de compatibilidad

Para la compatibilidad con versiones anteriores, Windows incluye lógica para detectar iconos monocromáticos y comprobar si contrasta con el fondo previsto. Si el icono no cumple los requisitos de contraste, Windows buscará una versión en blanco de contraste del recurso. Si no está disponible, Windows volverá a usar la versión predeterminada del recurso.

API importantes