鸿蒙应用开发实战【01】— 号码助手项目概述与开发环境搭建

鸿蒙应用开发实战【01】--- 号码助手项目概述与开发环境搭建

前言

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

在智能手机普及的今天，我们每个人都拥有多张 SIM 卡，在数十甚至数百个 App、网站、小程序上注册了账号。当你想注销某张手机号时，却发现不知道它绑定了哪些应用；当你换号时，更不知道要去哪里一个个更新。号码助手正是为解决这一真实痛点而生的 HarmonyOS NEXT 原生应用。

本系列是一个完整的 HarmonyOS NEXT 应用开发实战教程，以号码助手的真实项目代码为主线，从环境搭建到功能完成，逐步讲解每一个开发环节。本篇是系列第 01 篇，聚焦于项目背景、应用功能介绍 和开发环境搭建。

系列说明：本系列共 100 篇，覆盖 HarmonyOS NEXT 应用开发的方方面面，适合有一定 TypeScript / JavaScript 基础的开发者阅读。

一、号码助手是什么

1.1 产品定位

号码助手 是一款运行在 HarmonyOS NEXT 上的手机号码管理工具。它的核心功能是帮助用户记录哪些 App 使用了哪张手机号注册，在换号、注销时提供完整的待处理清单。

主要解决三大场景：

换号场景：列出所有使用旧号码注册的应用，逐一完成绑定手机号的更换
注销场景：列出该号码关联的全部应用，便于完整注销账号
停用场景：标记已停止使用的应用绑定，保持记录干净整洁

1.2 核心功能模块

模块	功能描述	对应页面
卡号管理	添加、编辑、删除 SIM 卡信息	CardManagePage / AddCardPage
应用绑定	记录应用与手机号的对应关系	AddAppPage / AppDetailPage
状态追踪	标记绑定状态（使用中/待换绑/待注销/已停用）	AppDetailPage
换绑功能	将某应用从旧卡号迁移到新卡号	RebindPage
批量操作	多选应用批量修改状态或删除	HomePage
搜索导入	搜索应用名或粘贴文本批量导入	SearchPage / PasteImportPage
数据备份	导出/导入本地数据	BackupPage

1.3 应用截图预览

图1：号码助手首页 --- 展示统计卡片、应用列表和 FAB 按钮

图片说明：上图展示首页的三大区域：顶部统计卡（待换绑/待注销/已停用数量）、中部应用列表（支持筛选和多选）、底部悬浮按钮（添加应用/粘贴导入）。

二、技术选型与架构设计

2.1 技术栈概览

层级	技术	版本
语言	ArkTS（HarmonyOS 专属 TypeScript 严格子集）	ArkTS 1.0
UI 框架	ArkUI（声明式 UI）	HarmonyOS SDK 6.1
数据库	relationalStore（本地关系型数据库）	@ohos.data.relationalStore
构建工具	Hvigor	与 DevEco Studio 同版本
开发工具	DevEco Studio	5.0+
目标平台	HarmonyOS NEXT（纯鸿蒙，无 Android 兼容层）	phone 设备

2.2 整体架构

应用采用经典的三层架构：

UI 层 ：pages/ 下的 ArkUI 页面 + common/components/ 下的可复用组件
数据访问层（DAO） ：features/data/ 下的 CardDao、AppBindingDao、SmsCandidateDao
数据库层 ：基于 relationalStore 的本地 SQLite 数据库，由 DatabaseService 统一管理

三、HarmonyOS NEXT 开发环境搭建

3.1 环境要求

在开始之前，请确认你的开发机满足以下要求：

项目	最低要求	推荐配置
操作系统	macOS 12 / Windows 10 64位	macOS 14+
内存	8GB	16GB+
磁盘空间	20GB 可用	50GB+
JDK	JDK 17	DevEco 自带
Node.js	16.x	DevEco 自带

3.2 安装 DevEco Studio

访问华为开发者官网：https://developer.huawei.com/consumer/cn/deveco-studio/
下载最新版 DevEco Studio（5.0 及以上）
按引导完成安装，首次启动会自动下载 SDK

注意：DevEco Studio 已内置 Node.js 和 ohpm（鸿蒙包管理器），无需单独安装。

安装完成后，在终端验证环境：

bash 复制代码

# 验证 hvigor 构建工具是否可用
/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw --version

# 验证 ohpm 包管理器
/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm --version

3.3 配置 SDK

打开 DevEco Studio，进入 File → Settings → HarmonyOS SDK：

复制代码

SDK 安装路径示例：
/Applications/DevEco-Studio.app/Contents/sdk/

需要安装的组件：
✅ HarmonyOS (API 12+)       --- 核心运行时
✅ HarmonyOS Extra           --- 额外设备支持
✅ OpenHarmony (API 12+)     --- 基础平台

3.4 拉取项目代码

bash 复制代码

# 进入工作目录
cd ~/Downloads

