HarmonyOS NEXT 企业级记账APP：创建工程与企业级目录结构设计

最爱老式锅包肉

279人浏览 · 2026-07-28 21:58:13

最爱老式锅包肉 · 2026-07-28 21:58:13 发布

创建工程与企业级目录结构设计

本文是《HarmonyOS NEXT 企业级开发实战：30篇打造智能记账APP》系列的第 02 篇，对应 Git Tag v0.0.2。承接第 01 篇的项目规划，本篇手把手创建 HarmonyLedger 工程骨架，搭建符合企业级规范的目录结构与基础配置，并建立完整的 SVG 矢量图标体系。

前言

HarmonyOS NEXT 应用工程的创建是项目落地的第一步。很多开发者习惯使用 DevEco Studio 的可视化向导一键创建工程，却忽略了目录结构对企业级项目的重要性。一个良好的目录结构可以让代码 更易维护、更易扩展、更易协作。

本文将带你：

使用 DevEco Studio 创建 HarmonyLedger 工程
搭建 MVVM + Repository 架构目录
完善基础配置文件（build-profile.json5、oh-package.json5、module.json5）
建立包含 33 个图标的 SVG 矢量图标体系
初始化 Git 仓库并提交首个正式版本

企业级核心原则：目录结构必须 一次设计、长期稳定，禁止后期随意修改。资源体系同样需要在项目初期统一规划，避免后期返工。参考 HarmonyOS 工程结构规范了解官方约定。

一、工程创建流程

1.1 DevEco Studio 创建工程

打开 DevEco Studio，通过向导创建新工程：

File → New → Create Project
选择 Ability（Empty Ability） 模板
填写工程信息：

参数	值	说明
Project name	HarmonyLedger	工程名（驼峰式）
Bundle name	com.example.harmonyledger	包名（反域名）
Save location	~/HarmonyOS/	工程存放目录
Compile SDK	5.0.0 (API 12)	编译 SDK 版本
Model	Stage	应用模型（NEXT 仅支持 Stage）
Language	ArkTS	开发语言
Device type	Phone	目标设备类型

点击 Finish，等待 Gradle 同步完成

在这里插入图片描述

1.2 验证工程创建

工程创建完成后，DevEco Studio 会自动打开项目。验证关键文件是否齐全：

# 工程根目录关键文件
HarmonyLedger/
├── AppScope/app.json5              # 应用级配置
├── entry/                          # 主模块
│   ├── build-profile.json5          # 模块构建配置
│   ├── oh-package.json5             # 模块依赖配置
│   └── src/main/module.json5        # 模块配置
│   └── src/main/ets/                # ArkTS 源码目录
└── build-profile.json5             # 工程构建配置

常见问题：如遇 Gradle 同步失败，检查 File → Project Structure → Project 中的 SDK 版本是否匹配。参考 DevEco Studio 故障排查。

二、企业级目录结构设计

2.1 完整目录树

HarmonyLedger 在 DevEco Studio 默认目录基础上，扩展出 MVVM + Repository 架构所需的分层目录：

