项目结构

了解 HarmonyOS 项目的目录结构，有助于你更好地组织和管理代码。

标准项目结构

一个典型的 HarmonyOS 应用项目结构如下：

MyApplication/
├── AppScope/                    # 应用全局配置
│   └── app.json5               # 应用配置文件
├── entry/                       # 主模块
│   ├── src/
│   │   └── main/
│   │       ├── ets/            # ArkTS 代码目录
│   │       │   ├── entryability/
│   │       │   │   └── EntryAbility.ts
│   │       │   └── pages/
│   │       │       └── Index.ets
│   │       ├── resources/      # 资源文件目录
│   │       │   ├── base/
│   │       │   │   ├── element/
│   │       │   │   ├── media/
│   │       │   │   └── profile/
│   │       │   └── rawfile/
│   │       └── module.json5    # 模块配置文件
│   ├── build-profile.json5     # 模块构建配置
│   └── oh-package.json5        # 模块依赖配置
├── oh_modules/                  # 第三方依赖
├── build-profile.json5         # 应用构建配置
└── oh-package.json5            # 应用依赖配置

目录说明

AppScope

应用级别的全局配置，包含应用图标、应用名称等信息。

app.json5

{
  "app": {
    "bundleName": "com.example.myapp",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name"
  }
}

entry 模块

ets 目录

存放 ArkTS 源代码，是应用的核心业务逻辑所在。

entryability/

• EntryAbility.ts: 应用入口，管理应用生命周期

pages/

• 存放页面文件，每个 .ets 文件对应一个页面

resources 目录

存放应用资源文件。

目录结构：

resources/
├── base/                   # 基础资源
│   ├── element/           # 字符串、颜色等资源
│   │   ├── string.json   # 字符串资源
│   │   └── color.json    # 颜色资源
│   ├── media/            # 图片、音视频等
│   └── profile/          # 配置文件
└── rawfile/              # 原始文件

使用示例：

// 引用字符串资源
Text($r('app.string.hello'))

// 引用图片资源
Image($r('app.media.icon'))

// 引用颜色资源
Text('Hello')
  .fontColor($r('app.color.primary'))

module.json5

模块配置文件，定义模块的基本信息和组件。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet"
    ],
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ts",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label"
      }
    ]
  }
}

配置文件

oh-package.json5

定义项目依赖和基本信息。

{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {}
}

build-profile.json5

构建配置文件，定义编译和打包选项。

{
  "app": {
    "signingConfigs": [],
    "compileSdkVersion": 9,
    "compatibleSdkVersion": 9,
    "products": [
      {
        "name": "default",
        "signingConfig": "default"
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry"
    }
  ]
}

页面配置

main_pages.json

定义应用的页面路由。

位置：entry/src/main/resources/base/profile/main_pages.json

{
  "src": [
    "pages/Index",
    "pages/Second",
    "pages/Detail"
  ]
}

页面顺序

数组中的第一个页面将作为应用的首页。

资源引用

字符串资源

resources/base/element/string.json

{
  "string": [
    {
      "name": "app_name",
      "value": "我的应用"
    },
    {
      "name": "hello_world",
      "value": "你好，世界！"
    }
  ]
}

使用：

Text($r('app.string.hello_world'))

颜色资源

resources/base/element/color.json

{
  "color": [
    {
      "name": "primary",
      "value": "#409EFF"
    },
    {
      "name": "success",
      "value": "#67C23A"
    }
  ]
}

使用：

Text('Hello')
  .fontColor($r('app.color.primary'))

最佳实践

1. 模块化组织

将功能相关的代码组织在一起：

ets/
├── common/              # 公共代码
│   ├── constants/      # 常量定义
│   ├── utils/          # 工具函数
│   └── components/     # 公共组件
├── pages/              # 页面
├── models/             # 数据模型
└── services/           # 业务逻辑

2. 资源命名规范

• 使用小写字母和下划线
• 文件名要有意义，便于维护
• 图片资源建议按功能分类

3. 配置管理

• 环境相关配置独立管理
• 敏感信息不要硬编码
• 使用资源文件管理多语言

下一步

• 配置开发环境
• 学习 ArkTS 语法
• 了解组件开发