鸿蒙原生应用实战（一）：Stage模型项目搭建与页面架构设计

鸿蒙原生应用实战一Stage模型项目搭建与页面架构设计系列目录第一篇项目搭建与页面架构设计 ← 当前第二篇首页开发与全局数据流设计第三篇笔记详情与编辑页面的路由与CRUD第四篇分类浏览与个人中心的多维数据展示第五篇构建调试、异常处理与HAP发布一、前言HarmonyOS 6.1API 23引入了更成熟的 Stage 模型和 ArkTS 声明式 UI 框架。本系列将从一个完整项目——「知识笔记」个人知识管理 App 的实战开发出发带你从零搭建一个多页面、可交互的鸿蒙原生应用。最终效果一个包含首页笔记列表、笔记详情、编辑笔记、分类浏览、个人中心 5 个页面的完整 App。二、项目环境与SDK配置2.1 开发环境DevEco Studio: 最新版本 SDK: API 23 (compatibleSdkVersion 23, targetSdkVersion 24) 框架: Stage 模型 ArkTS 模拟器: Emulator 6.1.0.1152.2 创建项目打开 DevEco Studio → 新建项目 → 选择Empty Ability模板 → Stage 模型 → ArkTS 语言。2.3 理解SDK版本配置创建完成后根目录下的build-profile.json5控制 SDK 版本{ app: { products: [ { name: default, targetSdkVersion: 6.1.1(24), compatibleSdkVersion: 6.1.0(23), runtimeOS: HarmonyOS } ] } }这里compatibleSdkVersion设为 23表示应用兼容 API 23而targetSdkVersion为 24 表示在 API 24 上测试过。我们不需要改动这个配置。三、项目结构概览创建后的项目结构MyApplication/ ├── AppScope/ # 全局配置 │ ├── app.json5 # 应用级配置bundleName、版本号等 │ └── resources/ │ └── base/element/string.json # 全局字符串资源app_name ├── entry/ # 应用入口模块 │ ├── build-profile.json5 # 模块构建配置 │ ├── src/main/ │ │ ├── ets/ │ │ │ ├── entryability/ # Ability 生命周期 │ │ │ └── pages/ # 页面目录 ← 我们的核心代码 │ │ ├── module.json5 # 模块注册 │ │ └── resources/ # 资源文件 │ └── oh-package.json5 # 依赖配置 ├── hvigor/ # 构建工具配置 └── build-profile.json5 # 项目级构建配置3.1 路由注册页面路由通过main_pages.json注册{src:[pages/Index,pages/NotePage,pages/EditPage,pages/CategoryPage,pages/ProfilePage]}这个文件位于entry/src/main/resources/base/profile/main_pages.json。每个页面路径对应pages/下的一个.ets文件。3.2 Ability 入口module.json5中注册的EntryAbility是应用入口它通过loadContent加载首页// entryability/EntryAbility.etsonWindowStageCreate(windowStage:window.WindowStage):void{windowStage.loadContent(pages/Index,(err){if(err.code){hilog.error(DOMAIN,testTag,Failed to load content: %{public}s,JSON.stringify(err));}});}四、页面架构设计4.1 五页面导航结构我们设计的「知识笔记」App 有 5 个页面底部导航栏提供三个主要入口┌─────────────────────────────────────┐ │ 首页 (Index.ets) │ │ ┌─ 顶部标题栏 ── 头像 ─┐ │ │ │ 搜索栏 │ │ │ │ [全部] [工作] [学习] ..│ │ │ ├──────────────────────┤ │ │ │ 笔记卡片 1 │ │ │ │ 笔记卡片 2 │ │ │ │ 笔记卡片 3 │ │ │ │ ... │ │ │ └──────────────────────┘ │ │ [笔记] [分类] [我的] ← 底部导航│ │ ⊕ 悬浮新建按钮 │ └─────────────────────────────────────┘页面间关系页面路由URL功能数据依赖Indexpages/Index笔记列表首页AppStorage 全局数据NotePagepages/NotePage查看笔记详情路由参数 noteIdEditPagepages/EditPage新建/编辑笔记可选路由参数 noteIdCategoryPagepages/CategoryPage分类浏览AppStorage 全局数据ProfilePagepages/ProfilePage个人中心与统计AppStorage 全局数据4.2 数据模型设计所有页面共享同一个数据模型NoteinterfaceNote{id:number;// 唯一标识title:string;// 笔记标题content:string;// 笔记正文category:string;// 分类工作/学习/生活/灵感date:string;// 日期YYYY-MM-DD}全局状态通过AppStorage共享以 JSON 字符串形式存储所有笔记letstored:string|undefinedAppStorage.getstring(notes);letallNotes:Note[]stored?JSON.parse(stored)asNote[]:[];五、资源文件体系鸿蒙的资源文件系统使用$r()语法引用分三类5.1 颜色资源 (color.json){color:[{name:start_window_background,value:#FFFFFF},{name:primary,value:#007AFF},{name:background,value:#F5F5F5},{name:card_bg,value:#FFFFFF},{name:text_primary,value:#1A1A1A},{name:text_secondary,value:#666666},{name:delete_red,value:#FF3B30}]}5.2 尺寸资源 (float.json){float:[{name:title_font_size,value:24fp},{name:body_font_size,value:16fp},{name:card_radius,value:12vp},{name:page_padding,value:16vp}]}5.3 字符串资源 (string.json)项目中两个 string.json 的职责要分清AppScope/resources/base/element/string.json: 只放app_nameentry/src/main/resources/base/element/string.json: 放所有页面级字符串重要警告app_name不能在两处同时定义否则构建时会报app_name conflict错误。六、第一篇总结本篇我们完成了✅ 创建鸿蒙 Stage 模型项目并理解 SDK 版本配置✅ 规划 5 个页面的路由架构和页面关系✅ 设计数据模型 Note 和全局状态方案✅ 搭建资源文件体系颜色、字体、字符串下一篇将进入核心开发——首页的笔记列表、搜索、分类筛选和悬浮按钮实现以及全局数据流的完整设计。