第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'))
}

这里有两个好处：

1. 资源名和业务 Tab 对齐，看到 nav_vault_active 就知道是保险箱选中态。
2. 底部导航和侧边导航共用 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/...	发布后图片必须公网可见

也就是说，资源命名不是只服务编译，它还服务文章截图、平台同步和后续复查。只要资源名称稳定，哪怕线上图片地址发生变化，读者仍然可以回到工程目录里定位真实资源。

资源缺失时怎么排查

如果页面显示空白或图标不对，可以按这个顺序查：

1. 先确认文件是否在 entry/src/main/resources/base/media。
2. 再确认文件名是否和 $r('app.media.xxx') 中的 xxx 完全一致。
3. 然后确认默认态和 _active 是否成对。
4. 最后确认文章截图引用的是发布后的图片地址，还是本地相对路径。

本地文档可以用 ../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