HarmonyLedger/
├── AppScope/                         # 应用级配置（跨模块共享）
│   ├── app.json5                     # 应用元数据
│   └── resources/
│       ├── base/                       # 默认资源
│       │   ├── element/              # 字符串、颜色等
│       │   └── media/               # 图片、图标
│       └── profile/                    # 应用级配置
│
├── entry/                            # 主模块（HarmonyLedger 入口）
│   └── src/main/
│   │   ├── ets/                      # ArkTS 源码根目录
│   │   │   ├── pages/                # 页面层（View）
│   │   │   ├── components/           # 公共组件
│   │   │   ├── viewmodel/            # 视图模型层（ViewModel）
│   │   │   ├── repository/           # 数据访问层（Repository）
│   │   │   ├── model/                # 数据模型层（Model）
│   │   │   ├── service/              # 业务服务层
│   │   │   ├── database/             # 数据库封装
│   │   │   ├── router/               # 路由管理
│   │   │   ├── utils/                # 工具类
│   │   │   ├── theme/                # 主题资源
│   │   │   ├── constants/            # 常量定义
│   │   │   ├── common/               # 公共能力
│   │   │   ├── entryability/         # Ability 入口
│   │   │   ├── entrybackupability/   # 备份 Ability
│   │   │   └── ...                   #（其他 Ability）
│   │   ├── resources/                # 模块资源
│   │   └── module.json5             # 模块配置
│   ├── build-profile.json5           # 模块构建配置
│   └── oh-package.json5             # 模块依赖
│
├── docs/                             # 项目文档
│   ├── Project-Design.md             # 产品设计文档
│   └── articles/                     # 30 篇系列博客
│
├── deveco-skills/                    # DevEco 开发技能包
│
├── build-profile.json5               # 工程构建配置
├── hvigorfile.ts                     # 构建脚本
├── oh-package.json5                  # 工程级依赖
├── README.md                         # 项目说明
├── CHANGELOG.md                      # 更新日志
└── .gitignore                        # Git 忽略配置

2.2 分层目录职责

目录	职责	命名规范
`pages/`	页面视图，对应一个完整页面	大驼峰，如 `HomeView.ets`
`components/`	可复用 UI 组件	大驼峰，按功能分子目录
`viewmodel/`	视图模型，处理业务逻辑	大驼峰 + VM 后缀，如 `HomeViewModel`
`repository/`	数据访问层，屏蔽存储细节	大驼峰 + Repository 后缀
`model/`	数据实体定义	大驼峰，与领域对象对应
`service/`	跨页面业务服务	大驼峰 + Service 后缀
`database/`	数据库连接、表定义	小写，如 `db.ets`
`router/`	路由表、跳转封装	小写，如 `router.ets`
`utils/`	工具类	大驼峰 + Util 后缀
`theme/`	颜色、字号、间距常量	小写，如 `colors.ets`
`constants/`	应用常量	小写，如 `app.ets`
`common/`	公共能力（无明确归属）	小写，如 `base.ets`

设计要点：每个目录职责单一，禁止跨目录存放无关文件。这是保证代码可维护性的基础。

三、配置文件详解

3.1 AppScope/app.json5

应用级元数据配置，所有模块共享：

{
  "app": {
    "bundleName": "com.example.harmonyledger",
    "vendor": {
      "name": "HarmonyLedger Team",
      "homepage": "https://gitcode.com/qiaomu8559968/HarmonyLedger.git"
    },
    "versionCode": 1,
    "versionName": "1.0.0",
    "minAPIVersion": 12,
    "targetAPIVersion": 12,
    "apiReleaseType": "Release",
    "debug": false
  }
}

字段	说明	示例值
`bundleName`	应用包名（唯一标识）	`com.example.harmonyledger`
`versionCode`	版本号（数字，递增）	`1`
`versionName`	版本名（展示用）	`"1.0.0"`
`minAPIVersion`	最低 API 版本	`12`
`targetAPIVersion`	目标 API 版本	`12`

3.2 entry/src/main/module.json5

主模块配置，声明 Ability、路由、权限：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "HarmonyLedger 主入口模块",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "HarmonyLedger 入口 Ability",
        "label": "$string:EntryAbility_label",
        "icon": "$media:icon",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background"
      }
    ],
    "extensionAbilities": [],
    "requestPermissions": [
      { "name": "ohos.permission.READ_MEDIA" },
      { "name": "ohos.permission.WRITE_MEDIA" }
    ]
  }
}

3.3 build-profile.json5（工程级）

工程构建配置，指定 SDK、签名、产物：

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS",
        "targetSdkVersion": "6.1.1(24)"
      }
    ],
    "buildModeSet": [
      { "name": "debug" },
      { "name": "release" }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": ["default"]
        }
      ]
    }
  ]
}

参考 build-profile.json5 规范了解更多构建配置项。

