鸿蒙原生应用实战（一）：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.ets
onWindowStageCreate(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：

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

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

let stored: string | undefined = AppStorage.get<string>('notes');
let allNotes: Note[] = stored ? JSON.parse(stored) as Note[] : [];

五、资源文件体系

鸿蒙的资源文件系统使用 $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_name
• entry/src/main/resources/base/element/string.json: 放所有页面级字符串

重要警告：app_name 不能在两处同时定义！否则构建时会报 'app_name' conflict 错误。

六、第一篇总结

本篇我们完成了：

1. ✅ 创建鸿蒙 Stage 模型项目并理解 SDK 版本配置
2. ✅ 规划 5 个页面的路由架构和页面关系
3. ✅ 设计数据模型 Note 和全局状态方案
4. ✅ 搭建资源文件体系（颜色、字体、字符串）

下一篇将进入核心开发——首页的笔记列表、搜索、分类筛选和悬浮按钮实现，以及全局数据流的完整设计。

---