Partilhar via

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

Use a codificação de caracteres Unicode Transformation Format 8-bit (UTF-8) 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 testes.

UTF-8 é a página de código universal para internacionalização e é capaz de codificar todo o conjunto de caracteres Unicode. É 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 interface de dispositivo gráfico (GDI) do Windows não oferece suporte à configuração da propriedade activeCodePage por processo. Em vez disso, o GDI assume 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 do> WindowsHora & idioma>Idioma e região>Configurações de idioma administrativo> a localidade do sistema e marque Beta: Use Unicode UTF-8 para suporte a idiomas em todo o mundo. Em seguida, reinicie 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 gerir a deteção e conversão de páginas de código legadas como habitualmente. Com uma versão mínima de destino do Windows 1903, a página de códigos do processo será sempre UTF-8, assim, a deteção e conversão de páginas de códigos herdadas podem ser evitadas.

Observação

Em 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 empacotado:

<?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 não empacotado:

<?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. APIs -W

As APIs do Win32 geralmente suportam variantes -A e -W.

-As variantes reconhecem a página de código ANSI configurada no sistema e suportam char*, enquanto as variantes -W operam em UTF-16 e suportam WCHAR.

Até recentemente, o Windows enfatizava as variantes 'Unicode' de -W em detrimento das APIs -A. No entanto, versões recentes usaram a página de código ANSI e APIs -A como um meio de introduzir o suporte 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. Este modelo tem a vantagem de suportar código existente criado com APIs -A sem quaisquer 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 interoperar com 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 que se converta a entrada UTF-8 para WCHAR a fim de passá-la para uma API -W e, em seguida, converter quaisquer resultados de volta, se necessário.

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

Observação

CP_ACP equivale apenas se CP_UTF8 estiver sendo executado no Windows Versão 1903 (Atualização de maio de 2019) ou superior e a propriedade activeCodePage descrita acima estiver definida como UTF-8. Caso contrário, ele respeita a página de código do sistema herdado. Recomendamos explicitamente o uso de CP_UTF8.

  • Last updated on