四、Ability 与入口页面

4.1 EntryAbility.ets

应用入口 Ability，负责加载首个页面与生命周期管理：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

const DOMAIN = 0x0000;
const TAG = 'EntryAbility';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(DOMAIN, TAG, 'onCreate: HarmonyLedger 启动');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/HomeView', (err) => {
      if (err.code) {
        hilog.error(DOMAIN, TAG, `loadContent failed: ${err.message}`);
        return;
      }
      hilog.info(DOMAIN, TAG, 'loadContent success: pages/HomeView');
    });
  }

  onWindowStageDestroy(): void {
    hilog.info(DOMAIN, TAG, 'onWindowStageDestroy');
  }

  onDestroy(): void {
    hilog.info(DOMAIN, TAG, 'onDestroy');
  }

  onForeground(): void {
    hilog.info(DOMAIN, TAG, 'onForeground');
  }

  onBackground(): void {
    hilog.info(DOMAIN, TAG, 'onBackground');
  }
}

4.2 入口页面 HomeView.ets

创建一个最简首页占位，后续版本逐步完善：

@Entry
@Component
struct HomeView {
  @State message: string = 'HarmonyLedger 鸿蒙记账';

  build() {
    Column() {
      Text(this.message)
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ top: 100 })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .alignItems(HorizontalAlign.Center)
  }
}

4.3 路由配置 main_pages.json

页面路由注册，所有可跳转页面必须在此声明：

{
  "src": [
    "pages/HomeView"
  ]
}

关键约束：EntryAbility 的 loadContent('pages/HomeView') 路径必须出现在 main_pages.json 的 src 数组中，否则会白屏。这是鸿蒙开发最常见的踩坑点。

五、SVG 矢量图标体系

5.1 为什么选择 SVG 而非 PNG

HarmonyLedger 项目初期使用的是 DevEco Studio 自动生成的占位 PNG 图标，每个文件仅 70 字节，是一个透明占位图，完全无法用于实际界面。这种占位图存在以下问题：

模糊失真：PNG 位图在不同分辨率设备上缩放后会出现锯齿
无法变色：PNG 不支持 fillColor 动态着色，深色模式需要维护两套图标
体积冗余：每个图标需要提供多套分辨率（1x/2x/3x），资源体积膨胀
维护困难：修改图标颜色需要重新导出所有分辨率的 PNG

因此 HarmonyLedger 将全部图标从 PNG 占位符替换为 SVG 矢量图标，共计 33 个 SVG 文件，统一存放在 entry/src/main/resources/base/media/ 目录下。

5.2 SVG 图标的优势

对比项	PNG 位图	SVG 矢量图
缩放表现	锯齿失真	无损任意缩放
文件体积	多分辨率膨胀	单文件，体积小
动态变色	不支持 `fillColor`	支持 `fillColor` 动态着色
深色模式	需两套资源	单套资源 + `fillColor`
维护成本	高（多分辨率）	低（单文件）
ArkUI 支持	`$r('app.media.xxx')`	`$r('app.media.xxx')` 同样支持

关键技术点：ArkUI 的 Image 组件原生支持 SVG 格式，通过 $r('app.media.icon_xxx') 引用 SVG 文件与引用 PNG 完全一致。fillColor() 方法可以动态修改 SVG 中 stroke 或 fill 属性的颜色，实现图标随主题变色。

5.3 图标分类体系

HarmonyLedger 的 33 个 SVG 图标按功能分为 7 大类：

类别	图标	数量
导航/操作	icon_back, icon_arrow_right, icon_add, icon_clear, icon_delete, icon_search, icon_more	7
收支	icon_expense, icon_income	2
状态	icon_empty, icon_default	2
时间	icon_calendar, icon_clock	2
分类	icon_category_food, icon_category_transport, icon_category_shopping 等	13
Tab栏	icon_tab_home, icon_tab_chart, icon_tab_budget, icon_tab_user	4
应用图标	background, foreground, startIcon	3
合计		33

