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

  • Artigo

Use a codificação de caracteres UTF-8 para compatibilidade ideal entre aplicativos web e outras plataformas baseadas em *nix (Unix, Linux e variantes), minimize bugs de localização e reduza a sobrecarga de testes.

UTF-8 é a página de código universal para internacionalização e é capaz de codificar todo o conjunto de caracteres Unicode. Ela é usada de forma generalizada na web e é o padrão para plataformas baseadas em *nix.

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

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

Observação

No momento, o GDI não oferece suporte à configuraçã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, vá para Configurações>Hora e idioma>Idioma e região>Configurações administrativas de idioma>Alterar local do sistema e marque a opção Beta: use 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 nas compilações anteriores do Windows, mas deve lidar com a detecção e conversão da página de código herdada normalmente. 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

Um caractere codificado tem entre 1 e 4 bytes. A codificação UTF-8 é compatível com sequências de bytes mais longas, até 6 bytes, mas o maior ponto de código do Unicode 6.0 (U+10FFFF) tem apenas 4 bytes.

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.

-A vs. -W APIs

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 sendo executado no Windows Versão 1903 (atualização de maio de 2019) ou posterior e a propriedade ActiveCodePage descrita acima estiver 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.