# 克隆项目（或直接复制项目文件夹）
# 项目根目录结构如下：
ls haomazhushou/app/

项目目录结构如下：

复制代码

app/
├── AppScope/                  # 应用级资源（图标、全局字符串）
│   ├── app.json5              # 应用配置（bundleName、版本号）
│   └── resources/base/media/app_icon.svg
├── entry/                     # 唯一业务模块
│   ├── src/main/ets/          # ArkTS 源码
│   │   ├── EntryAbility.ets   # UIAbility 入口
│   │   ├── common/            # 通用组件与设计令牌
│   │   ├── features/data/     # DAO 层与数据模型
│   │   └── pages/             # 所有页面
│   ├── src/main/resources/    # 模块资源（颜色、字符串）
│   └── module.json5           # 模块配置（路由表）
├── oh-package.json5           # 项目依赖声明
├── build-profile.json5        # 构建配置（SDK 版本、产品定义）
└── hvigorfile.ts              # Hvigor 构建脚本

3.5 安装依赖

bash 复制代码

cd /Users/fiona/Downloads/haomazhushou/app

# 使用 ohpm 安装依赖（类似 npm install）
/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm install

# 查看安装的模块
ls oh_modules/@ohos/

3.6 首次构建与运行

bash 复制代码

# 编译 Debug HAP
export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk"
export PATH="/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATH"

cd /Users/fiona/Downloads/haomazhushou/app
./hvigor/bin/hvigorw assembleHap --no-daemon

# 编译成功后，HAP 文件路径：
# entry/build/default/outputs/default/entry-default-unsigned.hap

提示：第一次构建可能需要 1-2 分钟，后续增量构建通常在 5-10 秒内完成。

四、项目核心文件解析

4.1 oh-package.json5 --- 包管理配置

json5 复制代码

{
  "name": "number-assistant",
  "version": "1.0.0",
  "description": "号码助手应用",
  "main": "",
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "@ohos/hypium": "1.0.25"    // 单元测试框架
  }
}

要点解析：

name：包名，在 ohpm 生态系统中的唯一标识
@ohos/hypium：HarmonyOS 官方单元测试框架，仅在开发阶段使用

4.2 build-profile.json5 --- 构建配置

json5 复制代码

{
  "app": {
    "signingConfigs": [],
    "products": [{
      "name": "default",
      "runtimeOS": "HarmonyOS",          // 目标平台：纯鸿蒙
      "compatibleSdkVersion": "6.1.0.66",
      "targetSdkVersion": "6.1.0.66",
      "bundleType": "app"
    }]
  },
  "modules": [{
    "name": "entry",
    "srcPath": "./entry",
    "targets": [{
      "name": "default",
      "applyToProducts": ["default"]
    }]
  }]
}

要点解析：

runtimeOS: "HarmonyOS"：表明这是纯鸿蒙应用，不兼容 Android
compatibleSdkVersion：最低兼容 SDK 版本
只有一个 entry 模块，是典型的单模块小应用结构

4.3 module.json5 --- 页面路由表

json5 复制代码

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone"],
    "abilities": [{
      "name": "EntryAbility",
      "srcEntry": "./ets/EntryAbility.ets",
      "startWindowBackground": "$color:start_window_background"
    }],
    "pages": "$profile:main_pages"     // 指向 main_pages.json
  }
}

页面路由配置文件 main_pages.json：

json 复制代码

{
  "src": [
    "pages/LoginPage",
    "pages/HomePage",
    "pages/CardManagePage",
    "pages/AddCardPage",
    "pages/AddAppPage",
    "pages/AppDetailPage",
    "pages/SearchPage"
    // ... 共 15 个页面
  ]
}

注意：HarmonyOS 路由使用字符串路径而非模块引用，路径对应 ets/ 下的文件相对路径（不含 .ets 后缀）。

五、DevEco Studio 常用操作

5.1 使用 Previewer 预览 UI

在 ArkUI 页面编辑器右上角点击 Previewer 图标，或快捷键 ⇧⌘O 打开预览面板。

主要功能：

实时渲染 ArkUI 组件，无需启动模拟器
支持多设备尺寸预览（手机/平板/大屏）
修改代码后热重载，秒级刷新

typescript 复制代码

