鸿蒙原生应用开发实战（一）：从零搭建"钓点日记"——项目初始化与环境配置全指南

前言

鸿蒙生态正在飞速发展，越来越多开发者开始投入鸿蒙原生应用开发。本文将以一个真实的钓鱼助手App——**“钓点日记”**为案例，手把手带你完成从环境搭建、项目创建到工程架构设计的全过程。

无论你是有经验的移动端开发者，还是刚入门鸿蒙开发的新手，这篇文章都将帮你建立起对鸿蒙Stage模型的完整认知。

---

一、项目背景

"钓点日记"是一款专为钓鱼爱好者设计的工具类App，核心功能包括：

• 附近钓点浏览：查看周边钓点的位置、水深、鱼种和评分
• 渔获记录：记录每次出钓的渔获信息
• 装备管理：管理鱼竿、鱼轮等装备的状态
• 鱼种百科：查阅常见鱼种的习性和钓法技巧
• 天气详情：逐小时和7天天气预报，附带钓鱼建议
• 钓点地图：可视化展示钓点分布

技术选型上，我们采用 Stage模型 + ArkTS语言 + ArkUI框架，这是当前鸿蒙应用开发的标准技术栈。

---

二、开发环境搭建

2.1 DevEco Studio 安装

首先从华为开发者官网下载 DevEco Studio（当前推荐版本 5.0+）。安装过程中注意：

1. 安装路径不要包含中文和空格
2. SDK管理器中勾选 API 23 及以上版本的SDK
3. 配置Node.js路径（DevEco内置了Node，也可以使用自定义路径）

2.2 创建项目

打开DevEco Studio，选择 Create Project：

• 模板：Empty Ability（空模板，我们从零开始搭建）
• Project Name：MyApplication
• Bundle Name：com.fishingspot.app
• Compile SDK：API 23
• Compatible SDK：API 23
• Device Type：Phone

创建完成后，你会看到如下目录结构：

MyApplication/
├── AppScope/                   # 全局应用配置
│   ├── app.json5               # 应用级配置（bundleName、版本等）
│   └── resources/
│       └── base/element/
│           └── string.json     # 全局字符串资源
├── entry/                      # 应用模块
│   ├── src/main/
│   │   ├── ets/                # 源码目录
│   │   │   ├── entryability/   # Ability入口
│   │   │   └── pages/          # 页面文件
│   │   ├── module.json5        # 模块配置
│   │   └── resources/          # 资源文件
│   └── build-profile.json5     # 模块构建配置
├── build-profile.json5         # 项目级构建配置
├── hvigor/                     # 构建工具配置
└── oh-package.json5            # 包管理配置

---

三、Stage模型深度解析

鸿蒙从API 9开始全面推行 Stage模型，替代了早期的FA模型。理解Stage模型是开发的第一步。

3.1 核心概念

Stage模型的核心是 Ability 和 Window 的分离：

• UIAbility：应用的入口，管理应用生命周期
• WindowStage：窗口阶段，负责窗口创建和页面加载
• @Entry + @Component：页面组件，每个.ets文件就是一个页面

3.2 EntryAbility 解读

我们来看项目生成的入口文件 EntryAbility.ets：

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

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 应用创建时的初始化逻辑
  }

  onDestroy(): void {
    // 应用销毁时的清理逻辑
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    // 窗口创建时加载首页
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        // 错误处理
        return;
      }
    });
  }
}

关键点：

• onCreate → onWindowStageCreate → onForeground 是启动时序
• windowStage.loadContent 加载首页页面
• 页面路径相对于 src/main/ets/ 目录

3.3 module.json5 配置

entry/src/main/module.json5 是模块的配置文件，其中注册了Ability：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "deviceTypes": ["phone"],
    "pages": "$profile:main_pages",  // 引用页面路由配置
    "abilities": [{
      "name": "EntryAbility",
      "srcEntry": "./ets/entryability/EntryAbility.ets",
      "label": "$string:EntryAbility_label",
      "startWindowIcon": "$media:startIcon",
      "startWindowBackground": "$color:start_window_background",
      "exported": true,
      "skills": [{
        "entities": ["entity.system.home"],
        "actions": ["ohos.want.action.home"]
      }]
    }]
  }
}

