鸿蒙原生应用实战（一）：项目初始化与架构设计——从零搭建智能诗词助手

鸿蒙原生应用实战（一）：项目初始化与架构设计------从零搭建智能诗词助手

前言

在 HarmonyOS 生态快速发展的今天，掌握鸿蒙原生应用开发已成为移动开发者的一项重要技能。本文将带领大家从零开始，基于 Stage 模型 + ArkTS + API 23 构建一个完整的 智能诗词助手 应用。

不同于简单的 Hello World 项目，本应用包含 5 个独立页面 、12 套完整诗词数据、跨页面路由传参、搜索筛选、收藏管理等复杂功能，是一个真正具备实用价值的原生应用。

一、项目概述

1.1 应用功能总览

智能诗词助手 是一款面向古典诗词爱好者的阅读鉴赏应用，包含以下核心功能：

页面	功能
首页	每日一首推荐诗词、6 大分类入口、热门排行、为你推荐
诗词库	搜索、朝代/类型双筛选、12 首诗词列表
诗词详情	全文展示、逐词注释、创作背景、名家赏析
作者天地	8 位诗人卡片、朝代筛选、代表作标签
我的收藏	收藏管理、分类分组、编辑模式

1.2 技术栈选型

复制代码

开发工具：DevEco Studio NEXT
框架模型：Stage 模型
开发语言：ArkTS（TypeScript 子集）
SDK 版本：API 23（compatibleSdkVersion 23）
构建工具：Hvigor
目标设备：Phone

二、项目初始化

2.1 创建项目

打开 DevEco Studio，选择 File → New → Create Project：

Project Name: MyApplication（后续可改）
Bundle Name: com.example.myapplication
Device: Phone
Language: ArkTS
Model: Stage

创建后项目结构如下：

复制代码

MyApplication/
├── AppScope/
│   ├── app.json5              # 应用级配置
│   └── resources/
│       └── base/element/
│           └── string.json    # 应用名
├── entry/
│   ├── build-profile.json5    # 模块构建配置
│   └── src/main/
│       ├── ets/
│       │   ├── entryability/  # Ability 入口
│       │   └── pages/         # 页面目录
│       ├── module.json5       # 模块配置
│       └── resources/         # 资源文件
├── build-profile.json5        # 项目构建配置
├── hvigor/                    # Hvigor 配置
└── oh-package.json5           # 包依赖

2.2 SDK 配置确认

关键处是 build-profile.json5 中的 SDK 配置：

json5 复制代码

{
  "app": {
    "products": [
      {
        "name": "default",
        "targetSdkVersion": "6.1.1(24)",
        "compatibleSdkVersion": "6.1.0(23)",
        "runtimeOS": "HarmonyOS"
      }
    ]
  }
}

API 23 的 compatibleSdkVersion 确保了最大的设备兼容性，同时 targetSdkVersion: 24 让我们可以使用最新的 API 特性。

三、页面架构设计

3.1 路由注册

在 main_pages.json 中注册所有页面路由：

json 复制代码

{
  "src": [
    "pages/Index",
    "pages/PoemListPage",
    "pages/PoemDetailPage",
    "pages/AuthorPage",
    "pages/CollectionPage"
  ]
}

3.2 跨页面路由导入规范

API 23 下必须从 @ohos.router 导入路由模块，这是与旧版本区别最大的地方：

typescript 复制代码

// ✅ 正确写法（API 23）
import router from '@ohos.router';

// ❌ 错误写法（该版本不导出）
import router from '@kit.AbilityKit';

3.3 页面跳转方式

typescript 复制代码

// 带参数跳转
router.pushUrl({
  url: 'pages/PoemDetailPage',
  params: { poemId: 3 }
});

// 接收参数
aboutToAppear(): void {
  const params = router.getParams() as Record<string, Object>;
  if (params && params['poemId'] !== undefined) {
    this.poemId = params['poemId'] as number;
  }
}

// 返回上一页
router.back();

3.4 整体路由链路设计

复制代码

