鸿蒙应用开发实战【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数据备份导出/导入本地数据BackupPage1.3 应用截图预览图1号码助手首页 — 展示统计卡片、应用列表和 FAB 按钮图片说明上图展示首页的三大区域顶部统计卡待换绑/待注销/已停用数量、中部应用列表支持筛选和多选、底部悬浮按钮添加应用/粘贴导入。二、技术选型与架构设计2.1 技术栈概览层级技术版本语言ArkTSHarmonyOS 专属 TypeScript 严格子集ArkTS 1.0UI 框架ArkUI声明式 UIHarmonyOS SDK 6.1数据库relationalStore本地关系型数据库ohos.data.relationalStore构建工具Hvigor与 DevEco Studio 同版本开发工具DevEco Studio5.0目标平台HarmonyOS NEXT纯鸿蒙无 Android 兼容层phone 设备2.2 整体架构应用采用经典的三层架构UI 层pages/下的 ArkUI 页面 common/components/下的可复用组件数据访问层DAOfeatures/data/下的 CardDao、AppBindingDao、SmsCandidateDao数据库层基于relationalStore的本地 SQLite 数据库由DatabaseService统一管理三、HarmonyOS NEXT 开发环境搭建3.1 环境要求在开始之前请确认你的开发机满足以下要求项目最低要求推荐配置操作系统macOS 12 / Windows 10 64位macOS 14内存8GB16GB磁盘空间20GB 可用50GBJDKJDK 17DevEco 自带Node.js16.xDevEco 自带3.2 安装 DevEco Studio访问华为开发者官网https://developer.huawei.com/consumer/cn/deveco-studio/下载最新版 DevEco Studio5.0 及以上按引导完成安装首次启动会自动下载 SDK注意DevEco Studio 已内置 Node.js 和 ohpm鸿蒙包管理器无需单独安装。安装完成后在终端验证环境# 验证 hvigor 构建工具是否可用/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw--version# 验证 ohpm 包管理器/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpm--version3.3 配置 SDK打开 DevEco Studio进入File → Settings → HarmonyOS SDKSDK 安装路径示例 /Applications/DevEco-Studio.app/Contents/sdk/ 需要安装的组件 ✅ HarmonyOS (API 12) — 核心运行时 ✅ HarmonyOS Extra — 额外设备支持 ✅ OpenHarmony (API 12) — 基础平台3.4 拉取项目代码# 进入工作目录cd~/Downloads# 克隆项目或直接复制项目文件夹# 项目根目录结构如下lshaomazhushou/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 安装依赖cd/Users/fiona/Downloads/haomazhushou/app# 使用 ohpm 安装依赖类似 npm install/Applications/DevEco-Studio.app/Contents/tools/ohpm/bin/ohpminstall# 查看安装的模块lsoh_modules/ohos/3.6 首次构建与运行# 编译 Debug HAPexportDEVECO_SDK_HOME/Applications/DevEco-Studio.app/Contents/sdkexportPATH/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATHcd/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 — 包管理配置{ name: number-assistant, version: 1.0.0, description: 号码助手应用, main: , author: , license: ISC, devDependencies: { ohos/hypium: 1.0.25 // 单元测试框架 } }要点解析name包名在 ohpm 生态系统中的唯一标识ohos/hypiumHarmonyOS 官方单元测试框架仅在开发阶段使用4.2 build-profile.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表明这是纯鸿蒙应用不兼容 AndroidcompatibleSdkVersion最低兼容 SDK 版本只有一个entry模块是典型的单模块小应用结构4.3 module.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{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 组件无需启动模拟器支持多设备尺寸预览手机/平板/大屏修改代码后热重载秒级刷新// Previewer 支持预览任意 Component 或 Entry 组件EntryComponentstruct 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 — 应用入口import{UIAbility,Want,AbilityConstant}fromkit.AbilityKitimport{hilog}fromkit.PerformanceAnalysisKitimport{window}fromkit.ArkUIimport{DatabaseService}from./features/data/DatabaseServiceconstTAG[EntryAbility]exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{hilog.info(0x0000,TAG,onCreate)}onWindowStageCreate(windowStage:window.WindowStage):void{// 1. 初始化数据库异步不阻塞 UIDatabaseService.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 — 版本适配工具预留// 未来扩展可在此处封装 HarmonyOS API 版本判断exportclassVersionHelper{staticisApiLevel12OrAbove():boolean{// canIUse(SystemCapability.xxx) 检查系统能力returntrue}}七、系列学习路径建议7.1 推荐学习顺序对于不同背景的开发者推荐不同的阅读路线路线 ATypeScript 开发者转型鸿蒙本篇环境搭建→ 第 02 篇ArkTS 语法→ 第 07 篇状态管理→ 第 26-40 篇数据库路线 BAndroid/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-columnArkTS 语言规范https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-get-startedDevEco Studio 下载https://developer.huawei.com/consumer/cn/deveco-studio/AppGallery Connecthttps://developer.huawei.com/consumer/cn/service/josp/agc/index.html八、常见环境问题排查8.1 SDK 找不到现象运行 hvigorw 时报SDK_HOME not found解决# 手动指定 SDK 路径exportDEVECO_SDK_HOME/Applications/DevEco-Studio.app/Contents/sdkexportPATH/Applications/DevEco-Studio.app/Contents/tools/node/bin:$PATH8.2 依赖包安装失败现象ohpm install报网络错误解决# 配置国内镜像源ohpm configsetregistry https://repo.harmonyos.com/ohpm/# 重新安装ohpminstall8.3 编译报 ArkTS 严格模式错误现象error TS... arkts-no-untyped-obj-literals解决所有对象字面量必须对应已声明的 interface 或 class// ❌ 错误匿名对象字面量constparams{status:active}// ✅ 正确先声明 interfaceinterfaceFilterParams{status:string}constparams: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等核心装饰器的使用方法。十、参考资料本系列相关文章鸿蒙应用开发实战【02】— ArkTS 语法基础与工程结构解析鸿蒙应用开发实战【03】— ArkUI 设计令牌体系构建鸿蒙应用开发实战【04】— 应用配置详解官方文档HarmonyOS NEXT 开发指南ArkTS 语言介绍DevEco Studio 使用指南relationalStore API 参考如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.netHarmonyOS 官方文档https://developer.huawei.com/consumer/cn/doc/DevEco Studio 下载https://developer.huawei.com/consumer/cn/deveco-studio/
