鸿蒙多功能工具箱开发实战(一)-项目架构设计与环境搭建-171主机测评

鸿蒙多功能工具箱开发实战(一)-项目架构设计与环境搭建

前言

随着鸿蒙生态的快速发展，越来越多的开发者开始接触HarmonyOS应用开发。本文将以一个实用的多功能工具箱应用为例，从零开始讲解HarmonyOS项目的架构设计与环境搭建过程。通过本系列文章，你将掌握HarmonyOS应用开发的核心技术和最佳实践。

一、项目概述

1.1 项目定位

鸿蒙多功能工具箱（HarmonyToolBox）是一款集成多种实用工具的应用，涵盖计算、历法、换算、财务、行情、生活等多个领域。项目旨在：

提供日常高频使用的工具集合
展示HarmonyOS开发的最佳实践
作为学习鸿蒙开发的实战案例

1.2 功能模块规划

图1 功能模块

分类工具列表说明

计算工具	亲戚称呼计算器、日期计算器、养老金计算器	生活常用计算
历法工具	中华农历、黄历查询、节气查询	传统历法功能
换算工具	长度/重量/面积/体积/温度/速度换算	多维度单位换算
财务工具	个税计算、汇率换算、理财计算、房贷/车贷计算	金融类计算
行情工具	今日金价、实时汇率	实时数据展示
生活工具	每日语录、天气查询	日常信息服务

1.3 技术选型

开发工具：DevEco Studio 5.0+
开发语言：ArkTS + ArkUI
系统版本：HarmonyOS 4.0+ (API 10+)
构建工具：Hvigor
状态管理：@State、@Link、@Provide/@Consume
网络请求：@ohos.net.http
数据存储：Preferences

二、开发环境搭建

2.1 安装DevEco Studio

下载安装包

访问华为开发者官网：https://developer.huawei.com
下载 DevEco Studio 最新版本（建议5.0以上）
支持 Windows 和 macOS 系统

安装配置

# Windows系统安装后配置环境变量
DEVECO_HOME = C:\\Program Files\\Huawei\\DevEco Studio

首次启动配置

下载 HarmonyOS SDK（选择 API 10+）
配置 Node.js 环境（DevEco会自动提示）
登录华为开发者账号

2.2 SDK版本选择

推荐配置：

HarmonyOS SDK: API 10 (HarmonyOS 4.0)
Compile SDK: 10
Target SDK: 10
Minimum SDK: 10

三、项目创建与结构解析

3.1 创建项目

打开 DevEco Studio → File → New → New Project

选择 Empty Ability 模板

配置项目信息：

配置项值

Project name	HarmonyToolBox
Bundle name	com.example.harmonytoolbox
Save location	自定义路径
Compile SDK	API 10
Model	Stage模型

3.2 项目目录结构

创建完成后的标准目录结构：

HarmonyToolBox/
├── AppScope/ # 应用全局配置
│ ├── app.json5 # 应用配置（包名、版本等）
│ └── resources/ # 全局资源（图标、字符串）
│ ├── base/
│ │ ├── element/
│ │ │ └── string.json # 全局字符串资源
│ │ └── media/ # 全局媒体资源
│ └── rawfile/ # 原始文件资源
│
├── entry/ # 主模块（entry HAP）
│ ├── src/
│ │ └── main/
│ │ ├── ets/ # ArkTS源码目录
│ │ │ ├── entryability/
│ │ │ │ └── EntryAbility.ets # 应用入口
│ │ │ └── pages/ # 页面目录
│ │ │ └── Index.ets
│ │ ├── resources/ # 模块资源
│ │ │ ├── base/
│ │ │ │ ├── element/
│ │ │ │ │ ├── color.json # 颜色资源
│ │ │ │ │ └── string.json # 字符串资源
│ │ │ │ ├── media/ # 图片资源
│ │ │ │ └── profile/ # 配置文件
│ │ │ │ └── main_pages.json # 页面路由配置
│ │ │ └── rawfile/
│ │ └── module.json5 # 模块配置
│ ├── build-profile.json5 # 构建配置
│ ├── hvigorfile.ts # Hvigor构建脚本
│ └── oh-package.json5 # 依赖配置
│
├── build-profile.json5 # 项目构建配置
├── hvigorfile.ts # 项目级构建脚本
├── oh-package.json5 # 项目依赖配置
└── hvigor/ # Hvigor工具配置
└── hvigor-config.json5

