企业官网建设流程全解析

前言

前面我们大量用 Emoji（🐱、🔥、🏆）做图标——简单但不专业。真正的游戏需要 PNG/JPG/SVG 图集：猫咪精灵图、UI 图标、背景插画。HarmonyOS 加载图片资源有两条路径——$r()引用编译期资源和**$rawfile()引用原始文件**。两者用法、性能、适用场景完全不同。

本篇以「猫猫大作战」图标资源加载为锚点，把$r与$rawfile的区别、资源目录结构、多分辨率适配三大要点讲透。

提示：本系列不讲 ArkTS 基础语法与环境搭建，假设你已跟完第 1–26 篇。本篇是布局进阶的第七篇。

一、场景拆解：图标资源加载

回顾「猫猫大作战」主菜单标题图标（第 1 篇）：

// 来源：entry/src/main/ets/pages/Index.ets MainMenuView() Text('🐱').fontSize(72)

这是用 Emoji 文字做图标。现在想换成专业的 PNG 图标cat_logo.png——需要 Image 组件 + 资源引用：

// 写法 1：$r() 引用编译期资源（推荐） Image($r('app.media.cat_logo')) .width(72).height(72) // 写法 2：$rawfile() 引用原始文件 Image($rawfile('icons/cat_logo.png')) .width(72).height(72)

关键区别：

二、$r 编译期资源引用

2.1 资源目录结构

entry/src/main/resources/ ├─ base/ # 默认资源（所有设备匹配） │ ├─ element/ # string.json, color.json, float.json │ ├─ media/ # 图片、音频、视频 │ │ ├─ cat_logo.png │ │ ├─ icon_pause.png │ │ └─ bg_main.jpg │ └─ profile/ # 自定义 JSON 配置 ├─ zh_CN/element/ # 中文语言覆盖 ├─ en_US/element/ # 英文语言覆盖 ├─ dark/element/ # 暗色模式覆盖 └─ rawfile/ # 原始文件（不编译） └─ icons/cat_logo.png

2.2 $r 三种资源类型

// 1. media：图片/音频/视频 Image($r('app.media.cat_logo')) // 2. string：字符串 Text($r('app.string.hello_world')) // 3. color/float：颜色/尺寸 Text('A').fontColor($r('app.color.primary')) Text('B').fontSize($r('app.float.title_size'))

关键经验：$r('app.<type>.<name>')引用资源——type是media/string/color/float/plural等，name是资源名（不含扩展名）。

2.3 命名规则

// ✅ 合法资源名 $r('app.media.cat_logo') // 蛇形命名 $r('app.media.icon_pause') $r('app.string.hello_world') // ❌ 非法资源名 $r('app.media.catLogo') // 驼峰，ArkTS 不允许 $r('app.media.cat-logo') // 含连字符 $r('app.media.cat logo') // 含空格

提示：HarmonyOS 资源名必须蛇形命名（snake_case）——驼峰会编译报错。

2.4 多分辨率适配

HarmonyOS 自动按设备密度加载对应 dpi 的图片：

resources/ ├─ base/media/cat_logo.png # 默认（mdpi 1x） ├─ fiberscale-2x/media/cat_logo.png # 2x 高分辨率 └─ fiberscale-3x/media/cat_logo.png # 3x 超高分辨率

实战经验：UI 图标准备 1x、2x、3x 三套——分别放在base/media、fiberscale-2x/media、fiberscale-3x/media，系统自动选最清晰的。

三、$rawfile 原始文件引用

3.1 适用场景

// 1. Lottie 动效 JSON Image($rawfile('lottie/loading.json')) // 2. 自定义字体 TTF Font().registerFont({ familyName: 'Custom', familySrc: $rawfile('fonts/Custom.ttf') }) // 3. 大型背景图（不想编译处理） Image($rawfile('bg/level_1.jpg')) // 4. 配置 JSON 文件 const config = fs.readSync($rawfile('config/game.json'))

3.2 路径规则

$rawfile('icons/cat_logo.png') // 相对 resources/rawfile/ 的路径 // 完整路径：resources/rawfile/icons/cat_logo.png

关键经验：$rawfile路径必须包含扩展名——与$r省略扩展名不同。

3.3 $rawfile vs $r 的核心差异

实战经验：能用 $r 就用 $r——编译期校验、多端适配都免费。只有 Lottie 动效、自定义字体这种「非标准资源」才用 $rawfile。

四、用 $r 改造主菜单图标

4.1 替换标题 Emoji 为 PNG 图标

假设已放置resources/base/media/cat_logo.png：