5.4 导航与操作图标

导航和操作类图标用于页面间的返回、跳转以及通用操作：

<!-- icon_back.svg：返回箭头 -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96">
  <path d="M66 48 L30 48 M44 30 L30 48 L44 66" stroke="#333" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
</svg>

<!-- icon_add.svg：新增加号 -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96">
  <path d="M48 20 L48 76 M20 48 L76 48" stroke="#333" stroke-width="6" stroke-linecap="round"/>
</svg>

<!-- icon_delete.svg：删除垃圾桶 -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96">
  <path d="M28 32 L68 32 M36 32 L36 24 L60 24 L60 32 M32 32 L32 72 L64 72 L64 32" stroke="#333" stroke-width="5" stroke-linecap="round" fill="none"/>
</svg>

5.5 收支图标

收支类图标用于区分支出和收入操作：

<!-- icon_income.svg：收入向上箭头 -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96">
  <path d="M48 60 L48 20 M30 38 L48 20 L66 38" stroke="#333" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
</svg>

5.6 分类图标

分类图标是数量最多的一组，用于账单分类的视觉标识。每个分类对应一个专属图标：

<!-- icon_category_food.svg：餐饮图标（碗筷造型） -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96">
  <path d="M30 68 L30 44 Q30 28 42 28 Q54 28 54 44 L54 68 M60 68 L60 36 Q60 28 66 28 L66 68" stroke="#333" stroke-width="5" stroke-linecap="round" fill="none"/>
</svg>

5.7 Tab 栏图标

Tab 栏图标用于底部导航栏的四个主页面入口：

<!-- icon_tab_home.svg：首页房屋图标 -->
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96">
  <path d="M48 16 L76 40 L68 40 L68 68 L28 68 L28 40 L20 40 Z" stroke="#333" stroke-width="5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
</svg>

5.8 完整分类图标清单

分类名称	图标文件	类型	用途
餐饮	icon_category_food	支出	食物消费
交通	icon_category_transport	支出	出行费用
购物	icon_category_shopping	支出	日用消费
娱乐	icon_category_entertainment	支出	休闲消费
房租	icon_category_housing	支出	居住费用
医疗	icon_category_medical	支出	健康消费
教育	icon_category_education	支出	学习投入
默认	icon_category_default	通用	新增分类默认图标
工资	icon_category_salary	收入	薪资收入
奖金	icon_category_bonus	收入	额外奖金
投资	icon_category_investment	收入	投资收益
礼金	icon_category_gift	收入	礼金收入
退款	icon_category_refund	收入	退款返还

六、SVG 图标设计规范

6.1 统一画布尺寸

所有功能图标（非应用图标）统一采用 96x96 的 viewBox 画布：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96">
  <!-- 图标路径 -->
</svg>

应用图标（background、foreground、startIcon）采用 256x256 的 viewBox 画布，以适配高分辨率启动屏需求。

6.2 stroke 描边风格

HarmonyLedger 的 SVG 图标统一采用 stroke 描边风格 而非 fill 填充风格，这是整个图标体系的核心设计语言：

<!-- 描边风格：使用 stroke 属性绘制轮廓 -->
<path d="..." stroke="#333" stroke-width="5" stroke-linecap="round" fill="none"/>

属性	值	说明
`stroke`	`#333`	描边颜色，统一深灰色作为基准色
`stroke-width`	`5` 或 `6`	描边宽度，功能图标 5-6px
`stroke-linecap`	`round`	线段端点圆角
`stroke-linejoin`	`round`	线段连接圆角
`fill`	`none`	不填充内部区域

设计哲学：统一使用 stroke 描边风格可以让所有图标视觉语言一致，圆角端点（linecap="round"）让图标更柔和友好。基准色 #333 是一个中性的深灰色，配合 ArkUI 的 fillColor() 方法可以在运行时动态替换为任意主题色。

6.3 fillColor 动态变色