首页 ──→ 诗词库（分类/搜索/筛选）
  │           │
  │           └──→ 诗词详情（全文+注释+赏析）
  │
  ├──→ 作者天地（诗人列表）
  │       │
  │       └──→ 诗词库（自动搜索该作者作品）
  │
  └──→ 我的收藏（收藏管理）
          │
          └──→ 诗词详情

四、资源文件规划

4.1 颜色资源

在 color.json 中定义统一色彩系统：

json 复制代码

{
  "color": [
    { "name": "primary_color", "value": "#FF6B35" },
    { "name": "accent_purple", "value": "#8B5CF6" },
    { "name": "accent_green", "value": "#22C55E" },
    { "name": "accent_blue", "value": "#3B82F6" },
    { "name": "accent_red", "value": "#EF4444" },
    { "name": "bg_primary", "value": "#F5F5F5" },
    { "name": "bg_card", "value": "#FFFFFF" },
    { "name": "text_primary", "value": "#1A1A2E" },
    { "name": "text_secondary", "value": "#6B7280" }
  ]
}

4.2 尺寸资源

在 float.json 中定义统一字体和间距：

json 复制代码

{
  "float": [
    { "name": "title_font_size", "value": "24fp" },
    { "name": "subtitle_font_size", "value": "18fp" },
    { "name": "body_font_size", "value": "14fp" },
    { "name": "small_font_size", "value": "12fp" },
    { "name": "card_radius", "value": "16vp" },
    { "name": "spacing_medium", "value": "16vp" }
  ]
}

注意：app_name 只需在 AppScope/resources/base/element/string.json 中定义一次，不可在 entry 模块中重复定义，否则编译会报资源冲突。

五、Stage 模型要点

本应用基于 Stage 模型 ，其核心入口是 EntryAbility.ets：

typescript 复制代码

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        console.error('Failed to load content', JSON.stringify(err));
        return;
      }
    });
  }
}

Stage 模型的特点：

Ability 生命周期独立管理：onCreate → onWindowStageCreate → onForeground → ...
页面通过 loadContent 加载：第一个参数是首页路由
模块化架构：Ability 和页面分离，职责清晰

六、项目目录结构（最终形态）

经过五篇博文的连续开发，项目的完整结构如下：

复制代码

entry/src/main/ets/pages/
├── Index.ets              ← 首页：每日诗词 + 6分类 + 热门排行
├── PoemListPage.ets       ← 诗词库：搜索 + 朝代/类型筛选
├── PoemDetailPage.ets     ← 诗词详情：全文 + 注释 + 背景 + 赏析
├── AuthorPage.ets         ← 作者天地：8位诗人卡片
└── CollectionPage.ets     ← 收藏管理：6首收藏 + 5分类分组

七、开发环境踩坑记录

7.1 路径空格问题

鸿蒙的构建工具链对路径空格敏感，如果你的 DevEco Studio 安装在 D:\Program Files 这类带空格的路径下，命令行构建时需要特别注意引号：

bash 复制代码

# ✅ 正确
cmd /c ""D:\DevEco Studio\tools\node\node.exe" "..."

# ❌ 错误------空格被截断
"D:\DevEco Studio\tools\node\node.exe" "..."

7.2 构建命令

bash 复制代码

cd /d "项目路径"
cmd /c ""D:\DevEco Studio\tools\node\node.exe" "D:\DevEco Studio\tools\hvigor\bin\hvigorw.js" \
  --mode module \
  -p module=entry@default \
  -p product=default \
  -p requiredDeviceType=phone \
  assembleHap \
  --analyze=normal \
  --parallel \
  --incremental \
  --daemon

小结

本章我们完成了项目的初始化、架构设计、路由规划、资源文件配置。下一章将正式进入编码阶段，从首页开始，构建包含每日推荐、分类入口、热门排行等核心功能。

【系列目录】

（一）项目初始化与架构设计 ← 本文
（二）首页与诗词库页面开发
（三）诗词详情与作者天地页面开发
（四）收藏页面与底部导航实现
（五）编译调试与问题修复经验