鸿蒙原生应用实战一从零搭建快递追踪App——项目初始化与工程架构详解本文是「鸿蒙原生应用实战」系列第一篇带你从零开始使用 DevEco Studio 搭建一个完整的快递追踪 App涵盖 Stage 模型、工程配置、资源管理和路由注册等核心内容。一、前言HarmonyOS鸿蒙操作系统自诞生以来其原生应用开发框架不断演进。目前主流的开发模式是Stage 模型 ArkTS 语言相比过去的 FA 模型Stage 模型在组件化、生命周期管理、任务调度等方面更加成熟。本系列将以一个快递追踪 AppPackageTracker为实战项目记录完整的开发过程。第一篇聚焦于项目初始化与工程架构。项目概览应用名称快递追踪包名com.packagetracker.app最低兼容 API23HarmonyOS 6.1.0目标 API24HarmonyOS 6.1.1框架Stage 模型 ArkTSIDEDevEco Studio 6.x快递追踪 App 的核心功能首页展示包裹列表区分运输中/已签收/异常三种状态添加快递单号选择快递公司添加备注查看物流轨迹时间线历史记录查询搜索与筛选包裹快递公司管理收藏常用公司数据统计月度趋势、公司分布个人中心通知设置、统计概览二、创建项目2.1 使用 DevEco Studio 新建项目打开 DevEco Studio点击Create Project选择模板Empty AbilityStage 模型项目名MyApplication包名com.packagetracker.app兼容 SDK选择 API 23语言ArkTS2.2 初始工程结构创建完成后工程目录结构如下MyApplication/ ├── AppScope/ ← 全局应用配置 │ ├── app.json5 ← 应用级配置 │ └── resources/ ← 全局资源 │ └── base/element/string.json ├── entry/ ← 主模块entry type │ ├── src/main/ │ │ ├── ets/ ← ArkTS 源码 │ │ │ ├── entryability/ ← Ability 入口 │ │ │ └── pages/ ← 页面文件 │ │ ├── resources/ ← 模块级资源 │ │ └── module.json5 ← 模块配置 │ ├── build-profile.json5 ← 模块构建配置 │ └── oh-package.json5 ← OHPM 依赖 ├── build-profile.json5 ← 顶层构建配置 ├── hvigor/ ← 构建工具配置 └── oh-package.json5 ← 顶层依赖三、Stage 模型核心概念Stage 模型是 HarmonyOS 从 API 9 开始主推的 Ability 架构有三个核心概念3.1 UIAbility每个应用有一个或多个 UIAbility是应用与系统交互的入口。我们的 App 有一个EntryAbility// entryability/EntryAbility.etsimport{UIAbility,AbilityConstant,Want}fromkit.AbilityKit;import{window}fromkit.ArkUI;exportdefaultclassEntryAbilityextendsUIAbility{onWindowStageCreate(windowStage:window.WindowStage):void{windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(0x0000,testTag,Failed: %{public}s,JSON.stringify(err));}});}}关键点onWindowStageCreate是加载 UI 的入口loadContent指定首页页面路径pages/IndexAbility 生命周期onCreate→onWindowStageCreate→onForeground→onBackground→onWindowStageDestroy→onDestroy3.2 module.json5每个模块的配置文件类似于 Android 的AndroidManifest.xml{ module: { name: entry, type: entry, // entry: 主模块, feature: 特性模块 mainElement: EntryAbility, deviceTypes: [phone], pages: $profile:main_pages, // 引用路由配置 abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, icon: $media:layered_image, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [entity.system.home], actions: [ohos.want.action.home] } ] } ] } }这里有两个重要细节startWindowBackground指向$color:start_window_background在color.json中定义为白色#FFFFFF确保启动时不会闪黑屏skills声明了这个 Ability 响应 Home 事件即桌面图标点击进入3.3 页面路由在resources/base/profile/main_pages.json中注册所有页面{src:[pages/Index,pages/AddPackagePage,pages/TrackDetailPage,pages/HistoryPage,pages/ProfilePage,pages/SearchPage,pages/CompanyManagePage,pages/PackageStatsPage]}每个页面对应ets/pages/下同名文件注册顺序不重要但必须全部列出否则跳转时会报错。四、构建配置详解4.1 顶层 build-profile.json5{ app: { products: [ { name: default, signingConfig: default, targetSdkVersion: 6.1.1(24), compatibleSdkVersion: 6.1.0(23), runtimeOS: HarmonyOS } ], buildModeSet: [ { name: debug }, { name: release } ] } }compatibleSdkVersion: 最低兼容版本向下兼容到此版本targetSdkVersion: 目标版本用此版本的 API 编译这里 API 23 ≈ HarmonyOS 6.1.0API 24 ≈ HarmonyOS 6.1.14.2 AppScope/app.json5{ app: { bundleName: com.packagetracker.app, vendor: atomcode, versionCode: 1000000, versionName: 1.0.0, icon: $media:layered_image, label: $string:app_name } }bundleName包名全局唯一发布后不可更改versionCode版本号整数用于版本比较versionName展示给用户的版本名4.3 API 23 下路由导入的注意事项在 API 23 中router从ohos.router导入而非kit.AbilityKit// ✅ 正确API 23importrouterfromohos.router;// ❌ 错误API 23 不导出此模块importrouterfromkit.AbilityKit;页面跳转标准写法interfaceRouteOpt{url:string;params?:Object;}// 跳转letopt:RouteOpt{url:pages/SearchPage};router.pushUrl(opt);// 带参数跳转letparams{packageData:item};letopt:RouteOpt{url:pages/TrackDetailPage,params:params};router.pushUrl(opt);// 返回上一页router.back();// 接收参数constparamsrouter.getParams()asRecordstring,Object;if(paramsparams[packageData]){this.packageDataparams[packageData]asPackageItem;}五、资源管理体系鸿蒙的资源系统通过$r()引用支持根据设备配置密度、语言、深色模式等自动切换。5.1 string.json — 字符串资源{string:[{name:title_home,value:我的包裹},{name:title_add_package,value:添加包裹},{name:btn_save,value:保存},{name:status_transit,value:运输中},{name:status_delivered,value:已签收},{name:status_exception,value:异常}]}5.2 color.json — 颜色资源{color:[{name:primary,value:#FF4A90D9},{name:background,value:#FFF5F5F5},{name:card_bg,value:#FFFFFF},{name:text_primary,value:#FF333333},{name:text_secondary,value:#FF666666},{name:text_hint,value:#FF999999},{name:divider,value:#FFE0E0E0},{name:status_transit,value:#FFFF8C00},{name:status_delivered,value:#FF4CAF50},{name:status_exception,value:#FFF44336},{name:rating_star,value:#FFFFC107}]}5.3 float.json — 字号与尺寸资源{float:[{name:page_title_font_size,value:22fp},{name:body_font_size,value:16fp},{name:small_font_size,value:13fp},{name:badge_font_size,value:11fp},{name:card_corner_radius,value:12vp},{name:btn_corner_radius,value:8vp},{name:padding_medium,value:16vp}]}fpFont Pixel是鸿蒙的字号单位自带字体缩放适配vpVirtual Pixel是虚拟像素与 dp 类似。5.4 在 ArkTS 中使用资源Text($r(app.string.title_home)).fontSize($r(app.float.page_title_font_size)).fontColor($r(app.color.text_primary)).backgroundColor($r(app.color.primary))重要约定app_name只在AppScope的string.json中定义一次不能在 entry 模块中重复定义否则会冲突。5.5 深色模式适配在entry/src/main/resources/dark/element/color.json中可以配置深色模式下的颜色值系统会根据系统主题自动切换。六、底层构建系统Hvigor鸿蒙使用自研的Hvigor构建系统类似于 Gradle构建命令如下hvigorw--modemodule-pmoduleentrydefault-pproductdefault\-prequiredDeviceTypephone assembleHap--analyzenormal--parallel--incremental--daemon常用参数--mode module模块级构建-p moduleentrydefault指定模块和 targetassembleHap打包 HAP 文件--parallel并行构建--incremental增量编译--daemon守护进程模式加速后续构建七、小结本篇我们完成了✅ 使用 DevEco Studio 创建鸿蒙原生项目✅ 理解 Stage 模型的 UIAbility 生命周期✅ 理解 module.json5 的配置含义✅ 掌握页面路由注册与跳转标准写法✅ 构建配置文件compatibleSdkVersion / targetSdkVersion✅ 资源管理体系string/color/float $r() 引用✅ API 23 下 router 从ohos.router导入的注意事项下一篇将进入首页与列表开发讲解 List 组件、ForEach 渲染、状态管理、空状态设计等实战内容。系列索引第一篇项目初始化与工程架构本文第二篇首页与列表开发实战第三篇表单交互与搜索筛选第四篇物流时间线与历史记录第五篇数据统计与个人中心
鸿蒙原生应用实战（一）：从零搭建快递追踪App——项目初始化与工程架构详解
发布时间：2026/6/13 17:17:46
鸿蒙原生应用实战一从零搭建快递追踪App——项目初始化与工程架构详解本文是「鸿蒙原生应用实战」系列第一篇带你从零开始使用 DevEco Studio 搭建一个完整的快递追踪 App涵盖 Stage 模型、工程配置、资源管理和路由注册等核心内容。一、前言HarmonyOS鸿蒙操作系统自诞生以来其原生应用开发框架不断演进。目前主流的开发模式是Stage 模型 ArkTS 语言相比过去的 FA 模型Stage 模型在组件化、生命周期管理、任务调度等方面更加成熟。本系列将以一个快递追踪 AppPackageTracker为实战项目记录完整的开发过程。第一篇聚焦于项目初始化与工程架构。项目概览应用名称快递追踪包名com.packagetracker.app最低兼容 API23HarmonyOS 6.1.0目标 API24HarmonyOS 6.1.1框架Stage 模型 ArkTSIDEDevEco Studio 6.x快递追踪 App 的核心功能首页展示包裹列表区分运输中/已签收/异常三种状态添加快递单号选择快递公司添加备注查看物流轨迹时间线历史记录查询搜索与筛选包裹快递公司管理收藏常用公司数据统计月度趋势、公司分布个人中心通知设置、统计概览二、创建项目2.1 使用 DevEco Studio 新建项目打开 DevEco Studio点击Create Project选择模板Empty AbilityStage 模型项目名MyApplication包名com.packagetracker.app兼容 SDK选择 API 23语言ArkTS2.2 初始工程结构创建完成后工程目录结构如下MyApplication/ ├── AppScope/ ← 全局应用配置 │ ├── app.json5 ← 应用级配置 │ └── resources/ ← 全局资源 │ └── base/element/string.json ├── entry/ ← 主模块entry type │ ├── src/main/ │ │ ├── ets/ ← ArkTS 源码 │ │ │ ├── entryability/ ← Ability 入口 │ │ │ └── pages/ ← 页面文件 │ │ ├── resources/ ← 模块级资源 │ │ └── module.json5 ← 模块配置 │ ├── build-profile.json5 ← 模块构建配置 │ └── oh-package.json5 ← OHPM 依赖 ├── build-profile.json5 ← 顶层构建配置 ├── hvigor/ ← 构建工具配置 └── oh-package.json5 ← 顶层依赖三、Stage 模型核心概念Stage 模型是 HarmonyOS 从 API 9 开始主推的 Ability 架构有三个核心概念3.1 UIAbility每个应用有一个或多个 UIAbility是应用与系统交互的入口。我们的 App 有一个EntryAbility// entryability/EntryAbility.etsimport{UIAbility,AbilityConstant,Want}fromkit.AbilityKit;import{window}fromkit.ArkUI;exportdefaultclassEntryAbilityextendsUIAbility{onWindowStageCreate(windowStage:window.WindowStage):void{windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(0x0000,testTag,Failed: %{public}s,JSON.stringify(err));}});}}关键点onWindowStageCreate是加载 UI 的入口loadContent指定首页页面路径pages/IndexAbility 生命周期onCreate→onWindowStageCreate→onForeground→onBackground→onWindowStageDestroy→onDestroy3.2 module.json5每个模块的配置文件类似于 Android 的AndroidManifest.xml{ module: { name: entry, type: entry, // entry: 主模块, feature: 特性模块 mainElement: EntryAbility, deviceTypes: [phone], pages: $profile:main_pages, // 引用路由配置 abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, icon: $media:layered_image, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [entity.system.home], actions: [ohos.want.action.home] } ] } ] } }这里有两个重要细节startWindowBackground指向$color:start_window_background在color.json中定义为白色#FFFFFF确保启动时不会闪黑屏skills声明了这个 Ability 响应 Home 事件即桌面图标点击进入3.3 页面路由在resources/base/profile/main_pages.json中注册所有页面{src:[pages/Index,pages/AddPackagePage,pages/TrackDetailPage,pages/HistoryPage,pages/ProfilePage,pages/SearchPage,pages/CompanyManagePage,pages/PackageStatsPage]}每个页面对应ets/pages/下同名文件注册顺序不重要但必须全部列出否则跳转时会报错。四、构建配置详解4.1 顶层 build-profile.json5{ app: { products: [ { name: default, signingConfig: default, targetSdkVersion: 6.1.1(24), compatibleSdkVersion: 6.1.0(23), runtimeOS: HarmonyOS } ], buildModeSet: [ { name: debug }, { name: release } ] } }compatibleSdkVersion: 最低兼容版本向下兼容到此版本targetSdkVersion: 目标版本用此版本的 API 编译这里 API 23 ≈ HarmonyOS 6.1.0API 24 ≈ HarmonyOS 6.1.14.2 AppScope/app.json5{ app: { bundleName: com.packagetracker.app, vendor: atomcode, versionCode: 1000000, versionName: 1.0.0, icon: $media:layered_image, label: $string:app_name } }bundleName包名全局唯一发布后不可更改versionCode版本号整数用于版本比较versionName展示给用户的版本名4.3 API 23 下路由导入的注意事项在 API 23 中router从ohos.router导入而非kit.AbilityKit// ✅ 正确API 23importrouterfromohos.router;// ❌ 错误API 23 不导出此模块importrouterfromkit.AbilityKit;页面跳转标准写法interfaceRouteOpt{url:string;params?:Object;}// 跳转letopt:RouteOpt{url:pages/SearchPage};router.pushUrl(opt);// 带参数跳转letparams{packageData:item};letopt:RouteOpt{url:pages/TrackDetailPage,params:params};router.pushUrl(opt);// 返回上一页router.back();// 接收参数constparamsrouter.getParams()asRecordstring,Object;if(paramsparams[packageData]){this.packageDataparams[packageData]asPackageItem;}五、资源管理体系鸿蒙的资源系统通过$r()引用支持根据设备配置密度、语言、深色模式等自动切换。5.1 string.json — 字符串资源{string:[{name:title_home,value:我的包裹},{name:title_add_package,value:添加包裹},{name:btn_save,value:保存},{name:status_transit,value:运输中},{name:status_delivered,value:已签收},{name:status_exception,value:异常}]}5.2 color.json — 颜色资源{color:[{name:primary,value:#FF4A90D9},{name:background,value:#FFF5F5F5},{name:card_bg,value:#FFFFFF},{name:text_primary,value:#FF333333},{name:text_secondary,value:#FF666666},{name:text_hint,value:#FF999999},{name:divider,value:#FFE0E0E0},{name:status_transit,value:#FFFF8C00},{name:status_delivered,value:#FF4CAF50},{name:status_exception,value:#FFF44336},{name:rating_star,value:#FFFFC107}]}5.3 float.json — 字号与尺寸资源{float:[{name:page_title_font_size,value:22fp},{name:body_font_size,value:16fp},{name:small_font_size,value:13fp},{name:badge_font_size,value:11fp},{name:card_corner_radius,value:12vp},{name:btn_corner_radius,value:8vp},{name:padding_medium,value:16vp}]}fpFont Pixel是鸿蒙的字号单位自带字体缩放适配vpVirtual Pixel是虚拟像素与 dp 类似。5.4 在 ArkTS 中使用资源Text($r(app.string.title_home)).fontSize($r(app.float.page_title_font_size)).fontColor($r(app.color.text_primary)).backgroundColor($r(app.color.primary))重要约定app_name只在AppScope的string.json中定义一次不能在 entry 模块中重复定义否则会冲突。5.5 深色模式适配在entry/src/main/resources/dark/element/color.json中可以配置深色模式下的颜色值系统会根据系统主题自动切换。六、底层构建系统Hvigor鸿蒙使用自研的Hvigor构建系统类似于 Gradle构建命令如下hvigorw--modemodule-pmoduleentrydefault-pproductdefault\-prequiredDeviceTypephone assembleHap--analyzenormal--parallel--incremental--daemon常用参数--mode module模块级构建-p moduleentrydefault指定模块和 targetassembleHap打包 HAP 文件--parallel并行构建--incremental增量编译--daemon守护进程模式加速后续构建七、小结本篇我们完成了✅ 使用 DevEco Studio 创建鸿蒙原生项目✅ 理解 Stage 模型的 UIAbility 生命周期✅ 理解 module.json5 的配置含义✅ 掌握页面路由注册与跳转标准写法✅ 构建配置文件compatibleSdkVersion / targetSdkVersion✅ 资源管理体系string/color/float $r() 引用✅ API 23 下 router 从ohos.router导入的注意事项下一篇将进入首页与列表开发讲解 List 组件、ForEach 渲染、状态管理、空状态设计等实战内容。系列索引第一篇项目初始化与工程架构本文第二篇首页与列表开发实战第三篇表单交互与搜索筛选第四篇物流时间线与历史记录第五篇数据统计与个人中心
的演进与通信机制)