3.3 关键配置文件详解

3.3.1 app.json5 – 应用配置

{
"app": {
"bundleName": "com.example.harmonytoolbox", // 应用包名（唯一标识）
"vendor": "example", // 开发者名称
"versionCode": 1000000, // 版本号（整数）
"versionName": "1.0.0", // 版本名称（字符串）
"icon": "$media:layered_image", // 应用图标
"label": "$string:app_name" // 应用名称
}
}

3.3.2 module.json5 – 模块配置

{
"module": {
"name": "entry", // 模块名称
"type": "entry", // 模块类型：entry/feature/shared
"description": "$string:module_desc",
"mainElement": "EntryAbility", // 主Ability
"deviceTypes": ["phone", "tablet"], // 支持设备类型
"deliveryWithInstall": true, // 是否随应用安装
"installationFree": false, // 是否免安装
"pages": "$profile:main_pages", // 页面配置
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:layered_image",
"label": "$string:EntryAbility_label",
"exported": true, // 是否可被其他应用调用
"skills": [
{
"entities": ["entity.system.home"],
"actions": ["ohos.want.action.home"] // 启动Action
}
]
}
]
}
}

3.3.3 main_pages.json – 页面路由配置

{
"src": [
"pages/Index",
"pages/calculator/RelativeCalculator",
"pages/calendar/LunarCalendar"
]
}

重要：每个新页面都必须在此注册才能被路由访问！

3.3.4 build-profile.json5 – 构建配置

{
"app": {
"signingConfigs": [], // 签名配置
"compileSdkVersion": 10, // 编译SDK版本
"compatibleSdkVersion": 10, // 兼容SDK版本
"products": [
{
"name": "default",
"signingConfig": "default"
}
]
},
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": ["default"]
}
]
}
]
}

四、项目架构设计

4.1 分层架构

┌─────────────────────────────────────────┐
│ UI Layer (Pages) │
│ Index.ets, CalculatorPage.ets, … │
├─────────────────────────────────────────┤
│ Component Layer (组件) │
│ BottomNavBar, ToolCard, … │
├─────────────────────────────────────────┤
│ Common Layer (公共) │
│ AppConfig, Utils, Constants │
├─────────────────────────────────────────┤
│ Service Layer (服务) │
│ HttpService, StorageService │
└─────────────────────────────────────────┘

4.2 目录规划

entry/src/main/ets/
├── common/ # 公共模块
│ ├── AppConfig.ets # 应用配置（主题、分类等）
│ ├── Constants.ets # 常量定义
│ └── Utils.ets # 工具函数
│
├── components/ # 公共组件
│ ├── BottomNavBar.ets # 底部导航栏
│ ├── ToolCard.ets # 工具卡片
│ └── Header.ets # 通用头部
│
├── pages/ # 页面
│ ├── Index.ets # 主页
│ ├── CalculatorPage.ets # 计算工具分类页
│ ├── CalendarPage.ets # 历法工具分类页
│ ├── ConvertPage.ets # 换算工具分类页
│ ├── FinancePage.ets # 财务工具分类页
│ ├── MarketPage.ets # 行情工具分类页
│ ├── LifePage.ets # 生活工具分类页
│ │
│ ├── calculator/ # 计算工具详情页
│ │ ├── RelativeCalculator.ets
│ │ ├── DateCalculator.ets
│ │ └── PensionCalculator.ets
│ │
│ ├── calendar/ # 历法工具详情页
│ │ ├── LunarCalendar.ets
│ │ ├── HuangCalendar.ets
│ │ └── SolarTerms.ets
│ │
│ ├── convert/ # 换算工具详情页
│ │ ├── LengthConvert.ets
│ │ └── …
│ │
│ ├── finance/ # 财务工具详情页
│ ├── market/ # 行情工具详情页
│ └── life/ # 生活工具详情页
│
├── services/ # 服务层
│ ├── HttpService.ets # 网络请求服务
│ └── StorageService.ets # 数据存储服务
│
├── models/ # 数据模型
│ └── ToolItem.ets # 工具项模型
│
└── entryability/
└── EntryAbility.ets # 应用入口