@Builder MainMenuView() { Column() { Spacer().height('15%') // 改造：Emoji → $r PNG 图标 Image($r('app.media.cat_logo')) .width(72) .height(72) .margin({ bottom: 8 }) Text('猫猫大作战').fontSize(36).fontWeight(FontWeight.Bold).fontColor('#2C3E50').margin({ bottom: 8 }) Text('合并进化 · 策略消除').fontSize(16).fontColor('#95A5A6').margin({ bottom: 48 }) if (this.highScore > 0) { Row() { // 改造：🏆 Emoji → $r PNG 奖杯图标 Image($r('app.media.icon_trophy')) .width(20).height(20) Text(` 最高分: ${this.highScore}`).fontSize(16).fontColor('#F1C40F').fontWeight(FontWeight.Bold) }.margin({ bottom: 32 }) } // 开始游戏按钮 Button('开始游戏') .width('70%').height(56) .fontSize(20).fontWeight(FontWeight.Bold) .fontColor('#FFFFFF').backgroundColor('#2ECC71') .borderRadius(28) .shadow({ radius: 8, color: 'rgba(46, 204, 113, 0.4)', offsetY: 4 }) .onClick(() => { this.startGame(); }) Spacer().height(24) // 规则面板（第 25 篇） Scroll() { /* ... */ }.height(180) Spacer() } .width('100%').height('100%') .linearGradient({ direction: GradientDirection.Bottom, colors: [['#E8F4F8', 0.0], ['#D6EEF5', 0.5], ['#C9E8F2', 1.0]] }) .alignItems(HorizontalAlign.Center) }

4.2 Image 组件常用属性

Image($r('app.media.cat_logo')) .width(72).height(72) // 尺寸 .objectFit(ImageFit.Contain) // 缩放模式 .borderRadius(12) // 圆角 .interpolation(ImageInterpolation.High) // 高质量插值 .draggable(false) // 禁止拖拽 .alt($r('app.media.placeholder')) // 加载失败占位图

4.3 objectFit 缩放模式

实战经验：UI 图标用 Contain——保证图标完整不变形；全屏背景用 Cover——填满屏幕不裁剪主体。

五、资源访问的编程式 API

5.1 resourceManager 获取资源

import { common } from '@kit.AbilityKit'; const context = getContext(this) as common.UIAbilityContext; const resMgr = context.resourceManager; // 同步获取字符串 const str: string = resMgr.getStringSync($r('app.string.hello_world').id); // 同步获取颜色 const color: number = resMgr.getColorSync($r('app.color.primary').id); // 异步获取 rawfile 文件描述符 const rawFd = await resMgr.getRawFd('config/game.json'); // rawFd = { fd, offset, length }

5.2 getStringByNameSync 按名取值

// 按资源名（不含 app. 前缀）取字符串 const greeting: string = resMgr.getStringByNameSync('hello_world');

实战经验：UI 层用$r()直接渲染，逻辑层用resourceManager取值——例如要把字符串塞进 ArrayBuffer 时。

六、踩坑提示

6.1 资源名拼错

// ❌ 错误：拼写错误，编译报错 Image($r('app.media.cat_Logo')) // L 大写 Image($r('app.media.catlogo')) // 缺下划线 // ✅ 正确：与文件名完全一致（蛇形） Image($r('app.media.cat_logo'))

6.2 $r 引用 rawfile 资源

// ❌ 错误：$r 不能引用 rawfile 下的文件 Image($r('app.media.cat_logo')) // 但 cat_logo.png 在 rawfile/icons/ 下 // ✅ 正确：rawfile 用 $rawfile Image($rawfile('icons/cat_logo.png'))

6.3 多分辨率图片缺失

# ❌ 只有 3x 图，1x 设备加载 3x 图缩放，模糊 resources/base/media/ # 空 resources/fiberscale-3x/media/cat_logo.png # ✅ 至少提供 1x 和 3x resources/base/media/cat_logo.png # 1x resources/fiberscale-3x/media/cat_logo.png # 3x

6.4 Image 不设宽高

// ❌ 错误：不设尺寸，Image 按图片原始像素渲染，可能撑爆屏幕 Image($r('app.media.cat_logo')) // ✅ 正确：显式设尺寸 Image($r('app.media.cat_logo')).width(72).height(72)

七、调试技巧

1. DevEco 资源预览：resources/base/media/下的图片在 IDE 里直接预览。
2. console.info打资源 id：$r('app.media.cat_logo').id打 log，追资源加载。
3. 图片不显示排查：检查资源名拼写；检查文件是否在media/或rawfile/；检查 Image 宽高是否设。
4. 模糊排查：1x 设备加载 3x 图会缩放模糊，补全多分辨率资源。

八、性能与最佳实践

1. UI 图标用 $r——编译期校验、多分辨率适配免费。
2. **Lottie/字体/大文件用rawfile**——r 不支持非标准资源。
3. 资源名蛇形命名——驼峰会编译报错。
4. 多分辨率准备 1x/2x/3x——避免高 dpi 设备加载低清图模糊。
5. Image 必须设宽高——不设按原始像素渲染，可能撑爆屏幕。
6. UI 图标 objectFit 用 Contain——保证完整不变形。

总结

本篇我们从 Image 资源引用切入，掌握了**r 编译期资源（多语言/多分辨率/暗色自动适配）**、**rawfile 原始文件（Lottie/字体/大文件）、资源目录结构与命名规则三大要点，并给出了主菜单 PNG 图标改造完整代码。核心要点：r 编译期校验+多端适配；rawfile 任意文件；资源名蛇形命名；UI 图标准备 1x/2x/3x 三套**。

下一篇我们将拆解暗色模式适配——深色资源与 colorMode。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

• 「猫猫大作战」项目源码：本仓库entry/src/main/ets/pages/Index.ets
• Image 组件官方指南
• 资源引用 $r 与 $rawfile 官方指南
• 资源目录结构官方文档
• 多分辨率资源适配最佳实践
• 开源鸿蒙跨平台社区
• HarmonyOS 开发者官方文档首页
• 系列索引：本仓库articles/INDEX.md