Adaptar los recursos al idioma, escala, alto contraste y otros calificadores

  • Artículo

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

La aplicación puede cargar recursos y recursos adaptados a contextos en tiempo de ejecución, como el idioma de visualización, el contraste alto, el factor de escala de pantalla 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 más información sobre la propuesta de valor de localizar la aplicación, consulta Globalización y localización.

Nombre del calificador, valor de calificador y calificador

Un nombre de calificador es una clave que se asigna a un conjunto de valores de calificador. Estos son los valores de nombre y calificador del calificador para el contraste.

Context Nombre del calificador Valores de calificador
Configuración de contraste alto contraste standard, high, black, white

Se combina 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 calificador.

Por lo tanto, 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 mayúsculas de minúsculas. Por ejemplo, contrast-standard y Contrast-Standard son el mismo calificador.

Usar calificadores en nombres de carpeta

Este es un ejemplo del uso de calificadores para asignar nombres a carpetas que contienen archivos de recursos. Use calificadores en nombres de carpeta 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, se cargan los archivos de recursos de la \Assets\Images\contrast-black carpeta. 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.

Usar 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. A continuación se muestra 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 Hacer referencia a un identificador de recursos de cadena desde el marcado XAML, Hacer referencia a un identificador de recurso de cadena desde el código y Hacer referencia a una imagen u otro recurso del marcado y el código XAML.

Coincidencias de calificador reales y neutrales

No es necesario proporcionar un archivo de recursos para cada valor de calificador. 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 primer nombre de archivo contiene el contrast-high calificador. Ese calificador es una coincidencia real para cualquier configuración de contraste alto cuando el contraste alto está activado. En otras palabras, es una coincidencia cercana, por lo que es preferible. Una coincidencia real solo puede producirse si el calificador contiene un valor real , como hace este. En este caso, high es un valor real para contrast.

El archivo denominado logo.png no tiene ningún calificador de contraste en él. La ausencia de un calificador es un valor neutro . Si no se puede encontrar ninguna coincidencia preferida, el valor neutro sirve como coincidencia de reserva. En este ejemplo, si el contraste alto está desactivado, no hay ninguna coincidencia real. La coincidencia neutra es la mejor coincidencia que se puede encontrar, por lo que se carga el recurso logo.png .

Si tuviera que cambiar el nombre de logo.png a logo.contrast-standard.png, el nombre de archivo contendrá un valor de calificador real. Con el contraste alto, habría una coincidencia real con logo.contrast-standard.pngy ese es el archivo de recursos 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 el contraste alto y otro para el contraste estándar, puede usar nombres de carpeta en lugar de nombres de archivo. En este caso, si se omite el nombre de carpeta por completo, se proporciona la coincidencia 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>

Para más información sobre cómo funciona la coincidencia de calificadores, consulte Sistema de administración de recursos.

Varios calificadores

Puede combinar calificadores en nombres de carpeta y archivo. Por ejemplo, puede 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 carpetas anidadas.

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

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

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

En función de las herramientas y el flujo de trabajo que use para la creación de recursos, o sobre lo que encuentre más fácil de leer o administrar, puede elegir una única estrategia de nomenclatura para todos los calificadores, o puede combinarlas para distintos calificadores.

AlternateForm

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 japonesas para proporcionar una cadena furigana para la que el valor msft-phonetic está reservado (consulte la sección "Compatibilidad con Furigana para cadenas japonesas que se pueden ordenar" en Preparación para la localización).

El sistema de destino o la aplicación deben proporcionar un valor con el que alternateform coincidan los calificadores. No use el msft- prefijo para sus propios valores de calificador personalizados alternateform .

Configuración

Es poco probable que necesite el nombre del configuration calificador. Se puede usar para especificar recursos que solo son aplicables a un entorno en tiempo de creación determinado, como los recursos de solo prueba.

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.

Compare

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 custom calificador y, a continuación, se cargan los recursos que mejor coincidan con 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, asignaría los nombres de los recursos que incluyen los calificadores custom-premium, custom-standardy custom-trial.

DeviceFamily

Es poco probable que necesite el nombre del devicefamily calificador. 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 controles y diseño de 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 un elemento común MainPage.xaml.cs, que permanece sin cambios en el 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 la aplicación se ejecuta en la familia de dispositivos móviles, el elemento <TextBlock x:Uid="DeviceFriendlyName"/> de interfaz de usuario usará el texto y los recursos en primer plano definidos en el Resources.devicefamily-mobile.resw archivo si contiene.

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

Para 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 necesite el nombre del dxfeaturelevel calificador. Se diseñó para usarse con recursos de juego de Direct3D, para hacer que los recursos de nivel inferior se carguen para que coincidan con una configuración de hardware de nivel inferior determinada del tiempo. Pero la prevalencia de esa configuración de hardware es ahora tan baja que se recomienda no usar este calificador.

HomeRegion

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 BCP-47 válida. Es decir, cualquier código de región de dos letras ISO 3166-1 alfa-2 , además del conjunto de códigos geográficos numéricos de tres dígitos ISO 3166-1 para regiones compuestas (véase 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 language calificador corresponde a la configuración de idioma para mostrar. Los valores incluyen cualquier etiqueta de idioma BCP-47 válida. Para obtener una lista de idiomas, consulte el registro de subetiquetas de idioma de IANA.

Si quieres que la aplicación admita distintos idiomas de presentació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 hacer una copia traducida de ese archivo de recursos para cada idioma que admita la aplicación.

Normalmente, se usa un language calificador para asignar un nombre a las carpetas que contienen los archivos de recursos (.resw).

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

Puede omitir la language- parte de un language calificador (es decir, el nombre del calificador). No puedes hacerlo con los demás tipos de calificadores; y solo puede hacerlo en un nombre de carpeta.

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

En lugar de asignar nombres a carpetas, puede usar language calificadores para asignar un nombre a los propios archivos de recursos.

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

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

LayoutDirection

Un layoutdirection calificador corresponde a la dirección de diseño de la configuración del idioma de presentación. Por ejemplo, es posible que una imagen deba 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 correctamente a la dirección del diseño si establece su propiedad FlowDirection (consulte Ajustar el diseño y las fuentes y admitir RTL). Sin embargo, el layoutdirection calificador es para los casos en los que el cambio simple no es adecuado y permite responder a la direccionalidad del orden de lectura específico y la alineación del texto 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 Píxeles efectivos y factor de escala. 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 en este ejemplo se 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 el destino.

TargetSize

El targetsize calificador se usa principalmente para especificar iconos de asociación de tipo de archivo o iconos de protocolo que se mostrarán en Explorador de archivos. El valor del calificador representa la longitud lateral de una imagen cuadrada en píxeles sin formato (físicos). El recurso cuyo valor coincide con el valor De vista en 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 representan varios tamaños de valor de calificador para el icono de targetsize aplicación (/Assets/Square44x44Logo.png) en la pestaña Activos 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 el destino.

Tema

El theme calificador 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 sin placa

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 proporcionaron recursos altform-unplated 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 calificador de recursos de formulario alternativo: altform-lightunplated. Este calificador refleja el calificador altform-unplated existente.

Consideraciones de nivel inferior

Las aplicaciones no deben usar el theme-light calificador con el altform-unplated calificador. Esto provocará un comportamiento imprevisible 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 windows, la versión de theme-light se puede usar incorrectamente. El altform-lightunplated calificador 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 plateada del recurso.

API importantes