HarmonyOS应用开发基础 课件 项目 3 资源管理与应用开发

项目3资源管理与应用开发深入理解HarmonyOS应用开发中的资源分类、创建、访问与匹配机制，掌握从基础资源目录到跨包访问的完整知识体系。导学概述在应用开发进程里，颜色、字体、间距、图标这类资源极为常用。由于设备的差异或配置的不同，这些资源的取值往往也有所不同。资源主要分为应用资源与系统资源两类：应用资源开发者凭借资源文件功能，在应用内部自定义的资源。开发者需要自行把控这些资源在各类设备或配置下的展示效果。系统资源开发者能够获取到的受支持的色彩、字体等系统资源的ID，以及这些资源在不同配置下的具体取值，同时还能从主题图标库获取受支持的系统图标资源。本项目将对资源相关内容展开详细阐述，涵盖资源分类、创建、访问、匹配等核心知识。知识目标01资源分类设计思想了解应用资源与系统资源的分类逻辑02资源目录与资源组目录理解base目录、限定词目录、rawfile目录、resfile目录以及element、media、profile资源组目录的概念03创建资源目录和资源文件掌握在DevEcoStudio中创建资源目录和资源文件的操作方法04资源可翻译特性理解attr属性对字符串翻译范围及翻译状态的标记机制05资源访问掌握访问单HAP包应用资源、跨HAP/HSP包应用资源以及系统资源的方法06资源匹配规则理解限定词目录与设备状态的匹配规则，以及获取配置资源和overlay机制能力目标1资源选择与使用能够根据项目需求合理选择和使用不同类型的资源文件2目录设置与管理能够设置和使用资源目录及资源组目录3资源创建与配置能够熟练创建并配置资源目录和资源文件4多语言支持实现支持多语言的应用程序，通过正确配置资源以适应不同的语言环境5HAP包资源管理能够访问和管理单一或多个HAP包内的资源6系统资源利用利用系统提供的资源来丰富应用的功能和界面7动态资源加载能够根据设备状态（如屏幕大小、分辨率等）动态加载最适合的资源素质目标系统化思维培养系统化思维和逻辑分析的能力，提高解决复杂问题时的资源规划与管理能力实践操作提升动手能力和实践操作技巧，形成良好的编程习惯和工作流程跨文化意识培养跨文化交流意识，适应多元文化环境的能力任务1自定义应用图标和界面图片任务描述：创建自定义应用图标和界面图片是应用程序开发过程中的重要步骤，它不仅影响到应用的视觉吸引力，还直接关系到用户体验。1放置资源将设计好的图标和界面图片放在对应的限定词目录中2引用资源在代码中正确引用创建的资源文件。对于应用图标，需在应用的配置文件中指定；对于界面图片，则在代码中进行引用3验证效果在模拟设备上运行应用，检查图标和界面图片显示效果是否达到预期必备知识3.1资源分类资源分类概述在应用开发过程中，所使用的各种资源文件，都必须在特定的子目录中进行存储与管理。资源目录包括base目录、限定词目录、rawfile目录以及resfile目录；而element、media、profile则被称为资源组目录。resources|—base//默认存在的目录||—element|||—string.json||—media|||—icon.png||—profile|||—test_profile.json|—en_GB-vertical-car-mdpi//自定义限定词目录示例||—element|||—string.json||—media|||—icon.png||—profile|||—test_profile.json|—rawfile//原始文件形式保存，不集成到resources.index|—resfile//原始文件形式保存，不集成到resources.index在stage模型且存在多工程的情形下，各个工程所共有的资源文件需放置于AppScope目录下的resources目录中。3.1.1资源目录base目录与限定词目录1.base目录base目录是一个默认生成的目录：二级子目录element用于存放字符串、颜色、布尔值等基础元素media和profile子目录用于存放媒体、动画、布局等资源文件资源文件在编译过程中会被转换为二进制文件每个资源文件都会被赋予一个唯一的资源文件ID通过指定资源的type和name来访问2.限定词目录限定词目录需开发者依据实际开发需求自主创建：二级子目录同样有element、media、profile用途为存储字符串、颜色、布尔值等基础元素，以及媒体、动画、布局等资源文件资源文件在编译时同样会被转化为二进制格式被分配独一无二的资源文件ID通过明确指定资源的type与name实现调用限定词目录的命名要求限定词目录由一个或多个能体现应用场景、设备特征的限定词组合构成，涵盖移动国家码与移动网络码、语言、文字、国家或地区、横竖屏状态、设备类型、颜色模式、屏幕密度等维度。组合顺序移动国家码_移动网络码-语言_文字_国家或地区-横竖屏-设备类型-颜色模式-屏幕密度连接规则语言、文字、国家或地区间及移动国家码与移动网络码间用下划线；其余用中划线示例：zh_Hant_CN、zh_CN-car-ldpi。限定词取值需严格符合规定，否则无法正确匹配资源。限定词取值要求（表3-1）限定词类型含义与取值说明移动国家码和移动网络码MCC可与MNC合并使用（下划线连接），也可单独使用。例如：mcc460表示中国；mcc460_mnc00表示中国移动。详见ITU-TE.212语言由2~3个小写字母组成。例如：zh表示中文；en表示英语；mai表示迈蒂利语。详见ISO639文字由1个大写字母（首字母）和3个小写字母组成。例如：Hans表示简体中文，Hant表示繁体中文。详见ISO15924国家或地区由2~3个大写字母或3个数字组成。例如：CN表示中国；GB表示英国。详见ISO3166-1限定词取值要求（续表）限定词类型含义与取值说明横竖屏vertical：竖屏；horizontal：横屏设备类型phone：手机；car：车机；tablet：平板；tv：智慧屏；wearable：智能穿戴；2in1颜色模式dark：深色模式；light：浅色模式屏幕密度sdpi：(0,120]；mdpi：(120,160]；ldpi：(160,240]；xldpi：(240,320]；xxldpi：(320,480]；xxxldpi：(480,640]（单位dpi）rawfile目录与resfile目录4.rawfile目录允许创建具有多个层级的子目录，子目录名称可由用户自行设定，内部能自由存放各种资源文件。资源文件会被直接打包至应用程序中不会经历编译，也不会被分配资源文件ID访问时需通过指定具体的文件路径以及文件名来实现5.resfile目录同样允许创建多层次的子目录，名称可由开发者自定义设定。资源文件会被直接打包至应用中，不经历编译，不赋予资源文件ID应用安装后，resfile资源将被解压至应用沙箱路径通过Context属性中的resourceDir获取resfile资源目录依据文件路径对资源文件进行访问操作3.1.2资源组目录资源组目录说明（表3-2）资源组目录涵盖element、media、profile这三类资源文件，专门用于存放特定类型的资源。目录类型说明资源文件element表示元素资源，支持boolean、color、float、intarray、integer、plural、strarray、string等JSON文件类型建议文件名：boolean.json、color.json、float.json、intarray.json、integer.json、plural.json、strarray.json、string.jsonmedia表示媒体资源，包括图片、音频、视频等非文本格式的文件文件名可自定义，例如：icon.pngprofile表示自定义配置文件，其文件内容可通过包管理接口获取（仅支持json文件类型）文件名可自定义，例如：test_profile.json媒体资源类型说明图片资源类型（表3-3）格式文件名后缀JPEG.jpgPNG.pngGIF.gifSVG.svg音视频资源类型（表3-4）格式支持的文件类型H.264AVC.3gpBaselineProfile(BP).mp4资源文件示例：color.json一个符合标准的十六进制颜色值由6个十六进制数字构成。在value值中，最前面的2个十六进制数字代表透明度，后面的6个十六进制数字代表颜色值。{"color":[{"name":"color_hello","value":"#ffff0000"}]}3.2创建资源创建资源目录和资源文件在resources目录中，开发者能够依据限定词目录的命名规则，以及资源组目录所允许的文件类型，来创建资源目录与资源组目录，并向其中添加特定类型的资源。DevEcoStudio为开发者提供了多种创建方式：方式一同时创建资源目录与资源文件方式二单独创建资源目录方式三单独创建资源文件3.2.1创建资源目录和文件如需在resources目录下创建资源目录及资源文件，可右击该目录，依次选择"New→ResourceFile"选项。默认情况下，文件会被创建在base目录下对应的资源组中。如果选择了限定词，系统会依据命名规范自动生成限定词目录和资源组目录，并将文件创建在限定词目录里。Filename即将创建的文件名称Resourcetype资源组的类型，默认值为"Element"Rootelement资源的具体类型Availablequalifiers可供选择的限定词目录，可通过右侧小箭头添加或删除所创建的目录名会自动生成，格式为"限定词_资源组"。例如，限定词为"dark"的"element"目录，自动生成名称为dark/element。图3-1创建资源目录和资源文件3.2.2创建资源目录在resources目录上右击，从弹出的菜单中选择"New→ResourceDirectory"选项时，便能够创建资源目录。一般情况下，默认创建的是base目录。若操作过程中勾选限定词，系统将按预设命名规范，自动生成对应的限定词目录与资源组目录。在确定好限定词之后，需要进一步选择资源组类型。目前，资源组类型支持Element、Media、Profile这三种。完成选择并执行创建操作后，就会生成对应的资源目录。图3-2创建资源目录3.2.3创建资源文件在资源目录（包括element、media、profile）上右击时，在弹出的快捷菜单中选择"New→XXXResourceFile"选项，就能够创建与当前资源组目录相对应的资源文件。例如，若在element目录下进行上述操作，便可以新建ElementResourceFile。图3-3创建资源文件Rootelement下拉菜单中提供了boolean、color、float、intarray、integer、pattern、plural、strarray等多种资源类型供选择。3.3资源可翻译特性资源可翻译特性3.3.1功能介绍当资源需要进行翻译时，可以利用attr属性来对字符串的翻译范围以及翻译状态进行标记。attr属性在整个资源编译过程中不会参与其中，它的作用仅仅是标识字符串是否已被翻译。若没有对attr属性进行配置，系统则默认该字符串是需要进行翻译处理的。"attr":{"translatable":false|true"priority":"code|translate|LT|customer"}名称类型说明translatableboolean标记字符串是否需要翻译。true：需要翻译；false：不需要翻译prioritystring标记字符串翻译状态。code：未翻译；translate：翻译未验证；LT：翻译已验证；customer：用户定制字符串3.3.2使用约束可翻译特性的有效适用范围为：位于base目录下的string（字符串）、strarray（字符串数组）、plural（复数形式字符串）这几种类型的资源。3.4资源访问资源访问概述单HAP包访问$r与$rawfile用于包内资源。跨HAP/HSP访问使用createModuleContext跨模块获取资源。系统资源访问$r('')用于系统级资源。HarmonyOS提供了三种主要的资源访问方式，分别针对单HAP包内资源、跨包资源以及系统级资源，开发者可根据实际需求灵活选用。3.4.1单HAP包应用资源$r与$rawfile访问方式可以借助$r或$rawfile访问资源。$r('')形式针对color、float、string、plural、media、profile等类型的资源。其中app为resources目录中定义的资源；type为资源类型；name为资源名。带占位符的访问对于string.json中使用多个占位符的情况，通过$r('app.string.label','aaa','bbb',444)形式访问。$rawfile('filename')形式对于rawfile目录中的资源，filename指rawfile目录下文件的相对路径，文件名必须包含文件后缀，路径不能以"/"开始。例3-1：获取带占位符的字符串资源用函数$r()获取message_notification字符串资源：{"name":"message_notification","value":"Hello,%1$s!Youhave%2$dnewmessages."}上述资源类型为string，有两个占位符参数，获取message_notification资源如下：letmessage:Resource=$r('app.string.message_notification','Job',100);$r('eger_1')返回的是一个Resource类型的对象，而不是具体的数值。必须通过调用resourceManager.getNumber()方法或resourceManager.getNumberByName()方法来获取实际的数值资源。资源的具体使用方法以下代码展示了在组件中通过$r引用各类资源的方式：//通过$r('')访问Text($r('app.string.string_hello')).fontColor($r('app.color.color_emphasize')).fontSize($r('app.float.text_size_headline')).fontFamily($r('app.string.font_family_medium')).backgroundColor($r('app.color.color_palette_aux1'))//对占位符，通过$r('app.string.label','aaa','bbb',444)访问Text($r('app.string.message_notification','LiHua',2))ResourceManager具备让用户访问应用资源的功能。通过创建ResourceManager对象，能够依据当前的configuration信息（语言、区域、屏幕横竖方向、Mcc、Mnc、Devicecapability、Density等），提供相应的接口获取并读取应用资源。//在Stage模型下，通过context获取ResourceManager对象letresMgr=getContext().resourceManager;ResourceManager接口详解①getNumber(resId:number):number用户获取指定资源ID对应的integer数值或者float数值，使用同步方式返回。参数名类型必填说明resIdnumber是资源ID值返回值：number类型。integer对应的是原数值，float对应的是真实像素点值。try{//integer对应返回的是原数值this.context.resourceManager.getNumber($r('eger_test'),id);}②getNumberByName(resName:string):number用户获取指定资源名称对应的integer数值或者float数值，使用同步方式返回。参数名类型必填说明resNamestring是资源名称返回值：number类型。integer对应原数值，float不带单位时对应原数值，带"xp""fp"单位时对应px值。try{this.context.resourceManager.getNumberByName('integer_test');}其他资源访问方式获取字符串资源getContext().resourceManager.getStringByNameSync('test')获取rawfile描述符getContext().resourceManager.getRawFd('rawfilepath')，访问时需结合(fd,offset,length)参数例3-2：获取字符串资源值继例3-1，获取字符串资源message_notification的值：letmessage:Resource=$r('app.string.message_notification');letresMgr=getContext().resourceManager;//同步实现letvalue,string=resMgr.getStringSync(message,id,'Job',100);console.log(value);输出：Hello,Job!Youhave100newmessages.模块内引用资源示例1.string类型资源定义：{"name":"greetings","value":"你好,世界"}组件引用：Text($r('app.string.greetings'))逻辑引用：letwelcome:string=getContext().resourceManager.getStringByNameSync("greetings");2.color类型资源定义：{"name":"color_red","value":"#ffff0000"}组件引用：Row().size({width:400,height:100}).backgroundColor($r('app.color.color_red'))逻辑引用：constred:number=getContext().resourceManager.getColorByNameSync("color_red");3.4.2跨HAP/HSP包应用资源跨HAP/HSP包应用资源当bundle相同时，若要实现跨module访问，可以借助createModuleContext(context,moduleName)接口来创建同一应用中不同module的上下文。在成功获取到resourceManager对象之后，就能够调用不同的资源管理接口，进而对不同的资源进行访问操作。1添加依赖在entry的oh-package.json5文件中添加依赖："dependencies":{"library":"file:../library"}2通过[hsp].获取资源"hsp"指hsp模块名称；"type"代表资源类型；"name"为资源具体名称3使用变量获取资源hsp包名必须写在[]内，rawfile下有多层目录需从第一个目录开始写跨包访问代码示例添加依赖（oh-package.json5）：图3-4添加依赖通过[hsp].形式获取资源：Text($r('hsp.string.test_string')).fontSize($r('hsp.float.font_size')).color($r('hsp.color.font_color'))Image($rawfile('hsp.icon.png'))使用变量获取资源：text:string='[hsp].string_test_string';fontSize:string='[hsp].float_font_size';fontColor:string='[hsp].color_font_color';image:string='[hsp].media_string';rawfile:string='[hsp].icon_png';使用$r和$rawfile跨包访问hsp包资源无法提供编译时的资源校验，需要开发者自行保证使用资源存在于对应包中。3.4.3系统资源系统资源访问开发者若想获取系统支持的色彩、字体等资源ID，以及这些资源在不同配置下的具体取值，可以参考应用UX设计中关于资源的介绍文档。同时，开发者能够从主题图标库中获取支持的图标资源，并借助SymbolGlyph对图标颜色等属性做进一步设置。访问格式$r('sys.type.resource_name')sys：系统资源；type：资源类型（color/float/string/media/symbol）；resource_name：资源名称适用范围只有声明式开发范式才支持使用系统资源。系统预置应用推荐使用系统资源；第三方应用可根据需求选择。默认字体默认采用鸿蒙黑体（HarmonyOSSans），支持中文编码字符集GB18030—2022中的级别一和级别二。Text('Hello').fontColor($r('sys.color.ohos_id_color_emphasize')).fontSize($r('sys.float.ohos_id_text_size_headline1')).fontFamily($r('sys.string.ohos_id_text_font_family_medium')).backgroundColor($r('sys.color.ohos_id_color_palette_aux1'))3.5资源匹配资源匹配机制应用调用资源时，系统依据设备状态先在匹配的限定词目录搜索；若无匹配目录或未找到资源，再去base目录查找。rawfile目录资源不随设备状态筛选。3.5.1限定词目录与设备状态的匹配规则限定词目录匹配优先级从高到低依次为：移动国家码和移动网络码区域横竖屏设备类型颜色模式屏幕密度完全匹配原则若目录含移动国家码和移动网络码、语言等限定词，需所有取值与设备状态完全吻合才参与匹配。例如，"zh_CN-car-ldpi"不匹配"en_US"设备。屏幕密度匹配多个屏幕密度目录时，优先向上匹配最接近的，否则向下匹配。例如设备密度为"xxldpi"，存在"xldpi"和"xxldpi"两个目录，则匹配"xxldpi"。例3-3：创建资源以适配手机及平板电脑创建资源以适配手机及平板电脑（表3-6）：资源名称类型值（适配手机）值（适配平板电脑）hellostring你好!手机你好!平板text_widthinteger100400text_font_sizefloat20.0fp50.0fp新建项目Hello，在resources目录右击，选择"New→ResourceDirectory"创建资源目录。"Resourcetype"选择默认"element"；"Availablequalifiers"中选择"Locale"；"Language"选择"zh:Chinese"，地区选择"CN:China"；"Directoryname"自动生成"zh_CN"。图3-5创建手机资源目录创建平板资源目录再次在resources目录右击，选择"New→ResourceDirectory"。在已有Locale限定词基础上，再次选择"Device"，在设备选项中选择"Tablet"，"Directoryname"自动生成zh_CN-tablet。图3-6创建平板资源目录在zh_CN/Element目录右击，选择"New→ElementResourceFile"，填写"Filename"为"string"，"Rootelement"选择"string"。按同样步骤创建integer.json、float.json文件。图3-7创建资源文件手机与平板资源匹配效果Index.ets文件代码通过$r('app.string.hello')获取字符串资源作为文本内容；通过$r('eger.text_width')获取整数值资源作为文本组件的宽度；通过$r('app.float.text_font_size')获取浮点数值资源作为字体大小。手机和平板设备匹配对应的资源文件时，根据设备类型限定词资源目录进行匹配：手机对应zh_CN/Element资源目录平板对应zh_CN-tablet/Element资源目录图3-8编译运行左图手机效果，右图为平板效果3.5.2获取指定配置的资源开发者可在resource目录添加限定词目录，满足多语言、深浅色模式等系统设置需求。但受限定词目录匹配规则限制，系统仅获取与当前设备状态最匹配的资源，无法获取其他目录资源。若需获取特定配置资源，可使用以下接口：接口名描述getOverrideResourceManager(configuration?:Configuration):ResourceManager获取可以加载指定配置资源的资源管理对象，使用同步方式返回getOverrideConfiguration():Configuration获取指定的配置，使用同步方式返回updateOverrideConfiguration(configuration:Configuration):void更新指定的配置例3-4：获取不同语言资源新建项目Language，在resources目录创建中文、英文、德文资源目录和文件：entry/src/main/resources/zh_CN/element/string.jsonentry/src/main/resources/en_US/element/string.jsonentry/src/main/resources/de_DE/element/string.json创建步骤选择"New→ResourceFile"，"Filename"填写"string"；"Resourcetype"选择"Element"；"Rootelement"选择"string"；"Availablequalifiers"中选择"Locale"。图3-9选择限定词选择语言和地区"Language"选择"zh:Chinese"，右侧选择"SpecificRegiononly"，选择地区"CN:China"。英文和德文按同样步骤创建。图3-10选择语言和地区多语言资源运行效果在Index.ets中，分别获取三种语言的资源并显示在文本框中。运行设备当前系统语言为中文，通过getOverrideResourceManager接口获取其他语言配置的资源。图3-11运行效果——同时显示中文"你好,世界"和德文"Hello,Welt"该示例展示了即使设备当前系统语言为中文，通过指定配置的资源管理接口，仍然可以获取到英文和德文的资源内容，实现了跨语言资源的灵活访问。3.5.3overlay机制overlay是一种资源替换机制。考虑到不同品牌、产品具有不同的显示风格，开发者无须重新打包业务逻辑hap，仅通过配置和使用overlay资源包，即可实现应用界面风格的切换。overlay资源包内容仅包含资源文件、资源索引文件以及配置文件核心优势无须重新打包业务逻辑hap，即可切换应用界面风格适用场景不同品牌、产品的差异化显示风格定制任务实施任务实施：自定义应用图标和界面图片（一）实施思路1导入资源新建项目Resource1，在entry/src/main/resources/base/media目录下导入需要作为应用图标的图片greens4.png和构成界面的图片greens.png2配置文件设置查看src/main/module.json5配置文件。"icon":"$media:layered_image"引用media目录下的图像资源设置应用图标；"label":"$string:EntryAbility_label"引用字符串资源设置应用名称。修改layered_image图像资源文件和string.json字符串资源文件。3构建页面修改entry/src/main/ets/pages/Index.ets文件，引用资源文件构建页面（二）任务代码修改layered_image.json将"foreground"前景图片设置为引入的图标图片greens4.png："layered-image":{"background":"$media:background","foreground":"$media:greens4"}修改string.json设置应用名称为"青菜"：{"name":"EntryAbility_label","value":"青菜"}修改Index.ets代码定义了8个带有边框的图像组件，图像资源为greens，存放在项目的r