SVG 图标最大的优势是支持运行时动态变色。在 ArkUI 中通过 fillColor() 方法实现：

// 图标颜色随主题动态变化
Image($r('app.media.icon_add'))
  .width(24).height(24)
  .fillColor(AppColors.Budget)   // 预算页：蓝色
  .fillColor(AppColors.Expense)  // 支出页：红色
  .fillColor(AppColors.Income)   // 收入页：绿色

// 分类图标颜色随分类配置变化
Image(cat.getIconResource())
  .width(24).height(24)
  .fillColor(cat.color)  // 每个分类有自己的颜色

6.4 深色模式适配

由于 SVG 图标支持 fillColor 动态变色，深色模式适配只需切换颜色值，无需维护两套图标资源：

// 浅色模式：图标使用 PrimaryText (#1C1C1E)
// 深色模式：图标使用 PrimaryText (#FFFFFF)
// fillColor 绑定到 AppStorage 中的主题色，自动响应切换
Image($r('app.media.icon_back'))
  .width(24).height(24)
  .fillColor(AppColors.PrimaryText)  // @StorageLink 自动响应深色模式

对比 PNG 方案：如果使用 PNG 图标，深色模式需要在 resources/dark/media/ 目录下维护一套白色版本图标，共 33 个文件。SVG 方案只需一套文件 + fillColor 即可完成适配，维护成本降低 50%。

6.5 图标资源引用

在 ArkTS 代码中通过 $r() 引用 SVG 图标，与 PNG 引用方式完全一致：

// 引用 SVG 图标（无需写扩展名）
Image($r('app.media.icon_back'))     // → icon_back.svg
Image($r('app.media.icon_add'))      // → icon_add.svg
Image($r('app.media.icon_category_food'))  // → icon_category_food.svg

// 在 Category 模型中动态引用
getIconResource(): Resource {
  return $r('app.media.' + this.iconName);  // iconName = 'icon_category_food'
}

七、从 PNG 到 SVG 的迁移

7.1 迁移背景

DevEco Studio 创建工程时会自动在 resources/base/media/ 目录下生成占位 PNG 图标：

icon.png（70 字节透明占位图）
foreground.png（70 字节透明占位图）
background.png（70 字节透明占位图）
startIcon.png（70 字节透明占位图）

这些占位图无法用于实际界面，需要替换为可用的 SVG 矢量图标。

7.2 迁移步骤

删除占位 PNG：移除 resources/base/media/ 下的 .png 占位文件
创建 SVG 文件：为每个图标创建对应的 .svg 文件
验证引用：确保代码中 $r('app.media.xxx') 引用的资源名与新 SVG 文件名一致
编译测试：运行应用验证所有图标正常显示

7.3 迁移前后对比

对比项	迁移前（PNG 占位）	迁移后（SVG 矢量）
文件数量	4 个占位 PNG	33 个可用 SVG
文件大小	每个 70 字节	每个 200-500 字节
显示效果	透明不可见	清晰矢量图标
动态变色	不支持	支持 `fillColor`
深色模式	需两套资源	单套 + `fillColor`
图标覆盖	仅 4 个	33 个全功能图标

迁移要点：SVG 文件名必须与代码中 $r('app.media.xxx') 的 xxx 部分完全一致（不含扩展名）。例如代码中引用 $r('app.media.icon_back')，对应文件名必须是 icon_back.svg。

八、Git 仓库初始化

8.1 .gitignore 配置

工程根目录创建 .gitignore，忽略构建产物与敏感文件：

# 构建产物
/build/
/entry/build/
/.hvigor/
/.idea/

# 依赖缓存
/.ohpm/
/node_modules/

