第22篇｜资源命名：nav_*.png、mock 图、SVG 如何服务文章截图
这篇专门补一个容易被忽略的工程点：资源命名。文章截图好不好看，当然和设计有关；但截图能不能长期维护，主要看资源能不能被代码、文档和发布链路稳定找到。
本文不讨论抽象命名偏好，而是用当前工程里的真实目录、真实$r('app.media.xxx')引用和发布后的正文截图来验证。目标是让读者知道：一个图标从base/media到 ArkTS 页面，再到 CSDN 和开发者社区，应该怎样保持同一个业务语义。
配图说明：这张图展示了第 5 天导航资源的成对关系，以及ok pair检查输出。它是本文的主图，不再复用首页地图截图。
官方依据
官方文档《资源分类与访问》说明，应用开发会使用字符串、颜色、字体、间距、图标等资源，开发者可以通过资源文件管理不同设备或配置下的表现。项目里的资源集中在entry/src/main/resources/base/media，命名已经形成了几类规则。
第 5 天涉及的导航资源已经形成nav_业务.png与nav_业务_active.png的成对关系，演示素材集中使用mock_业务_场景.png，工具图标使用icon_功能.svg。这不是单纯的命名偏好，而是为了让 ArkTS 代码、截图说明、CSDN 正文和开发者社区正文都能回到同一份工程资源。
高质量命名的验收标准
本文按四条依据判断资源命名是否可靠：
| 验收项 | 判断方式 | 本文证据 |
|---|---|---|
| 官方依据 | HarmonyOS 官方《资源分类与访问》说明资源可按类型管理，并在代码中通过资源引用访问 | app.media.xxx引用方式 |
| 目录依据 | 资源必须真实存在于entry/src/main/resources/base/media | 下文列出当前目录清单 |
| 代码依据 | 页面只通过统一函数引用导航资源 | Index.ets的buildNavIconMark(tab) |
| 发布依据 | 本地 Markdown、CSDN、开发者社区都能说明同一组资源来源 | 文章截图和正文统一描述nav_*、mock_*、icon_* |
这样写的目的，是让读者能复查：资源在哪里、在哪段 ArkTS 代码里被引用、替换时需要保持哪些命名关系。
配图说明：资源不是只服务编译。它会从工程目录流向 ArkTS 页面、文章截图、CSDN 和开发者社区，所以命名必须稳定。
资源目录先分三类
当前和第 5 天关系最密切的资源可以分成三类：导航入口、演示素材、轻量工具图标。先分清类型，再谈命名。
配图说明：nav_、mock_、icon_三类资源各有边界，排查时不要混在同一个命名池里。
当前资源目录里可以看到这些文件：
nav_camera.png nav_camera_active.png nav_gallery.png nav_gallery_active.png nav_map.png nav_map_active.png nav_vault.png nav_vault_active.png mock_camera_preview_thumb.png mock_gallery_feature_city.png mock_map_background.png mock_map_pin_city.png icon_locate_current.svg icon_smart_action.svg这些名字都服务明确职责。nav_表示导航图标，_active表示选中态；mock_表示用于演示和截图的数据素材；icon_表示轻量功能图标。命名一眼能看出用途，后续写文章、截屏、换图、排查资源缺失都会轻很多。
在工程里如何定位资源
如果只看正文，很容易把资源命名当成写作规范。实际它首先是工程规范：文件必须在资源目录里，代码引用的名称必须和文件名对应，截图说明也要能回到同一组资源。
配图说明：目录结构图用于定位entry/src/main/resources/base/media。读者可以按这个路径回到工程里核对真实资源。
导航图标在buildNavIconMark(tab)中集中引用：
if (tab === 'camera') { Image(this.isActiveTab(tab) ? $r('app.media.nav_camera_active') : $r('app.media.nav_camera')) } else if (tab === 'gallery') { Image(this.isActiveTab(tab) ? $r('app.media.nav_gallery_active') : $r('app.media.nav_gallery')) }这里有两个好处：
- 资源名和业务 Tab 对齐，看到
nav_vault_active就知道是保险箱选中态。 - 底部导航和侧边导航共用
buildNavIconMark()，不需要两套图标映射。
如果后续要替换视觉，只要保证nav_业务_active.png和nav_业务.png成对存在，代码不需要改。
mock 图为什么也要规范命名
训练营文章需要大量截图。如果截图直接依赖临时相册或真机随机照片，别人很难复现同样效果。项目用mock_*资源做稳定演示素材，例如地图背景、地图记忆点、相册封面和相机预览缩略图。
这类素材的命名建议遵循：
mock_map_*：地图页演示素材，如背景、Pin。mock_gallery_*：相册页演示素材，如城市、草地、湖景。mock_camera_*：相机页演示素材，如预览缩略图。mock_video_*：视频或动态图能力演示素材。
这样写文章时可以直接说明截图来源，读者也能在工程里复现。
PNG 和 SVG 怎么选
项目里导航图标使用 PNG，icon_locate_current.svg、icon_smart_action.svg使用 SVG。一个实用判断是：
- 需要复杂色彩、发光、质感或和设计稿完全一致的图标，用 PNG。
- 单色线性、可缩放、轻量功能入口，用 SVG。
官方资源机制支持通过$r('app.media.xxx')访问媒体资源，所以重点不是“只能用哪一种格式”，而是资源名称和使用场景要稳定。
代码验证：底部和侧边共用同一套资源
第 20 篇和第 21 篇分别讲了底部导航和侧边导航。它们的共同点是都调用buildNavIconMark(tab)：
private buildNavIconMark(tab: string) { Stack({ alignContent: Alignment.Center }) { if (tab === 'camera') { Image(this.isActiveTab(tab) ? $r('app.media.nav_camera_active') : $r('app.media.nav_camera')) } else if (tab === 'gallery') { Image(this.isActiveTab(tab) ? $r('app.media.nav_gallery_active') : $r('app.media.nav_gallery')) } } }这说明资源命名不是只服务某一个组件，而是服务“导航系统”。只要nav_*成对存在，底部导航和侧边导航都能同步获得默认态和选中态。
代码验证：实际资源清单
这篇文章不是凭命名习惯下结论，而是直接用当前工程目录验证。执行：
Get-ChildItem entry/src/main/resources/base/media -File | Where-Object { $_.Name -match '^(nav_|mock_)' } | Sort-Object Name | Select-Object -ExpandProperty Name当前输出里和第 5 天相关的资源包括：
mock_camera_preview_thumb.png mock_gallery_feature_city.png mock_gallery_grass.png mock_gallery_misty_peak.png mock_gallery_sunset_lake.png mock_map_background.png mock_map_pin_city.png mock_map_pin_forest.png mock_map_pin_lake.png nav_camera.png nav_camera_active.png nav_gallery.png nav_gallery_active.png nav_map.png nav_map_active.png nav_vault.png nav_vault_active.png这个清单能验证三件事：第一，四个导航入口都有默认态和选中态；第二，地图页不是临时依赖一张外部图片，而是有mock_map_background和不同城市、森林、湖泊 Pin 资源；第三，相册和相机演示素材也已经按业务前缀归类。
发布链路里的命名价值
训练营文章会同时存在三种地址：本地 Markdown、CSDN 正文、开发者社区正文。本地 Markdown 可以写../assets/screenshots/web/resource-naming-check.png，但线上平台必须使用可访问的图片 URL；应用运行时又通过$r('app.media.xxx')访问工程资源。
| 使用位置 | 访问方式 | 稳定性要求 |
|---|---|---|
| ArkTS 页面 | $r('app.media.nav_camera') | 资源名不能随意改 |
| 本地教程 | ../assets/screenshots/web/resource-naming-check.png | 相对路径要能在仓库里打开 |
| CSDN/社区 | https://i-blog.csdnimg.cn/... | 发布后图片必须公网可见 |
也就是说，资源命名不是只服务编译，它还服务文章截图、平台同步和后续复查。只要资源名称稳定，哪怕线上图片地址发生变化，读者仍然可以回到工程目录里定位真实资源。
资源缺失时怎么排查
如果页面显示空白或图标不对，可以按这个顺序查：
- 先确认文件是否在
entry/src/main/resources/base/media。 - 再确认文件名是否和
$r('app.media.xxx')中的xxx完全一致。 - 然后确认默认态和
_active是否成对。 - 最后确认文章截图引用的是发布后的图片地址，还是本地相对路径。
本地文档可以用../assets/screenshots/web/resource-naming-check.png，但 CSDN 和开发者社区最终需要可访问的图片地址。这里也是资源命名的重要性：本地素材、文章截图、应用资源各自有边界，不能混成一套。
最小检查脚本
如果要把这套规则固化，可以先用一个简单脚本找出未成对的导航资源：
$media = Get-ChildItem entry/src/main/resources/base/media -File $names = $media | ForEach-Object { $_.BaseName } 'map','camera','gallery','vault' | ForEach-Object { $normal = "nav_$_" $active = "nav_${_}_active" if ($names -notcontains $normal -or $names -notcontains $active) { Write-Host "missing pair: $_" } }本文在当前仓库执行这段检查，输出为：
ok pair: map ok pair: camera ok pair: gallery ok pair: vault这说明四个主导航入口都同时具备默认态和选中态。文章结论不是凭经验写的，而是由目录清单、ArkTS 引用和检查脚本共同验证。
小结
资源命名是文档质量的一部分。命名清楚，文章就能准确解释“这张截图来自哪个资源、这个图标在哪段代码里被引用、后续替换要改哪里”。
第 5 天的导航和首页截图之所以能串起来，靠的不是一堆截图，而是nav_*、mock_*、icon_*这套稳定的资源语言。
参考依据：
- 华为开发者文档：《资源分类与访问》
- 项目资源目录：
entry/src/main/resources/base/media - 项目源码：
entry/src/main/ets/pages/Index.ets