4.3 命名规范

类型规范示例

页面	PascalCase + Page	CalculatorPage.ets
组件	PascalCase	ToolCard.ets
服务	PascalCase + Service	HttpService.ets
工具	PascalCase + Utils	DateUtils.ets
常量	UPPER_SNAKE_CASE	THEME_COLORS

五、初始化核心配置

5.1 创建应用配置文件

创建 entry/src/main/ets/common/AppConfig.ets：

// 工具分类枚举
export enum ToolCategory {
CALCULATOR = 'calculator',
CALENDAR = 'calendar',
CONVERT = 'convert',
FINANCE = 'finance',
MARKET = 'market',
LIFE = 'life'
}

// 分类信息接口
export interface CategoryInfo {
category: ToolCategory
name: string
icon: string
color: string
}

// 主题颜色配置
export const THEME_COLORS = {
primary: '#4A90E2',
secondary: '#50C878',
background: '#F5F5F5',
card: '#FFFFFF',
text: '#333333',
textSecondary: '#999999'
}

// 获取分类列表
export function getToolCategories(): CategoryInfo[] {
return [
{ category: ToolCategory.CALCULATOR, name: '计算', icon: '🔢', color: '#4A90E2' },
{ category: ToolCategory.CALENDAR, name: '历法', icon: '📅', color: '#E74C3C' },
{ category: ToolCategory.CONVERT, name: '换算', icon: '🔄', color: '#50C878' },
{ category: ToolCategory.FINANCE, name: '财务', icon: '💰', color: '#FFB347' },
{ category: ToolCategory.MARKET, name: '行情', icon: '📈', color: '#9B59B6' },
{ category: ToolCategory.LIFE, name: '生活', icon: '🏠', color: '#1ABC9C' }
]
}

5.2 配置资源文件

string.json – 字符串资源

{
"string": [
{ "name": "app_name", "value": "多功能工具箱" },
{ "name": "module_desc", "value": "多功能工具箱应用" }
]
}

color.json – 颜色资源

{
"color": [
{ "name": "primary", "value": "#4A90E2" },
{ "name": "start_window_background", "value": "#FFFFFF" }
]
}

六、运行与调试

6.1 本地预览器

DevEco Studio 提供了强大的预览器功能：

打开任意 .ets 页面文件

右侧边栏点击 Previewer

实时预览UI效果

6.2 模拟器运行

点击 Tools → Device Manager

创建本地模拟器（选择 Phone 类型）

点击运行按钮 ▶️

6.3 真机调试

连接华为手机/平板

开启开发者模式和USB调试

配置签名（自动签名或手动签名）

点击运行

七、小结

本文介绍了鸿蒙多功能工具箱项目的整体架构设计与开发环境搭建，包括：

✅ 项目功能规划与技术选型

✅ DevEco Studio环境配置

✅ HarmonyOS项目结构详解

✅ 关键配置文件说明

✅ 分层架构设计

✅ 核心配置初始化

下一篇文章将讲解底部导航栏的实现，包括多分类切换、状态管理等核心功能。

系列文章导航：下期预告：鸿蒙多功能工具箱开发实战(二)-底部导航栏实现

鸿蒙多功能工具箱开发实战(一)-项目架构设计与环境搭建