Como carregar recursos de cadeias de caracteres (HTML)

Artigo
01/29/2016

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente ]

Você pode carregar recursos de cadeias de caracteres de objetos, como arquivos de recursos, bibliotecas, controles, pacotes e manifestos de aplicativos.

Carregando cadeias de caracteres de arquivos de recursos

Os recursos de cadeia de caracteres são criados nos arquivos de recursos e referenciados com o uso de identificadores de recursos. Para ler uma introdução básica sobre como carregar recursos de cadeias de caracteres, veja Início Rápido: usando recursos de cadeias de caracteres.

A maioria dos aplicativos precisa de apenas um único arquivo de recurso padrão por idioma (<language>/Resources.resjson), e eles podem se referir aos seus recursos usando um caminho relativo para chaves dentro desse arquivo (por exemplo, /String1). Mas, em alguns aplicativos, é apropriado separar os recursos em vários arquivos de recursos para permitir uma separação dos componentes.

Por exemplo:

Nome do arquivo:

Strings/en-US/Errors.resjson

Uma referência de marcação:

<span data-win-res="{textContent: '/Errors/AlreadyRegistered'}"></span>

Uma referência de código:

WinJS.Resources.getString('/Errors/AlreadyRegistered');

O identificador de recurso tem o formato **/ResourceFileName/**StringName. Observe que o nome do arquivo de recurso não inclui a extensão nem o caminho da pasta. Portanto, todos os nomes de arquivos de recurso precisam ser exclusivos em um componente ou projeto.

Carregando cadeias de caracteres de bibliotecas e controles

Os aplicativos normalmente têm vários componentes ou dependem de bibliotecas, como as bibliotecas de classes portáteis .NET, outras bibliotecas de classes compatíveis e bibliotecas de controles.

Sempre que possível, os controles e as bibliotecas devem tentar reduzir o número de recursos e contar com o aplicativo para fornecê-los. Quando uma biblioteca não precisa fornecer recursos, ela deve permitir que os aplicativos substituam esses recursos como uma entrada. Isso pode ser necessário quando a biblioteca não tem a mesma amplitude de localização que o aplicativo que a usa.

Por exemplo:

var rating = new WinJS.UI.RatingsControl(el, {label: 'Please Rate', image: 'images/star.png'});

O controle deve exibir cadeias de caracteres personalizadas passadaspara ele no estado original e, se possível, deixe o aplicativo lidar com a localização.

var control = new Control(el, {commands: [
    {label: R.getString('Reply')}, 
    {label: R.getString('ReplyAll')
    ]});

Em geral, os componentes ou arquivos de bibliotecas são adicionados a uma subpasta do pacote em que eles são incluídos durante o processo de criação, semelhante aos seus recursos de cadeias de caracteres. O identificador de recurso normalmente tem o seguinte formato:

ClassLibraryOrAssemblyName**/ResourceFileName/**StringName

Programaticamente, as bibliotecas também podem ter um ResourceLoader próprio para seus recursos. Por exemplo, o código a seguir ilustra como uma biblioteca pode obter um ResourceLoader para seu próprio arquivo de recurso:


var resources = Windows.ApplicationModel.Resources;
var RL = new resources.ResourceLoader('ContosoControl/Resources');
RL.getString('loadingStr'); // which came from ContosoControl's Resources

Carregando cadeias de caracteres de outros pacotes

Os recursos para cada pacote de aplicativo são gerenciados e acessados separadamente por meio de objetos ResourceMap de alto nível separados que podem ser acessados pelo ResourceManager atual. Dentro de cada pacote, vários componentes podem ter seus próprios valores ResourceMap Subtree.

Os pacotes de estruturas podem acessar seus próprios recursos com um URI mais absoluto:

Para obter mais detalhes sobre URIs ms-resource, consulte Esquemas de URI.

Carregando cadeias de caracteres de controles JavaScript

Os controles JavaScript que fornecem cadeias de caracteres padrão devem usar WinJS.Resources.getString para recuperar suas próprias cadeias de caracteres.

Os documentos HTML carregados no contexto Web (com ms-app-web:) não têm acesso às APIs do Tempo de Execução do Windows. Sendo assim, no código JavaScript, inclua controles JavaScript que foram escritos para usar WinJS.Resources.getString. No contexto Web, WinJS.Resources.getString faz o fallback para procurar pelo identificador fornecido como uma propriedade de um objeto de cadeia de caracteres global.

var strings = { 'String1' : 'Hello' };
WinJS.Resources.getString('String1');

Você também pode substituir WinJS.Resources.getString para buscar recursos em um local diferente.

WinJS.Resources.getString = function(id){
    return getStringFromOtherService(id);
}

Carregando cadeias de caracteres do manifesto do aplicativo

Todos os logotipos e cadeias de caracteres que possam ser exibidos no manifesto são localizáveis. Os logotipos também podem ser personalizados para o modo de escala e alto contraste. As referências de cadeia de caracteres podem ser adicionadas no lugar de uma cadeia de caracteres codificada colocando-se um URI especificado pelo esquema ms-resource: nos dados de manifesto (geralmente, isso é feito na interface do usuário com guias do Visual Studio para editar o appxmanifest). Por exemplo, ms-resource:String1 se refere a uma cadeia de caracteres chamada String1 no arquivo de recurso Resources.resw, enquanto ms-resource:/ManifestStrings/Shortname se refere a uma cadeia de caracteres chamada Shortname no arquivo de recurso ManifestStrings.resw.

Carregando cadeias de caracteres para um idioma ou contexto específico

O ResourceContextpadrão, um objeto obtido do ResourceManager, representa o estado atual ao qual os recursos são correspondidos. O ResourceContext contém todos os diversos valores de qualificador para o usuário e a máquina atuais. Embora seja possível substituir cada qualificador, isso não é recomendado. A maioria dos qualificadores tem um provedor de dados do sistema, que em alguns casos é melhor ser alterado por meio de uma API separada (ou seja, PrimaryLanguageOverride), ou é melhor deixar inalterado.

Veja Como nomear recursos usando qualificadores para saber mais sobre os diversos qualificadores.

O ResourceManager mantém o objeto de contexto padrão no qual as pesquisas de recursos são realizadas. Em alguns casos, é útil ser explícito em relação ao idioma, à escala ou a outro qualificador de contexto quando o aplicativo carrega recursos. Por exemplo, um aplicativo também pode permitir que um usuário escolha um idioma alternativo para dicas de ferramentas ou mensagens de erro. As pesquisas podem especificar seu próprio objeto de contexto substituído explícito para afetar o recurso que é escolhido. Para especificar um contexto explícito, onde a propriedade Languages é deliberadamente substituída:

var rcns = Windows.ApplicationModel.Resources.Core;

var context = new rcns.ResourceContext(); // deliberately not using getForCurrentView()
context.languages = new Array('fr-fr');
var resourceMap = rcns.ResourceManager.current.mainResourceMap.getSubtree('Resources');
var str = resourceMap.getValue('string1', context).ValueAsString;

Uma outra técnica que você pode usar é chamar ResourceContext.SetGlobalQualifierContext antes de chamar ResourceContext.GetForCurrentView. Para o cenário de idioma, você definiria o qualificador language para um novo valor. A diferença, se você fizer isso, é que a alteração de qualificador e contexto agora se aplica a todas as pesquisas de recursos, não apenas ao ResourceContext específico que você criou para usar na única chamada a GetValue. Veja também ApplicationLanguages.PrimaryLanguageOverride.

Alterações de eventos e contexto

Um aplicativo ainda pode ser executado quando o sistema é alterado. Isso resulta em um conjunto diferente de qualificadores em uso. Uma mudança desse tipo é quando o usuário ativa o alto contraste. Diversas mudanças no sistema invocam eventos no objeto ResourceContext.

No JavaScript, a maneira mais simples de escutar esses eventos é usando o método addEventListener:

WinJS.Resources.addEventListener('contextchanged', refresh, false);

Após detectar o evento, os aplicativos podem processar novamente o documento, para que os recursos corretos possam ser carregados.

function refresh(){
    WinJS.Resources.processAll(); // Refetch string resources.
}

O reprocessamento de recursos pode fazer com que valores vinculados a dados dentro do recurso sejam redefinidos à medida que o novo recurso é aplicado diretamente à propriedade do elemento. Se o recurso contiver slots de vinculação de dados, verifique se foram revinculados ao reprocessar.