当前位置：首页 > news >正文

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

news 2026/6/10 20:10:55

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

系列目录：
第一篇：项目搭建与页面架构设计 ← 当前
第二篇：首页开发与全局数据流设计
第三篇：笔记详情与编辑页面的路由与CRUD
第四篇：分类浏览与个人中心的多维数据展示
第五篇：构建调试、异常处理与HAP发布

一、前言

HarmonyOS 6.1（API 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.115

2.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	功能	数据依赖
Index	`pages/Index`	笔记列表首页	AppStorage 全局数据
NotePage	`pages/NotePage`	查看笔记详情	路由参数 noteId
EditPage	`pages/EditPage`	新建/编辑笔记	可选路由参数 noteId
CategoryPage	`pages/CategoryPage`	分类浏览	AppStorage 全局数据
ProfilePage	`pages/ProfilePage`	个人中心与统计	AppStorage 全局数据

4.2 数据模型设计

所有页面共享同一个数据模型Note：

interfaceNote{id:number;// 唯一标识title:string;// 笔记标题content:string;// 笔记正文category:string;// 分类：工作/学习/生活/灵感date:string;// 日期：YYYY-MM-DD}

全局状态通过AppStorage共享，以 JSON 字符串形式存储所有笔记：

letstored:string|undefined=AppStorage.get<string>('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"}]}