注意这里的 $profile:main_pages 指向了资源目录下的 main_pages.json，这是路由的集中式管理方式。

---

四、路由注册机制

在鸿蒙Stage模型中，页面路由必须先在 main_pages.json 中注册。这是我们项目的路由配置：

{
  "src": [
    "pages/Index",
    "pages/SpotDetailPage",
    "pages/CatchRecordPage",
    "pages/GearPage",
    "pages/ProfilePage",
    "pages/FishEncyclopediaPage",
    "pages/WeatherDetailPage",
    "pages/SpotsMapPage"
  ]
}

重要规则：

1. 路径相对于 src/main/ets/ 目录
2. 不带 .ets 后缀
3. 每新增一个页面，必须在这里注册
4. 首页（Index）排第一位

页面间跳转使用 @ohos.router 模块：

import router from '@ohos.router';

// 跳转到详情页，带参数
let opt = { url: 'pages/SpotDetailPage', params: { spotData: spot } };
router.pushUrl(opt);

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

接收参数：

const params = router.getParams() as SpotDetailParams;

坑点提醒：在API 23下，router 从 @ohos.router 导入，不要使用 @kit.AbilityKit 的 router（该版本不导出）。

---

五、资源管理体系

鸿蒙的资源管理非常强大，支持国际化、多设备适配。我们的项目使用了三层资源体系：

5.1 资源文件结构

resources/
├── base/           # 默认资源
│   ├── element/
│   │   ├── string.json    # 字符串
│   │   ├── color.json     # 颜色
│   │   └── float.json     # 尺寸/字号
│   ├── media/             # 图片资源
│   └── profile/           # 配置文件
├── dark/           # 深色模式资源
└── rawfile/        # 原始文件

5.2 资源引用方式

使用 $r() 语法引用资源：

// 字符串
Text($r('app.string.title_home'))

// 颜色
.backgroundColor($r('app.color.primary'))

// 尺寸
.fontSize($r('app.float.page_title_font_size'))

5.3 资源定义示例

string.json（entry模块级别）：

{
  "string": [
    { "name": "title_home", "value": "附近钓点" },
    { "name": "title_spot_detail", "value": "钓点详情" },
    { "name": "no_spots", "value": "暂无钓点数据" }
  ]
}

color.json（定义主题色板）：

{
  "color": [
    { "name": "primary", "value": "#FF2E7D32" },     // 主题绿
    { "name": "background", "value": "#FFF5F5F5" },  // 背景灰
    { "name": "text_primary", "value": "#FF333333" }, // 主文字
    { "name": "rating_star", "value": "#FFFFC107" }  // 星星黄
  ]
}

float.json（统一定义字号和间距）：

{
  "float": [
    { "name": "page_title_font_size", "value": "22fp" },
    { "name": "body_font_size", "value": "16fp" },
    { "name": "card_corner_radius", "value": "12vp" }
  ]
}

全局 vs 模块资源：

• AppScope/resources/ 下的资源是全局共享的
• entry/resources/ 下的资源是模块私有的
• app_name 只需在 AppScope 中定义一次，不可重复定义

---

六、小结

本篇我们完成了：

1. ✅ 开发环境搭建和项目创建
2. ✅ Stage模型核心概念理解
3. ✅ Ability生命周期与窗口管理
4. ✅ 页面路由注册机制
5. ✅ 资源管理体系的搭建

至此，项目的骨架已经搭建完毕。下一篇文章我们将正式进入编码阶段，从首页开始构建钓点列表和底部导航，敬请期待！

---

项目源码：基于 HarmonyOS API 23 + Stage模型 + ArkTS

系列目录：

• 第一篇：项目初始化与环境配置（本篇）
• 第二篇：首页与钓点列表开发
• 第三篇：数据管理与多页面交互
• 第四篇：复杂页面与交互体验
• 第五篇：地图可视化与性能优化