示例工程【免费下载链接】Windows-universal-samplesAPI samples for the Universal Windows Platform.项目地址https://gitcode.com/gh_mirrors/wi/Windows-universal-samples点击查看免费下载本文以 Samples/ApplicationResources 示例为核心讲解如何在 UWP 应用中把字符串、图片等可本地化内容与业务代码分离利用 Windows 资源管理系统MRT实现多语言、多 DPI、多对比度、多地域等多维度的资源匹配与回退。读完本文你将掌握.resw资源文件的组织方式、XAMLx:Uid与代码侧ResourceLoader的用法、AppX 清单中ms-resource:引用、多维限定符回退以及在非 UI 线程中安全检索资源等完整实战方案。示例概览与工程结构该示例是 Windows-universal-samples 集合中关于应用资源与本地化的官方示例源码分别提供 C#、CCppCX与 VB 三种语言实现目录内还有cpp、cs、vb三个子工程所有语言的界面与资源都共享shared目录避免重复维护C# 工程C 工程VB 工程共享资源与 XAML核心依赖的 WinRT 命名空间是 Windows.ApplicationModel.Resources.Core提供ResourceManager、ResourceContext、ResourceMap等底层 API和 Windows.ApplicationModel.Resources提供便捷的ResourceLoader以及 Windows.Globalization提供ApplicationLanguages语言管理。示例在 constants.cs 中把全部 13 个场景注册为主页面列表可以直观看到本示例覆盖的技术点场景主题对应文件1XAML 中的字符串资源x:Uidscenario1.xaml2XAML 中的文件资源图片的多限定符回退scenario2.xaml3代码中的字符串资源ResourceLoaderscenario3.xaml.cs4AppX 清单中的资源引用ms-resource:scenario4.xaml5附加资源文件独立.resw文件scenario5.xaml.cs6类库中的资源跨程序集检索scenario6.xaml.cs7运行时更改与事件ResourceContext变更监听scenario7.xaml.cs8应用语言ApplicationLanguagesscenario8.xaml.cs9语言覆盖context.Languagesscenario9.xaml.cs10多维回退language/scale/contrast/homeregionscenario10.xaml.cs11与 Web 服务协作本地化查询参数scenario11.xaml.cs12在非 UI 线程检索资源scenario12.xaml.cs13代码中的文件资源限定符 StorageFilescenario13.xaml.cs为什么要把资源与代码分离UWP 鼓励开发者把字符串、图片、音频等资源从代码中分离出来独立维护与修改。这样做的直接收益是本地化同一份代码通过语言限定符en、fr、ja等适配多种语言无需为每种语言改代码设备适配通过scale对应 DPI/缩放、contrast高对比度等限定符为不同设备形态提供最合适的资源用户定制通过homeregion等限定符针对特定区域用户提供差异化内容。仓库中 shared/strings/dimensions/ 就是上述多维能力的教科书式演示同一份dimensions.resw以dimensions.lang-en.resw、dimensions.lang-en-gb.resw、dimensions.contrast-high.resw、dimensions.scale-140.resw、dimensions.homeregion-us.resw等二十多个文件形态存在每个文件名后缀就是一个限定符 值资源系统会根据运行时上下文自动挑选最合适的变体。构建与运行系统要求Windows 10示例使用Windows.Universal目标设备家族见 cs/Package.appxmanifest 中的TargetDeviceFamily声明MinVersion 为 10.0.10240.0Visual Studio含 UWP 工作负载。构建步骤若以 ZIP 方式下载整个示例集合务必解压完整归档而不是只解压单个示例文件夹因为示例依赖仓库根目录的SharedContentREADME 元数据中extendedZipContent也指定了SharedContent与LICENSE需要随包分发启动 Visual Studio选择File Open Project/Solution进入解压目录依次进入Samples→ApplicationResources→ 首选语言子目录cs/cpp/vb双击其中的.sln解决方案文件按CtrlShiftB或选择Build Build Solution编译。运行步骤仅部署选择Build Deploy Solution部署并调试运行按F5或Debug Start Debugging不调试直接运行按CtrlF5或Debug Start Without Debugging。字符串资源XAML 中的x:Uid绑定场景 1 演示了最常用的字符串资源用法在 XAML 中给元素挂上x:Uid资源系统自动把.resw文件中形如[Uid].[属性名]的条目应用到对应属性上。看 scenario1.xaml 的输出区域TextBlock Style{StaticResource BasicTextStyle} x:UidWelcomeHeader x:NameScenario1TextBlock TextHello FontSize20 /对应 shared/strings/en/resources.resw 中的三个条目data nameWelcomeHeader.Text xml:spacepreserve valueHello World/value /data data nameWelcomeHeader.Width xml:spacepreserve value115/value /data机制要点x:Uid是属性级的资源绑定.resw条目名是WelcomeHeader.TextUid 点号 属性名XAML 解析器会把TextBlock.Text覆盖为资源值默认文本TextHello作为设计期占位值保留运行时被资源值替换资源文件按 BCP-47 语言标签组织成en、fr、ja等子目录见 shared/strings/例如 fr/resources.resw 与 ja/resources.resw 存放对应语言翻译系统按当前语言自动选择。字符串资源代码中的ResourceLoader场景 3 演示在代码中检索字符串这是动态拼接文本、后台逻辑提示等场景的常用方式。scenario3.xaml.cs 中的核心代码var resourceLoader ResourceLoader.GetForCurrentView(); this.Scenario3TextBlock.Text resourceLoader.GetString(string1);其中string1定义在默认资源文件中data namestring1 xml:spacepreserve valueHello World/value /dataResourceLoader.GetForCurrentView()返回与当前视图绑定语言、缩放、对比度等上下文随视图的资源加载器不带文件名参数时默认从Resources.resw检索。若资源分布在其他.resw文件如Errors.resw则传入文件名作为第二个参数// 场景 5从附加资源文件 Errors.resw 中读取 InvalidOperation var resourceLoader ResourceLoader.GetForCurrentView(Errors); this.Scenario5TextBlock.Text resourceLoader.GetString(InvalidOperation);见 scenario5.xaml.cs。Errors.resw同样按语言拆分en/errors.resw、fr/errors.resw、ja/errors.resw错误信息也能随语言切换。AppX 清单中的资源引用场景 4 演示如何让Package.appxmanifest中的显示名、描述、Logo 等也走资源系统从而为不同语言/缩放/对比度提供多个变体。cs/Package.appxmanifest 中可以看到Properties DisplayNamems-resource:displayNameCS/DisplayName Logoimages\packagelogo.png/Logo /Properties ... Application IdApplicationResources.App Executable$targetnametoken$.exe EntryPointApplicationResources.App uap:VisualElements DisplayNamems-resource:appDisplayNameCS Square150x150LogoImages\logo.png Square44x44LogoImages\logo.png Descriptionms-resource:appDescriptionCS BackgroundColor#00b2f0 uap:SplashScreen ImageImages\splashscreen.png / /uap:VisualElements /Application要点字符串资源必须使用ms-resource:前缀的 URI 方案如ms-resource:displayNameCS对应的键定义在 en/resources.resw 中appDisplayNameCS、appDescriptionCS、displayNameCS、shortNameCS等README 指出shortName必须少于 13 个字符且是 displayName 的缩写文件资源直接引用逻辑文件名如Images\logo.png物理文件通过 shared/images/ 下的logo.scale-140.png、logo.scale-180.png、logo.contrast-black_scale-100.png等带限定符的变体自动解析不同语言C#/VB/C使用各自后缀的键名displayNameCS、displayNameVB、displayNameCPP同一套资源文件可服务三个语言的工程。文件资源图片的多限定符回退场景 2 演示了图片这类文件资源的虚拟化寻址。scenario2.xaml 中 XAML 只引用逻辑路径Image SourceImages/projector.png Height80 Width80 StretchUniformToFill / Image SourceImages/ProjectorWithScaleCaption.png Height80 Width80 StretchUniformToFill /而实际包内并不存在projector.png真正存在的是 shared/images/en-US/ 与 shared/images/ja/ 下的物理文件例如projector.scale-100_contrast-black.png projector.scale-140_contrast-standard.png projector.scale-180_contrast-white.png解析规则限定符既可以用文件夹名也可以用文件名如en-US/是语言限定符目录projector.scale-100_contrast-standard.png的文件名中scale-100、contrast-standard是多个限定符的组合XAML 或代码中的任何文件引用都会被虚拟化资源系统依据当前上下文语言、缩放、对比度解析出最合适的物理文件变体可以按 scale100/140/180对应不同 DPI、contraststandard/black/white/high、languageen-US/ja等任意维度组合。要实际看到不同图片可以按场景说明操作改变语言偏好PC 设置 时间和语言 区域和语言添加应用支持的语言示例支持英文、日文并设为主要语言改变缩放因子使用多显示器低 DPI 高 DPI或 Visual Studio 模拟器改变对比度PC 设置 轻松使用 高对比度选择一个主题然后重启应用。类库中的资源与跨程序集检索场景 6 演示把资源放进独立的类库AppResourceClassLibrary并从应用读取这是组件化、插件化应用中常见的诉求。工程位于 cs/AppResourceClassLibrary/核心实现 class1.cspublic static class LocalizedNamesLibrary { static ResourceLoader resourceLoader null; public static string LibraryName { get { String name; GetLibraryName(string1, out name); return name; } } private static void GetLibraryName(string resourceName, out string resourceValue) { if (resourceLoader null) { // 从类库资源文件默认 Resources.resw加载 resourceLoader ResourceLoader.GetForCurrentView(AppResourceClassLibrary/Resources); } resourceValue resourceLoader.GetString(resourceName); } }应用侧调用scenario6.xaml.csvar resourceLoader ResourceLoader.GetForCurrentView(AppResourceClassLibrary/Resources); this.Scenario6TextBlock.Text Retrieved from app: resourceLoader.GetString(string1); this.Scenario6TextBlock2.Text Retrieved from class library: AppResourceClassLibrary.LocalizedNamesLibrary.LibraryName;要点ResourceLoader.GetForCurrentView的文件名参数使用程序集名 / 资源文件名的路径形式AppResourceClassLibrary/Resources即表示类库程序集中的Resources.resw类库内部的资源加载器采用延迟初始化if (resourceLoader null)避免每次访问都重新创建。ResourceContext、运行时变更与事件监听ResourceContext是资源解析的核心对象它封装了语言、缩放、对比度等限定符值集合ResourceManager.Current.MainResourceMap则提供对应用主资源映射的访问。监听运行时上下文变更场景 7scenario7.xaml.cs 先通过ResourceContext.GetForCurrentView()拿到当前视图的默认上下文再用ResourceManager.Current.MainResourceMap.GetValue(Resources/string1, context)显式解析资源随后订阅上下文的QualifierValues.MapChanged事件当限定符值例如用户在系统中切换语言发生变化时在 UI 线程重新解析字符串并刷新显示defaultContextForCurrentView ResourceContext.GetForCurrentView(); ... this.Scenario7TextBlock.Text ResourceManager.Current.MainResourceMap .GetValue(Resources/string1, defaultContextForCurrentView).ValueAsString; defaultContextForCurrentView.QualifierValues.MapChanged async (s, m) { await this.Scenario7TextBlock.Dispatcher.RunAsync( Windows.UI.Core.CoreDispatcherPriority.Normal, () { this.Scenario7TextBlock.Text ResourceManager.Current.MainResourceMap .GetValue(Resources/string1, defaultContextForCurrentView).ValueAsString; }); };注意跨线程更新 UI 时必须通过Dispatcher.RunAsync封送到 UI 线程。同时可以结合 scenario12.xaml.cs 理解上下文与线程的关系非 UI 线程若要解析资源要么把 UI 线程创建的ResourceContext传入工作线程要么使用ResourceContext.GetForViewIndependentUse()创建视图无关上下文——但后者默认没有设置scale限定符若资源存在 scale 变体则可能解析失败需要程序化设置 scale 值且调用Reset()后会回到无 scale 的默认状态。应用语言与语言覆盖应用语言列表场景 8scenario8.xaml.cs 展示如何枚举与管理应用语言// 当前生效的应用语言含用户语言偏好过滤 String.Join(, , ApplicationLanguages.Languages) // 清单中声明的全部语言含资源包场景 ApplicationLanguages.ManifestLanguages // 持久化的主语言覆盖 ApplicationLanguages.PrimaryLanguageOverride页面把用户偏好中匹配应用的语言与清单声明的全部语言分别加入下拉框中间用分隔项隔开。源码注释里明确说明了两种模式的差别如果用户更改语言偏好默认设置无覆盖意味着主应用语言可能随之变化而如果把它设为覆盖语言PrimaryLanguageOverride即使用户之后更改语言偏好主应用语言也会保持不变。选择下拉项后执行ApplicationLanguages.PrimaryLanguageOverride languageTag即设置持久化的主语言覆盖。视图级语言覆盖场景 9与PrimaryLanguageOverride应用级持久化不同场景 9 演示在当前视图的 ResourceContext 上临时覆盖语言作用域仅限该上下文。scenario9.xaml.cs 的关键代码var context ResourceContext.GetForCurrentView(); var lang new Liststring { selectedLanguage.ToString() }; context.Languages lang; var resourceStringMap ResourceManager.Current.MainResourceMap.GetSubtree(Resources); this.Scenario9TextBlock.Text resourceStringMap.GetValue(string1, context).ValueAsString;由于该示例把多个场景加载在同一个宿主页面同一个 CoreWindow/视图中默认上下文是共享的因此源码特意在OnNavigatedFrom中调用context.Reset()清理语言覆盖避免影响其他场景。这提醒我们视图级覆盖的生命周期需要自行管理真实应用中要根据设计决定何时清除覆盖。多维回退Multi-dimensional fallback场景 10 是资源系统最硬核的部分同时设置 language、scale、contrast、homeregion 四个限定符观察同一资源在不同维度组合下的候选与回退结果。scenario10.xaml.cs 中var context ResourceContext.GetForCurrentView().Clone(); context.QualifierValues[language] selectedLanguage.ToString(); context.QualifierValues[scale] selectedScale.ToString(); context.QualifierValues[contrast] selectedContrast.ToString(); context.QualifierValues[homeregion] selectedHomeRegion.ToString(); var dimensionMap ResourceManager.Current.MainResourceMap.GetSubtree(dimensions); foreach (var id in resourceIds) // LanguageOnly, ScaleOnly, ContrastOnly, HomeRegionOnly, MultiDimensional { NamedResource namedResource; if (dimensionMap.TryGetValue(id, out namedResource)) { var resourceCandidates namedResource.ResolveAll(context); Scenario10_ShowCandidates(id, resourceCandidates); } }代码用Clone()创建独立上下文避免本场景的设置污染其他场景随后对每个资源 ID 调用ResolveAll(context)获取全部候选并输出每个候选的Qualifiers限定符名称/值、IsMatch是否精确匹配与IsDefault是否回退到默认值直观展示回退链。支撑这些候选的资源文件就是 shared/strings/dimensions/ 下的二十多个变体例如dimensions.resw无任何限定符的默认资源This is an unqualified resourcedimensions.lang-en.resw、dimensions.lang-en-gb.resw语言限定后者内容为This is a resource in English as spoken in the United Kingdomdimensions.lang-fr.resw、dimensions.lang-fr-fr.resw法语及法国法语dimensions.scale-100.resw、scale-140、scale-180缩放维度dimensions.contrast-standard.resw、contrast-black、contrast-white、contrast-high对比度维度部分还组合了 scale如dimensions.contrast-black_scale-100.reswdimensions.homeregion-us.resw、homeregion-001、homeregion-021地区维度。运行该场景时在四个下拉框中分别选择语言、缩放、对比度、地区输出区会列出dimensions\LanguageOnly、dimensions\ScaleOnly、dimensions\ContrastOnly、dimensions\HomeRegionOnly、dimensions\MultiDimensional等资源各自解析出的候选列表及每个候选的匹配状态IsMatch/IsDefault据此可清晰理解 MRT 的多维匹配与回退优先级。与 Web 服务协作本地化查询参数场景 11 演示把本地化信息传递给 Web 服务。scenario11.xaml.cs 使用默认资源文件中的webservicelang键拼出带语言参数的请求 URLvar resourceLoader ResourceLoader.GetForCurrentView(); this.Scenario11TextBlock.Text http://api.contoso.com/Feed?lang resourceLoader.GetString(webservicelang);webservicelang在 en/resources.resw 中值为en在 fr/resources.resw 与 ja/resources.resw 中分别对应各自语言代码。这种模式把向服务端声明客户端语言也纳入资源管理服务端可以据此返回对应语言的响应内容。代码中的文件资源限定符与 StorageFile场景 13场景 13 演示在代码中按限定符解析文件资源并读取内容。仓库在 shared/appdata/ 准备了三个按 DX 特性级别dxfeaturelevel限定的数据文件appdata.dxfl-dx9.dat appdata.dxfl-dx10.dat appdata.dxfl-dx11.datscenario13.xaml.cs 的逻辑// 1. 全局设置 dxfeaturelevel 限定符值作用于所有默认上下文 // 因为后续异步读取 StorageFile 发生在后台线程 ResourceContext.SetGlobalQualifierValue(dxfeaturelevel, combo.SelectedValue.ToString()); // 2. 用 ms-appx URI 引用逻辑文件实际解析发生在 // StorageFile.GetFileFromApplicationUriAsync 内部后台线程的默认上下文 Uri uri new Uri(ms-appx:///appdata/appdata.dat); // 3. 异步读取解析后的物理文件 StorageFile file await StorageFile.GetFileFromApplicationUriAsync(uri); string content await FileIO.ReadTextAsync(file); ResultText.Text content;这个场景揭示了两个关键细节ResourceContext.SetGlobalQualifierValue设置的是全局限定符值适用于所有默认上下文包括后台线程使用的上下文——这是让异步文件解析拿到正确dxfeaturelevel的关键文件型资源在资源映射中统一组织在Files顶层子树下其对应的ms-resourceURI 形如ms-resource:///Files/appdata/appdata.dat而此处为了配合StorageFileAPI 使用的是ms-appxURI二者 URI 方案不同用途不同ms-resource用于Windows.ApplicationModel.Resources/Resources.Core的 API。相关资源与进一步阅读示例入口与构建说明Samples/ApplicationResources/README.mdC# 解决方案cs/ApplicationResources.sln共享 XAML 与资源shared/xaml/、shared/strings/、shared/images/、shared/appdata/类库工程cs/AppResourceClassLibrary/历史 JavaScript 版示例已归档archived/ApplicationResources/实践建议把示例中的strings/en、fr、ja目录结构与x:Uid命名约定直接迁移到自己的 UWP 工程需要多设备适配时参考dimensions目录用文件名后缀组合限定符涉及后台线程解析资源时优先把 UI 线程的ResourceContext传入工作线程或对视图无关上下文显式设置scale等限定符。赞分享示例工程【免费下载链接】Windows-universal-samplesAPI samples for the Universal Windows Platform.项目地址https://gitcode.com/gh_mirrors/wi/Windows-universal-samples点击查看免费下载相关推荐Windows-universal-samples本地化资源管理UWP应用多语言支持Windows universal samples本地化资源管理UWP应用多语言支持 在全球化应用开发中多语言支持是提升用户体验的关键环节。Windows示例工程Windows-universal-samples游戏开发入门构建UWP平台游戏应用Windows universal samples游戏开发入门构建UWP平台游戏应用 Windows universal samples是微软提供的一系列Un示例工程提升研究质量Awesome Claude Skills学术写作助手提升研究质量Awesome Claude Skills学术写作助手 Awesome Claude Skills是一个精心策划的Claude技能、资源和工具列表AI 技能AI 插件人工智能工作流自动化上一篇Windows 激活不再折腾KMS 激活脚本使用教程5 分钟搞定系统与 Office下一篇如何用OBS Source Record插件实现多源独立录制一个录课up主的自救实录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
