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

前言

随着鸿蒙生态的快速发展，越来越多的开发者开始接触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

  1. 下载安装包

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

  2. 安装配置

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

  3. 首次启动配置

    • 下载 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 创建项目

  1. 打开 DevEco Studio → File → New → New Project
  2. 选择 Empty Ability 模板
  3. 配置项目信息：
配置项 值
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 提供了强大的预览器功能：

  1. 打开任意 .ets 页面文件
  2. 右侧边栏点击 Previewer
  3. 实时预览UI效果

6.2 模拟器运行

  1. 点击 Tools → Device Manager
  2. 创建本地模拟器（选择 Phone 类型）
  3. 点击运行按钮 ▶️

6.3 真机调试

  1. 连接华为手机/平板
  2. 开启开发者模式和USB调试
  3. 配置签名（自动签名或手动签名）
  4. 点击运行

七、小结

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

  1. ✅ 项目功能规划与技术选型
  2. ✅ DevEco Studio环境配置
  3. ✅ HarmonyOS项目结构详解
  4. ✅ 关键配置文件说明
  5. ✅ 分层架构设计
  6. ✅ 核心配置初始化

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

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

相关资源：

# harmonyos # 华为
Logo
人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

鸿蒙系统安装openharmony EFI 物理磁盘

鸿蒙系统安装openharmonyEFI物理磁盘把鸿蒙系统openharmony 安装到 EFI物理磁

avatar 人工智能6S服务平台
cover

“与时代 共昇腾”，昇腾深入千行万业，以算力驱动智能未来

avatar 人工智能6S服务平台
cover

鸿蒙Flutter MaterialPageRoute：路由参数与使用场景

avatar 人工智能6S服务平台