Compartilhar via

Usar páginas de código UTF-8 em aplicativos do Windows

Use a codificação de caracteres UTF-8 (Formato de Transformação Unicode) de 8 bits para maximizar a compatibilidade entre aplicativos Web e outras plataformas baseadas em *nix (Unix, Linux e variantes), minimizar bugs de localização e reduzir a sobrecarga de teste.

UTF-8 é a página de código universal para internacionalização e é capaz de codificar todo o conjunto de caracteres Unicode. Ele é usado extensivamente na Web e é a codificação padrão para plataformas baseadas em XML e *nix.

Definir uma página de código de processo como UTF-8

A partir da Versão 1903 do Windows (Atualização de maio de 2019), você pode especificar a propriedade activeCodePage no appxmanifest para aplicativos empacotados (ou o manifesto de fusão para aplicativos não empacotados) para forçar um processo a usar UTF-8 como a página de código do processo.

Observação

Atualmente, a GDI (interface do dispositivo gráfico) do Windows não dá suporte à definição da propriedade activeCodePage por processo. Em vez disso, o GDI usa como padrão a página de código do sistema ativo. Para configurar seu aplicativo para renderizar texto UTF-8 via GDI, acesse Windows Configurações>Hora & idioma>Idioma & região>Configurações administrativas de idioma>Alterar a localidade do sistema, e marque Beta: usar Unicode UTF-8 para suporte a idiomas em todo o mundo. Reinicialize o PC para que a alteração entre em vigor.

Você pode declarar a propriedade activeCodePage e direcionar/executar em compilações anteriores do Windows, mas deve lidar com a detecção e a conversão da página de código herdada como de costume. Com uma versão de destino mínima do Windows Versão 1903, a página de código do processo sempre será UTF-8. Portanto, a detecção e a conversão de página de código herdada podem ser evitadas.

Observação

No UTF-8, um caractere codificado é representado por uma sequência de 1 a 4 bytes. (Consulte a definição D92 no Capítulo 3 do Padrão Unicode para a especificação formal.)

Exemplos

Manifesto do Appx para um aplicativo em pacote:

<?xml version="1.0" encoding="utf-8"?>
<Package xmlns="http://schemas.microsoft.com/appx/manifest/foundation/windows10"
         ...
         xmlns:uap7="http://schemas.microsoft.com/appx/manifest/uap/windows10/7"
         xmlns:uap8="http://schemas.microsoft.com/appx/manifest/uap/windows10/8"
         ...
         IgnorableNamespaces="... uap7 uap8 ...">

  <Applications>
    <Application ...>
      <uap7:Properties>
        <uap8:activeCodePage>UTF-8</uap8:activeCodePage>
      </uap7:Properties>
    </Application>
  </Applications>
</Package>

Manifesto do Fusion para um aplicativo Win32 sem pacote:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
  <assemblyIdentity type="win32" name="..." version="6.0.0.0"/>
  <application>
    <windowsSettings>
      <activeCodePage xmlns="http://schemas.microsoft.com/SMI/2019/WindowsSettings">UTF-8</activeCodePage>
    </windowsSettings>
  </application>
</assembly>

Observação

Adicione um manifesto a um executável existente a partir da linha de comando com mt.exe -manifest <MANIFEST> -outputresource:<EXE>;#1.

APIs -A versus -W

As APIs do Win32 geralmente são compatíveis com as variantes -A e -W.

-As variantes A reconhecem a página de código ANSI configurada no sistema e são compatíveis com char*, já as variantes -W operam em UTF-16 e são compatíveis com WCHAR.

Até recentemente, o Windows enfatizava as variantes -W "Unicode" sobre as APIs -A. No entanto, versões recentes usaram a página de código ANSI e as APIs -A como um meio de introduzir compatibilidade com UTF-8 para aplicativos. Se a página de código ANSI estiver configurada para UTF-8, as APIs -A normalmente operam em UTF-8. Esse modelo tem o benefício de compatibilidade com o código existente criado com APIs -A sem alterações de código.

Conversão de página de código

Como o Windows opera nativamente em UTF-16 (WCHAR), talvez seja necessário converter dados UTF-8 em UTF-16 (ou vice-versa) para interoperabilidade com as APIs do Windows.

MultiByteToWideChar e WideCharToMultiByte permitem converter entre UTF-8 e UTF-16 (WCHAR) (e outras páginas de código). Isso é particularmente útil quando uma API Win32 herdada pode entender apenas WCHAR. Essas funções permitem converter a entrada UTF-8 para WCHAR passar para uma API -W e, em seguida, converter resultados de volta, se necessário.

Uso dwFlags de um 0 ou MB_ERR_INVALID_CHARS ao usar essas funções com CodePage definido como CP_UTF8 (caso contrário, um ERROR_INVALID_FLAGS ocorre).

Observação

CP_ACP equivale a CP_UTF8 somente se estiver em execução no Windows Versão 1903 (Atualização de maio de 2019) ou superior e a propriedade activeCodePage descrita acima for definida como UTF-8. Caso contrário, ele honrará a página de código do sistema herdado. Recomendamos o uso de CP_UTF8 explícito.

  • Last updated on