# 签名文件（敏感）
/*.p12
/*.csr
/.deveco/

# 系统文件
.DS_Store
Thumbs.db

# IDE 配置
*.iml
/.vscode/

8.2 首次提交

# 初始化仓库
git init
git remote add origin https://gitcode.com/qiaomu8559968/HarmonyLedger.git.git

# 添加文件
git add .

# 首次提交
git commit -m "feat(project): 初始化 HarmonyLedger 工程骨架

- 创建 DevEco Studio 默认工程
- 搭建 MVVM + Repository 分层目录
- 完善 app.json5、module.json5、build-profile.json5 配置
- 创建 EntryAbility 与 HomeView 占位页
- 建立 33 个 SVG 矢量图标体系
- 配置 .gitignore、README、CHANGELOG"

# 打标签
git tag -a v0.0.2 -m "v0.0.2 创建工程与企业级目录结构"

# 推送
git push -u origin main
git push origin v0.0.2

8.3 CHANGELOG.md

# CHANGELOG

## [v0.0.2] - 2026-07-27

### Added
- 初始化 DevEco Studio 工程
- 搭建 MVVM + Repository 分层目录（pages/components/viewmodel/repository 等）
- 完善 AppScope/app.json5 应用元数据
- 完善 entry/module.json5 模块配置与权限声明
- 创建 EntryAbility 应用入口
- 创建 HomeView 占位页
- 配置 main_pages.json 路由表
- 建立 33 个 SVG 矢量图标体系（替代 PNG 占位符）
- 添加 .gitignore、README.md、CHANGELOG.md

## [v0.0.1] - 2026-07-27
### Added
- 项目规划文档 Project-Design.md
- CSDN 博客写作规范 csdn-high-score-article.md
- 30 篇博客规划与 Git Tag 策略

九、README.md 规范

9.1 README 结构

工程根目录的 README.md 必须包含以下章节：

# HarmonyLedger 鸿蒙记账

> HarmonyOS NEXT 企业级开发实战项目，ArkTS + ArkUI 最佳实践。

## 项目介绍
{一段话介绍项目定位}

## 效果图
{首页、新增账单、统计等核心截图}

## 运行方式
{git clone、ohpm install、DevEco Studio 打开步骤}

## 开发环境
{DevEco Studio 版本、SDK 版本、Node 版本}

## 目录结构
{完整目录树}

## 技术栈
{ArkTS、ArkUI、Stage Model、PersistenceV2 等}

## 系列文章
{30 篇博客目录链接}

## Git 版本
{30 个 Tag 列表}

## 更新日志
{链接到 CHANGELOG.md}

## License
Apache License 2.0

## 作者信息
{GitHub 链接、联系方式}

9.2 README 模板示例

# HarmonyLedger 鸿蒙记账

> HarmonyOS NEXT 企业级记账 APP，ArkTS + ArkUI + MVVM + Repository。

## 项目介绍
HarmonyLedger 是一款面向 HarmonyOS NEXT 的企业级记账应用，采用 MVVM + Repository 架构，涵盖账单管理、分类管理、预算控制、统计分析等完整功能。

## 运行方式
git clone https://gitcode.com/qiaomu8559968/HarmonyLedger.git.git
cd HarmonyLedger
git checkout v0.0.2
ohpm install
# 使用 DevEco Studio 打开工程并 Run

## 开发环境
| 项 | 版本 |
|----|------|
| DevEco Studio | 5.0+ |
| HarmonyOS SDK | 5.0.0 (API 12) |
| Node.js | 18+ |

## 系列文章
详见 [30 篇博客目录](docs/articles/articles-index.md)。

## License
Apache License 2.0

十、最佳实践

10.1 目录结构稳定性

为什么禁止后期随意修改目录？

Git 历史：目录变更会导致大量文件移动，Git 历史断裂
引用更新：路径修改需同步更新所有 import，成本高昂
文档失效：博客、README 中的路径引用会失效
协作混乱：团队成员习惯被打破，降低协作效率

正确做法：项目初期投入足够时间设计目录，后续只在 正式架构评审 后才允许调整。

10.2 BundleName 命名规范

反域名格式：com.{vendor}.{product}
示例：      com.example.harmonyledger

规则：
1. 全小写，单词用点分隔
2. vendor 部分使用公司/团队标识
3. product 部分使用产品名（驼峰转小写下划线）
4. 上架应用市场后不可修改

10.3 资源文件命名规范

HarmonyLedger 的资源文件统一采用 SVG 格式，命名规范如下：

资源类型	命名规范	示例
字符串	小驼峰，按模块前缀	`home_title_today_expense`
颜色	小驼峰，色系前缀	`color_income_primary`
SVG 图标	小写下划线，用途明确	`icon_category_food.svg`
Tab 图标	`icon_tab_` 前缀	`icon_tab_home.svg`
分类图标	`icon_category_` 前缀	`icon_category_food.svg`
应用图标	固定名称	`foreground.svg`、`startIcon.svg`
配置	小写下划线	`main_pages.json`

10.4 SVG 图标管理规范

统一画布：功能图标统一 96x96，应用图标 256x256
统一风格：stroke 描边风格，圆角端点
统一基准色：#333 深灰色，运行时通过 fillColor 动态替换
禁止 fill 填充：功能图标使用 fill="none"，仅靠 stroke 描边
文件命名：小写下划线，用途明确，与代码引用一致

图标管理要点：所有 SVG 图标存放在 entry/src/main/resources/base/media/ 目录下，不需要为深色模式单独创建 dark/media/ 目录。深色模式通过 fillColor 绑定 AppStorage 主题色实现自动切换。

十一、运行验证

11.1 编译检查

# 命令行编译（DevEco Studio 内置）
node /Applications/DevEco-Studio.app/Contents/tools/hvigor/hvigor/bin/hvigor.js assembleApp --no-daemon

预期输出：

> hvigor version: 5.0.0
> hvigor assembleApp: starting...
> hvigor assembleApp: success
> hvigor BUILD SUCCESSFUL in 5s 988ms

11.2 真机运行

通过 hdc 连接鸿蒙真机或模拟器
DevEco Studio 工具栏选择目标设备
点击 Run 按钮，等待应用安装并启动
验证首页显示 “HarmonyLedger 鸿蒙记账” 文字
验证所有 SVG 图标正常渲染（无透明占位图）

十二、常见问题

12.1 Gradle 同步失败

错误现象	解决方案
`SDK not found`	File → Project Structure → 切换 SDK
`hvigor version mismatch`	删除 `.hvigor` 缓存目录后重新同步
`ohpm install timeout`	切换 ohpm 镜像源（`ohpm config set registry`）

12.2 白屏问题

// 错误：loadContent 路径不在 main_pages.json 中
windowStage.loadContent('pages/HomeView', ...)
// 但 main_pages.json 的 src 数组为空 → 白屏

修复：确保 main_pages.json.src 包含所有 loadContent 路径：

{
  "src": [
    "pages/HomeView"  // 必须与 loadContent 参数一致
  ]
}

12.3 SVG 图标不显示

错误现象：Image 引用 SVG 后界面空白
原因一：SVG 文件名与 $r() 引用名不一致
原因二：SVG 文件 XML 格式错误
解决：检查文件名拼写，验证 SVG XML 合法性

12.4 fillColor 不生效

// 原因：SVG 中使用了 fill 属性而非 stroke，fillColor 无法覆盖
// 解决：确保功能图标使用 stroke 描边风格，fill="none"

12.5 BundleName 冲突

错误：hap安装失败，bundleName 已存在
原因：模拟器已安装同包名的其他应用
解决：hdc uninstall com.example.harmonyledger 后重试

十三、工具类占位

13.1 LogUtil.ets

提前创建工具类骨架，后续版本逐步完善：

// utils/LogUtil.ets
import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0001;

export class LogUtil {
  private static readonly TAG = 'HarmonyLedger';

  static d(msg: string): void {
    hilog.debug(DOMAIN, this.TAG, msg);
  }

  static i(msg: string): void {
    hilog.info(DOMAIN, this.TAG, msg);
  }

  static w(msg: string): void {
    hilog.warn(DOMAIN, this.TAG, msg);
  }

  static e(msg: string): void {
    hilog.error(DOMAIN, this.TAG, msg);
  }
}

13.2 constants/app.ets

应用级常量集中定义：

// constants/app.ets
export class AppConfig {
  static readonly BUNDLE_NAME: string = 'com.example.harmonyledger';
  static readonly VERSION_NAME: string = '1.0.0';
  static readonly VERSION_CODE: number = 1;
  static readonly DATABASE_NAME: string = 'harmonyledger.db';
  static readonly DATABASE_VERSION: number = 1;
}

设计要点：常量集中管理避免散落硬编码，便于后期维护与版本升级。

附录：运行效果截图

在这里插入图片描述

总结

本文完整介绍了 HarmonyLedger 工程的 创建流程、目录结构设计、配置文件详解、Ability 与入口页、SVG 矢量图标体系、Git 初始化、README 规范。通过本篇你可以：

使用 DevEco Studio 创建标准鸿蒙工程
搭建符合 MVVM + Repository 架构的分层目录
理解 app.json5、module.json5、build-profile.json5 的关键配置
建立包含 33 个图标的 SVG 矢量图标体系，支持 fillColor 动态变色
将 PNG 占位符全面替换为可用的 SVG 矢量图标
初始化 Git 仓库并提交首个正式版本（v0.0.2）

下一篇预告：《搭建全局主题与 Design Token》将设计 HarmonyLedger 的色彩体系、字号体系、间距体系，并封装深色模式支持，为后续所有页面提供统一的视觉基础。

如果这篇文章对你有帮助，欢迎在下方投票点赞，你的支持是我持续创作的动力！也欢迎收藏关注，不错过后续更新。

所有评论(0)

查看更多评论

最爱老式锅包肉

@2601_96191042

已为社区贡献86条内容

HarmonyOS NEXT 企业级记账APP：创建工程与企业级目录结构设计

最爱老式锅包肉

创建工程与企业级目录结构设计

前言

一、工程创建流程

1.1 DevEco Studio 创建工程

1.2 验证工程创建

二、企业级目录结构设计

2.1 完整目录树

2.2 分层目录职责

三、配置文件详解

3.1 AppScope/app.json5

3.2 entry/src/main/module.json5

3.3 build-profile.json5（工程级）

四、Ability 与入口页面

4.1 EntryAbility.ets

4.2 入口页面 HomeView.ets

4.3 路由配置 main_pages.json

五、SVG 矢量图标体系

5.1 为什么选择 SVG 而非 PNG

5.2 SVG 图标的优势

5.3 图标分类体系

5.4 导航与操作图标

5.5 收支图标

5.6 分类图标

5.7 Tab 栏图标

5.8 完整分类图标清单

六、SVG 图标设计规范

6.1 统一画布尺寸

6.2 stroke 描边风格

6.3 fillColor 动态变色

6.4 深色模式适配

6.5 图标资源引用

七、从 PNG 到 SVG 的迁移

7.1 迁移背景

7.2 迁移步骤

7.3 迁移前后对比

八、Git 仓库初始化

8.1 .gitignore 配置

8.2 首次提交

8.3 CHANGELOG.md

九、README.md 规范

9.1 README 结构

9.2 README 模板示例

十、最佳实践

10.1 目录结构稳定性

10.2 BundleName 命名规范

10.3 资源文件命名规范

10.4 SVG 图标管理规范

十一、运行验证

11.1 编译检查

11.2 真机运行

十二、常见问题

12.1 Gradle 同步失败

12.2 白屏问题

12.3 SVG 图标不显示

12.4 fillColor 不生效

12.5 BundleName 冲突

十三、工具类占位

13.1 LogUtil.ets

13.2 constants/app.ets

附录：运行效果截图

总结

相关资源

所有评论(0)

温馨提示：您尚未绑定手机号

最爱老式锅包肉