// Previewer 支持预览任意 @Component 或 @Entry 组件
@Entry
@Component
struct PreviewDemo {
  build() {
    Column() {
      Text('Hello HarmonyOS NEXT')
        .fontSize(24)
        .fontColor('#4F7CFF')
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

5.2 连接模拟器

菜单栏 → Tools → Device Manager
点击 + 创建虚拟设备（推荐选择 Phone 类型）
启动后在工具栏选择该设备
点击运行按钮（▶）自动编译并部署到模拟器

5.3 查看 Log 日志

打开 View → Tool Windows → Log（或底部 Log 标签）：

复制代码

过滤条件设置：
- 应用包名：com.fiona.numberassistant
- 级别：Debug / Info / Warn / Error
- 标签：搜索具体的 TAG（如 [HomePage]）

六、号码助手项目初始化代码

6.1 EntryAbility.ets --- 应用入口

typescript 复制代码

import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit'
import { hilog } from '@kit.PerformanceAnalysisKit'
import { window } from '@kit.ArkUI'
import { DatabaseService } from './features/data/DatabaseService'

const TAG = '[EntryAbility]'

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, TAG, 'onCreate')
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    // 1. 初始化数据库（异步，不阻塞 UI）
    DatabaseService.init(this.context).catch((e: Error) => {
      hilog.error(0x0000, TAG, 'DB init failed: %{public}s', JSON.stringify(e))
    })

    // 2. 加载首页
    windowStage.loadContent('pages/LoginPage', (err) => {
      if (err.code) {
        hilog.error(0x0000, TAG, 'loadContent failed: %{public}d', err.code)
        return
      }
      hilog.info(0x0000, TAG, 'loadContent success')
    })
  }
}

关键点 ：数据库初始化 DatabaseService.init() 是异步的，不会阻塞 UI 加载。页面初次显示时数据库可能尚未就绪，因此各 DAO 调用都必须包裹 try/catch。

6.2 ValidationHelper --- 版本适配工具（预留）

typescript 复制代码

// 未来扩展：可在此处封装 HarmonyOS API 版本判断
export class VersionHelper {
  static isApiLevel12OrAbove(): boolean {
    // canIUse('SystemCapability.xxx') 检查系统能力
    return true
  }
}

七、系列学习路径建议

7.1 推荐学习顺序

对于不同背景的开发者，推荐不同的阅读路线：

路线 A：TypeScript 开发者转型鸿蒙

本篇（环境搭建）→ 第 02 篇（ArkTS 语法）→ 第 07 篇（状态管理）→ 第 26-40 篇（数据库）

路线 B：Android/iOS 开发者迁移鸿蒙

本篇 → 第 04 篇（配置详解）→ 第 06 篇（生命周期）→ 第 23 篇（三态 UI）→ 第 11-13 篇（组件）

路线 C：零基础跟着实战学

第 01-10 篇（基础入门）→ 第 11-25 篇（UI 开发）→ 第 41-60 篇（页面实战）

7.2 每篇文章结构

本系列每篇文章统一包含以下部分：

功能介绍：该功能/模块是什么、解决什么问题
API 介绍：涉及的 HarmonyOS NEXT API 讲解
核心代码演示：真实项目代码 + 详细注释
运行效果：截图或效果描述
小结与踩坑记录：开发过程中的注意事项

7.3 配套资源

资源	地址
HarmonyOS 官方文档	https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/
ArkUI 组件参考	https://developer.huawei.com/consumer/cn/doc/harmonyos-references/ts-container-column
ArkTS 语言规范	https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-get-started
DevEco Studio 下载	https://developer.huawei.com/consumer/cn/deveco-studio/
AppGallery Connect	https://developer.huawei.com/consumer/cn/service/josp/agc/index.html

八、常见环境问题排查

8.1 SDK 找不到

现象：运行 hvigorw 时报 SDK_HOME not found

解决：

bash 复制代码

# 手动指定 SDK 路径
export DEVECO_SDK_HOME="/Applications/DevEco-Studio.app/Contents/sdk"
export PATH="/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATH"

8.2 依赖包安装失败

现象：ohpm install 报网络错误

解决：

bash 复制代码

# 配置国内镜像源
ohpm config set registry https://repo.harmonyos.com/ohpm/

# 重新安装
ohpm install

8.3 编译报 ArkTS 严格模式错误

现象：error TS... arkts-no-untyped-obj-literals

解决：所有对象字面量必须对应已声明的 interface 或 class：

typescript 复制代码

// ❌ 错误：匿名对象字面量
const params = { status: 'active' }

// ✅ 正确：先声明 interface
interface FilterParams {
  status: string
}
const params: FilterParams = { status: 'active' }

九、本篇小结

本篇完成了号码助手系列的「起跑线」工作：

了解了产品定位：帮助用户管理手机号与 App 的绑定关系，解决换号/注销难题
掌握了技术栈：ArkTS + ArkUI + relationalStore，纯 HarmonyOS NEXT 技术
搭建了开发环境：DevEco Studio 5.0 + SDK 6.1，并完成了第一次编译
理解了项目结构：entry 模块下的三层架构（pages / data / common）

下一篇将深入 ArkTS 语法基础 ，介绍 ArkTS 与标准 TypeScript 的区别、严格模式约束，以及 @Entry、@Component、@State 等核心装饰器的使用方法。

十、参考资料

本系列相关文章：

官方文档：

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！

相关资源：

开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
HarmonyOS 官方文档：https://developer.huawei.com/consumer/cn/doc/
DevEco Studio 下载：https://developer.huawei.com/consumer/cn/deveco-studio/