鸿蒙原生应用开发实战一从零搭建钓点日记——项目初始化与环境配置全指南前言鸿蒙生态正在飞速发展越来越多开发者开始投入鸿蒙原生应用开发。本文将以一个真实的钓鱼助手App——**“钓点日记”**为案例手把手带你完成从环境搭建、项目创建到工程架构设计的全过程。无论你是有经验的移动端开发者还是刚入门鸿蒙开发的新手这篇文章都将帮你建立起对鸿蒙Stage模型的完整认知。一、项目背景钓点日记是一款专为钓鱼爱好者设计的工具类App核心功能包括附近钓点浏览查看周边钓点的位置、水深、鱼种和评分渔获记录记录每次出钓的渔获信息装备管理管理鱼竿、鱼轮等装备的状态鱼种百科查阅常见鱼种的习性和钓法技巧天气详情逐小时和7天天气预报附带钓鱼建议钓点地图可视化展示钓点分布技术选型上我们采用Stage模型 ArkTS语言 ArkUI框架这是当前鸿蒙应用开发的标准技术栈。二、开发环境搭建2.1 DevEco Studio 安装首先从华为开发者官网下载DevEco Studio当前推荐版本 5.0。安装过程中注意安装路径不要包含中文和空格SDK管理器中勾选API 23及以上版本的SDK配置Node.js路径DevEco内置了Node也可以使用自定义路径2.2 创建项目打开DevEco Studio选择Create Project模板Empty Ability空模板我们从零开始搭建Project NameMyApplicationBundle Namecom.fishingspot.appCompile SDKAPI 23Compatible SDKAPI 23Device TypePhone创建完成后你会看到如下目录结构MyApplication/ ├── AppScope/ # 全局应用配置 │ ├── app.json5 # 应用级配置bundleName、版本等 │ └── resources/ │ └── base/element/ │ └── string.json # 全局字符串资源 ├── entry/ # 应用模块 │ ├── src/main/ │ │ ├── ets/ # 源码目录 │ │ │ ├── entryability/ # Ability入口 │ │ │ └── pages/ # 页面文件 │ │ ├── module.json5 # 模块配置 │ │ └── resources/ # 资源文件 │ └── build-profile.json5 # 模块构建配置 ├── build-profile.json5 # 项目级构建配置 ├── hvigor/ # 构建工具配置 └── oh-package.json5 # 包管理配置三、Stage模型深度解析鸿蒙从API 9开始全面推行Stage模型替代了早期的FA模型。理解Stage模型是开发的第一步。3.1 核心概念Stage模型的核心是Ability和Window的分离UIAbility应用的入口管理应用生命周期WindowStage窗口阶段负责窗口创建和页面加载Entry Component页面组件每个.ets文件就是一个页面3.2 EntryAbility 解读我们来看项目生成的入口文件EntryAbility.etsimport{AbilityConstant,UIAbility,Want}fromkit.AbilityKit;import{window}fromkit.ArkUI;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{// 应用创建时的初始化逻辑}onDestroy():void{// 应用销毁时的清理逻辑}onWindowStageCreate(windowStage:window.WindowStage):void{// 窗口创建时加载首页windowStage.loadContent(pages/Index,(err){if(err.code){// 错误处理return;}});}}关键点onCreate→onWindowStageCreate→onForeground是启动时序windowStage.loadContent加载首页页面页面路径相对于src/main/ets/目录3.3 module.json5 配置entry/src/main/module.json5是模块的配置文件其中注册了Ability{ module: { name: entry, type: entry, deviceTypes: [phone], pages: $profile:main_pages, // 引用页面路由配置 abilities: [{ name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [{ entities: [entity.system.home], actions: [ohos.want.action.home] }] }] } }注意这里的$profile:main_pages指向了资源目录下的main_pages.json这是路由的集中式管理方式。四、路由注册机制在鸿蒙Stage模型中页面路由必须先在main_pages.json中注册。这是我们项目的路由配置{src:[pages/Index,pages/SpotDetailPage,pages/CatchRecordPage,pages/GearPage,pages/ProfilePage,pages/FishEncyclopediaPage,pages/WeatherDetailPage,pages/SpotsMapPage]}重要规则路径相对于src/main/ets/目录不带.ets后缀每新增一个页面必须在这里注册首页Index排第一位页面间跳转使用ohos.router模块importrouterfromohos.router;// 跳转到详情页带参数letopt{url:pages/SpotDetailPage,params:{spotData:spot}};router.pushUrl(opt);// 返回上一页router.back();接收参数constparamsrouter.getParams()asSpotDetailParams;坑点提醒在API 23下router从ohos.router导入不要使用kit.AbilityKit的 router该版本不导出。五、资源管理体系鸿蒙的资源管理非常强大支持国际化、多设备适配。我们的项目使用了三层资源体系5.1 资源文件结构resources/ ├── base/ # 默认资源 │ ├── element/ │ │ ├── string.json # 字符串 │ │ ├── color.json # 颜色 │ │ └── float.json # 尺寸/字号 │ ├── media/ # 图片资源 │ └── profile/ # 配置文件 ├── dark/ # 深色模式资源 └── rawfile/ # 原始文件5.2 资源引用方式使用$r()语法引用资源// 字符串Text($r(app.string.title_home))// 颜色.backgroundColor($r(app.color.primary))// 尺寸.fontSize($r(app.float.page_title_font_size))5.3 资源定义示例string.jsonentry模块级别{string:[{name:title_home,value:附近钓点},{name:title_spot_detail,value:钓点详情},{name:no_spots,value:暂无钓点数据}]}color.json定义主题色板{color:[{name:primary,value:#FF2E7D32},// 主题绿{name:background,value:#FFF5F5F5},// 背景灰{name:text_primary,value:#FF333333},// 主文字{name:rating_star,value:#FFFFC107}// 星星黄]}float.json统一定义字号和间距{float:[{name:page_title_font_size,value:22fp},{name:body_font_size,value:16fp},{name:card_corner_radius,value:12vp}]}全局 vs 模块资源AppScope/resources/下的资源是全局共享的entry/resources/下的资源是模块私有的app_name只需在AppScope中定义一次不可重复定义六、小结本篇我们完成了✅ 开发环境搭建和项目创建✅ Stage模型核心概念理解✅ Ability生命周期与窗口管理✅ 页面路由注册机制✅ 资源管理体系的搭建至此项目的骨架已经搭建完毕。下一篇文章我们将正式进入编码阶段从首页开始构建钓点列表和底部导航敬请期待项目源码基于 HarmonyOS API 23 Stage模型 ArkTS系列目录第一篇项目初始化与环境配置本篇第二篇首页与钓点列表开发第三篇数据管理与多页面交互第四篇复杂页面与交互体验第五篇地图可视化与性能优化