【鸿蒙原生应用开发实战】第一篇项目初始化与架构设计——从零搭建阅迹阅读应用一、前言HarmonyOS 自诞生以来以其分布式架构和全场景能力受到了广泛关注。随着 API 23HarmonyOS 6.1.0的发布Stage 模型进一步完善ArkTS 语言也日趋成熟。本系列文章将带领大家从零开发一个完整的鸿蒙原生应用——「阅迹」阅读记录与书籍收藏App手把手讲解每一个技术环节。本文是第一篇重点介绍项目初始化、Stage模型架构、数据模型设计以及工程目录规划。二、项目创建与环境配置2.1 开发环境操作系统Windows 11IDEDevEco Studio 内置 Node.js 和 hvigor 构建工具SDK版本HarmonyOS API 23compatibleSdkVersion 23targetSdkVersion 24框架Stage 模型 ArkTS构建工具hvigor华为自研构建系统2.2 创建项目在 DevEco Studio 中选择File → New → Create Project选择Empty Ability模板选择Stage ModelAPI版本选择6.1.0(API 23)。创建完成后项目会自动生成以下基础结构MyApplication/ ├── AppScope/ # 全局应用配置 │ ├── app.json5 # 应用级配置bundleName、版本等 │ └── resources/ # 全局资源 ├── entry/ # 应用主模块 │ └── src/main/ │ ├── ets/ # ArkTS源码目录 │ │ ├── entryability/ # Ability生命周期 │ │ └── pages/ # 页面目录 │ ├── module.json5 # 模块配置文件 │ └── resources/ # 模块资源 ├── build-profile.json5 # 项目级构建配置 └── hvigor/ # 构建配置2.3 核心配置文件解读项目级build-profile.json5中关键配置是 SDK 版本号{ app: { products: [ { compatibleSdkVersion: 6.1.0(23), // 兼容API 23 targetSdkVersion: 6.1.1(24) // 目标API 24 } ] } }注意compatibleSdkVersion表示应用能运行的最低API版本targetSdkVersion表示编译目标版本。三、Stage 模型架构解析Stage 模型是 HarmonyOS 自 API 9 引入的新一代 Ability 架构。与旧的 FA 模型相比Stage 模型有以下核心变化3.1 Ability 与页面的关系EntryAbility (UIAbility) └── WindowStage.loadContent(pages/Index) ├── Index.ets ← 首页 ├── BookListPage.ets ← 列表页 ├── BookDetailPage.ets← 详情页 ├── FavPage.ets ← 收藏页 └── ProfilePage.ets ← 个人中心在EntryAbility.ets中通过onWindowStageCreate生命周期加载首页exportdefaultclassEntryAbilityextendsUIAbility{onWindowStageCreate(windowStage:window.WindowStage):void{windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(0x0000,testTag,Failed: %{public}s,JSON.stringify(err));return;}hilog.info(0x0000,testTag,Succeeded.);});}}3.2 页面路由配置所有页面必须在main_pages.json中注册{src:[pages/Index,pages/BookListPage,pages/BookDetailPage,pages/FavPage,pages/ProfilePage]}四、数据模型设计作为阅读应用核心数据是书籍。我设计了一个Book接口来标准化数据。4.1 定义 Book 接口在entry/src/main/ets/model/BookData.ets中定义exportinterfaceBook{id:number;// 唯一标识title:string;// 书名author:string;// 作者category:string;// 分类文学/科技/历史/哲学/艺术rating:number;// 评分1.0 - 5.0description:string;// 简介year:string;// 出版年份pages:number;// 页数color:string;// 封面颜色替代真实图片}为什么不使用真实图片在鸿蒙应用开发中图片资源需要打包到 HAP 中。为了简化示例且不依赖外部图片我采用纯色背景 文字首字作为替代封面方案既美观又轻量。4.2 构建书籍数据集我准备了10本经典书籍覆盖5个分类分类书籍作者评分文学百年孤独马尔克斯⭐4.8文学活着余华⭐4.9科技算法导论Cormen⭐4.7科技黑客与画家Paul Graham⭐4.5历史人类简史赫拉利⭐4.8历史万历十五年黄仁宇⭐4.6哲学存在与时间海德格尔⭐4.3哲学庄子庄子⭐4.7艺术艺术的故事贡布里希⭐4.9艺术美的历程李泽厚⭐4.64.3 分类常量与工具函数exportconstALL_CATEGORIES:string[][全部,文学,科技,历史,哲学,艺术];// 按分类筛选exportfunctiongetBooksByCategory(category:string):Book[]{if(category全部||category)returnBOOKS;returnBOOKS.filter(bookbook.categorycategory);}// 获取高分推荐评分≥4.7exportfunctiongetRecommendedBooks():Book[]{returnBOOKS.filter(bookbook.rating4.7);}// 生成星级字符串exportfunctiongetStarString(rating:number):string{letstars;for(leti0;i5;i){starsiMath.floor(rating)?★:☆;}returnstars rating.toFixed(1);}这里特别要注意的是ArkTS严格模式的限制。在 API 23 中对象字面量必须有显式类型声明arkts-no-untyped-obj-literals规则数组字面量必须可推断类型。因此必须显式标注类型// ❌ 错误缺少类型声明constbooks[{id:1,title:百年孤独}];// ✅ 正确显式声明类型constBOOKS:Book[][{id:1,title:百年孤独,...}];五、项目目录结构规划最终项目的完整目录结构如下entry/src/main/ets/ ├── entryability/ │ └── EntryAbility.ets # Ability生命周期 ├── entrybackupability/ │ └── EntryBackupAbility.ets # 备份扩展 ├── model/ │ └── BookData.ets # 数据模型层 └── pages/ ├── Index.ets # 首页 ├── BookListPage.ets # 书籍列表 ├── BookDetailPage.ets # 书籍详情 ├── FavPage.ets # 收藏管理 └── ProfilePage.ets # 个人中心分层设计思想model/数据层负责数据定义和查询逻辑与UI解耦pages/视图层每个页面独立文件通过路由连接entryability/应用入口管理生命周期六、资源文件配置HarmonyOS 使用资源文件管理颜色、字符串、尺寸等常量支持多语言和多设备适配。6.1 颜色资源{color:[{name:start_window_background,value:#FFF8F0},{name:primary_color,value:#C4956A},{name:background_color,value:#FFF8F0},{name:text_primary,value:#2C1810},{name:text_secondary,value:#8B7355}]}6.2 字符串资源AppScope/resources/string.json中定义app_name注意app_name只需在 AppScope 中定义一次不可在 entry 中重复定义。6.3 使用资源的最佳实践在 ArkTS 中通过$r()引用资源Text(阅迹).fontSize($r(app.float.title_font_size)).fontColor($r(app.color.text_primary))七、构建与验证配置完成后使用 hvigor 命令构建验证cdMyApplication hvigorw--modemodule-pmoduleentrydefault assembleHap首次构建会启动 hvigor daemon后续构建会增量执行速度更快。构建成功的标志是控制台输出BUILD SUCCESSFUL。八、小结本篇完成了✅ 项目创建与 SDK 配置✅ Stage 模型架构理解✅ 数据模型设计与10本书数据集✅ 资源文件配置✅ 项目目录规划下一篇我们将开始首页开发实现分类快速入口、精选推荐横向滚动、热门榜单列表以及底部导航栏——敬请期待
【鸿蒙原生应用开发实战】第一篇：项目初始化与架构设计——从零搭建“阅迹“阅读应用
【鸿蒙原生应用开发实战】第一篇项目初始化与架构设计——从零搭建阅迹阅读应用一、前言HarmonyOS 自诞生以来以其分布式架构和全场景能力受到了广泛关注。随着 API 23HarmonyOS 6.1.0的发布Stage 模型进一步完善ArkTS 语言也日趋成熟。本系列文章将带领大家从零开发一个完整的鸿蒙原生应用——「阅迹」阅读记录与书籍收藏App手把手讲解每一个技术环节。本文是第一篇重点介绍项目初始化、Stage模型架构、数据模型设计以及工程目录规划。二、项目创建与环境配置2.1 开发环境操作系统Windows 11IDEDevEco Studio 内置 Node.js 和 hvigor 构建工具SDK版本HarmonyOS API 23compatibleSdkVersion 23targetSdkVersion 24框架Stage 模型 ArkTS构建工具hvigor华为自研构建系统2.2 创建项目在 DevEco Studio 中选择File → New → Create Project选择Empty Ability模板选择Stage ModelAPI版本选择6.1.0(API 23)。创建完成后项目会自动生成以下基础结构MyApplication/ ├── AppScope/ # 全局应用配置 │ ├── app.json5 # 应用级配置bundleName、版本等 │ └── resources/ # 全局资源 ├── entry/ # 应用主模块 │ └── src/main/ │ ├── ets/ # ArkTS源码目录 │ │ ├── entryability/ # Ability生命周期 │ │ └── pages/ # 页面目录 │ ├── module.json5 # 模块配置文件 │ └── resources/ # 模块资源 ├── build-profile.json5 # 项目级构建配置 └── hvigor/ # 构建配置2.3 核心配置文件解读项目级build-profile.json5中关键配置是 SDK 版本号{ app: { products: [ { compatibleSdkVersion: 6.1.0(23), // 兼容API 23 targetSdkVersion: 6.1.1(24) // 目标API 24 } ] } }注意compatibleSdkVersion表示应用能运行的最低API版本targetSdkVersion表示编译目标版本。三、Stage 模型架构解析Stage 模型是 HarmonyOS 自 API 9 引入的新一代 Ability 架构。与旧的 FA 模型相比Stage 模型有以下核心变化3.1 Ability 与页面的关系EntryAbility (UIAbility) └── WindowStage.loadContent(pages/Index) ├── Index.ets ← 首页 ├── BookListPage.ets ← 列表页 ├── BookDetailPage.ets← 详情页 ├── FavPage.ets ← 收藏页 └── ProfilePage.ets ← 个人中心在EntryAbility.ets中通过onWindowStageCreate生命周期加载首页exportdefaultclassEntryAbilityextendsUIAbility{onWindowStageCreate(windowStage:window.WindowStage):void{windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(0x0000,testTag,Failed: %{public}s,JSON.stringify(err));return;}hilog.info(0x0000,testTag,Succeeded.);});}}3.2 页面路由配置所有页面必须在main_pages.json中注册{src:[pages/Index,pages/BookListPage,pages/BookDetailPage,pages/FavPage,pages/ProfilePage]}四、数据模型设计作为阅读应用核心数据是书籍。我设计了一个Book接口来标准化数据。4.1 定义 Book 接口在entry/src/main/ets/model/BookData.ets中定义exportinterfaceBook{id:number;// 唯一标识title:string;// 书名author:string;// 作者category:string;// 分类文学/科技/历史/哲学/艺术rating:number;// 评分1.0 - 5.0description:string;// 简介year:string;// 出版年份pages:number;// 页数color:string;// 封面颜色替代真实图片}为什么不使用真实图片在鸿蒙应用开发中图片资源需要打包到 HAP 中。为了简化示例且不依赖外部图片我采用纯色背景 文字首字作为替代封面方案既美观又轻量。4.2 构建书籍数据集我准备了10本经典书籍覆盖5个分类分类书籍作者评分文学百年孤独马尔克斯⭐4.8文学活着余华⭐4.9科技算法导论Cormen⭐4.7科技黑客与画家Paul Graham⭐4.5历史人类简史赫拉利⭐4.8历史万历十五年黄仁宇⭐4.6哲学存在与时间海德格尔⭐4.3哲学庄子庄子⭐4.7艺术艺术的故事贡布里希⭐4.9艺术美的历程李泽厚⭐4.64.3 分类常量与工具函数exportconstALL_CATEGORIES:string[][全部,文学,科技,历史,哲学,艺术];// 按分类筛选exportfunctiongetBooksByCategory(category:string):Book[]{if(category全部||category)returnBOOKS;returnBOOKS.filter(bookbook.categorycategory);}// 获取高分推荐评分≥4.7exportfunctiongetRecommendedBooks():Book[]{returnBOOKS.filter(bookbook.rating4.7);}// 生成星级字符串exportfunctiongetStarString(rating:number):string{letstars;for(leti0;i5;i){starsiMath.floor(rating)?★:☆;}returnstars rating.toFixed(1);}这里特别要注意的是ArkTS严格模式的限制。在 API 23 中对象字面量必须有显式类型声明arkts-no-untyped-obj-literals规则数组字面量必须可推断类型。因此必须显式标注类型// ❌ 错误缺少类型声明constbooks[{id:1,title:百年孤独}];// ✅ 正确显式声明类型constBOOKS:Book[][{id:1,title:百年孤独,...}];五、项目目录结构规划最终项目的完整目录结构如下entry/src/main/ets/ ├── entryability/ │ └── EntryAbility.ets # Ability生命周期 ├── entrybackupability/ │ └── EntryBackupAbility.ets # 备份扩展 ├── model/ │ └── BookData.ets # 数据模型层 └── pages/ ├── Index.ets # 首页 ├── BookListPage.ets # 书籍列表 ├── BookDetailPage.ets # 书籍详情 ├── FavPage.ets # 收藏管理 └── ProfilePage.ets # 个人中心分层设计思想model/数据层负责数据定义和查询逻辑与UI解耦pages/视图层每个页面独立文件通过路由连接entryability/应用入口管理生命周期六、资源文件配置HarmonyOS 使用资源文件管理颜色、字符串、尺寸等常量支持多语言和多设备适配。6.1 颜色资源{color:[{name:start_window_background,value:#FFF8F0},{name:primary_color,value:#C4956A},{name:background_color,value:#FFF8F0},{name:text_primary,value:#2C1810},{name:text_secondary,value:#8B7355}]}6.2 字符串资源AppScope/resources/string.json中定义app_name注意app_name只需在 AppScope 中定义一次不可在 entry 中重复定义。6.3 使用资源的最佳实践在 ArkTS 中通过$r()引用资源Text(阅迹).fontSize($r(app.float.title_font_size)).fontColor($r(app.color.text_primary))七、构建与验证配置完成后使用 hvigor 命令构建验证cdMyApplication hvigorw--modemodule-pmoduleentrydefault assembleHap首次构建会启动 hvigor daemon后续构建会增量执行速度更快。构建成功的标志是控制台输出BUILD SUCCESSFUL。八、小结本篇完成了✅ 项目创建与 SDK 配置✅ Stage 模型架构理解✅ 数据模型设计与10本书数据集✅ 资源文件配置✅ 项目目录规划下一篇我们将开始首页开发实现分类快速入口、精选推荐横向滚动、热门榜单列表以及底部导航栏——敬请期待
