HarmonyOS项目结构深度解析：从AppScope到oh_modules
本文将深入解析HarmonyOS项目的完整结构，帮助你理解每个文件和目录的作用，掌握项目配置的核心要点，为大型项目开发打下坚实基础。
一、项目整体结构概览
1.1 标准项目结构树
MyHarmonyOSApp/
├── AppScope/ # 应用级配置和资源
├── entry/ # 主模块
├── feature1/ # 功能模块1
├── feature2/ # 功能模块2
├── library/ # 共享库模块
├── oh_modules/ # 第三方依赖库
├── build-profile.json5 # 项目级构建配置
├── hvigorfile.ts # 项目级构建脚本
└── oh-package.json5 # 项目级依赖管理
1.2 各层级作用说明
// 项目配置文件示例：oh-package.json5
{
"name": "my-harmonyos-app",
"version": "1.0.0",
"description": "A sample HarmonyOS application",
"dependencies": {
"@ohos/hypium": "1.0.0", // 测试框架
"@ohos/http": "1.0.0", // 网络请求
"@ohos/router": "1.0.0" // 路由管理
},
"devDependencies": {
"@ohos/hvigor": "1.0.0" // 构建工具
}
}
二、AppScope目录详解
2.1 应用级资源配置
AppScope目录包含整个应用的全局资源配置：
AppScope/
├── resources/
│ ├── base/
│ │ ├── element/ # 字符串、颜色等资源
│ │ ├── media/ # 应用图标和媒体文件
│ │ └── profile/ # 配置文件
│ └── en_US/ # 英文资源
└── app.json5 # 应用级配置
2.2 应用配置文件解析
// AppScope/app.json5
{
"app": {
"bundleName": "com.example.myapp",
"vendor": "example",
"versionCode": 1000000,
"versionName": "1.0.0",
"icon": "$media:app_icon",
"label": "$string:app_name",
"description": "$string:app_description",
"distributedNotificationEnabled": true,
"minAPIVersion": 12,
"targetAPIVersion": 12,
"apiReleaseType": "Release"
}
}
2.3 全局资源定义
// AppScope/resources/base/element/string.json
{
"string": [
{
"name": "app_name",
"value": "我的应用"
},
{
"name": "app_description",
"value": "这是一个HarmonyOS示例应用"
},
{
"name": "welcome_message",
"value": "欢迎使用"
}
]
}
// AppScope/resources/base/element/color.json
{
"color": [
{
"name": "primary_color",
"value": "#007DFF"
},
{
"name": "background_color",
"value": "#F5F5F5"
},
{
"name": "text_primary",
"value": "#333333"
}
]
}
三、模块结构深度解析
3.1 主模块（entry）完整结构
entry/
├── src/
│ ├── main/
│ │ ├── ets/
│ │ │ ├── entryability/ # Ability入口
│ │ │ ├── pages/ # 页面组件
│ │ │ ├── utils/ # 工具类
│ │ │ ├── models/ # 数据模型
│ │ │ └── services/ # 服务层
│ │ ├── resources/ # 模块资源
│ │ └── module.json5 # 模块配置
│ └── ohosTest/ # 测试代码
├── build-profile.json5 # 模块构建配置
├── hvigorfile.ts # 模块构建脚本
└── oh-package.json5 # 模块依赖管理
3.2 模块配置文件详解
// entry/src/main/module.json5
{
"module": {
"name": "entry",
"type": "entry",
"description": "$string:module_desc",
"mainElement": "EntryAbility",
"deviceTypes": [
"phone",
"tablet",
"tv"
],
"deliveryWithInstall": true,
"installationFree": false,
"pages": "$profile:main_pages",
"abilities": [
{
"name": "EntryAbility",
"srcEntry": "./ets/entryability/EntryAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:icon",
"label": "$string:EntryAbility_label",
"startWindowIcon": "$media:icon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"actions": [
"action.system.home"
],
"entities": [
"entity.system.home"
]
}
]
}
],
"requestPermissions": [
{
"name": "ohos.permission.INTERNET",
"reason": "$string:internet_permission_reason"
},
{
"name": "ohos.permission.LOCATION",
"reason": "$string:location_permission_reason"
}
]
}
}
3.3 页面路由配置
// entry/src/main/resources/base/profile/main_pages.json
{
"src": [
"pages/Index",
"pages/Detail",
"pages/Profile",
"pages/Settings"
]
}
四、功能模块设计
4.1 功能模块结构示例
feature1/
├── src/
│ ├── main/
│ │ ├── ets/
│ │ │ ├── components/ # 专属组件
│ │ │ ├── pages/ # 功能页面
│ │ │ └── utils/ # 功能工具
│ │ └── resources/ # 模块资源
│ └── ohosTest/ # 功能测试
└── oh-package.json5 # 功能依赖
4.2 功能模块配置
// feature1/src/main/module.json5
{
"module": {
"name": "feature1",
"type": "feature",
"description": "$string:feature1_desc",
"mainElement": "Feature1Ability",
"deviceTypes": [
"phone"
],
"deliveryWithInstall": true,
"abilities": [
{
"name": "Feature1Ability",
"srcEntry": "./ets/entryability/Feature1Ability.ets",
"exported": true,
"skills": [
{
"actions": [
"action.example.feature1"
]
}
]
}
]
}
}
五、依赖管理机制
5.1 oh_modules目录结构
oh_modules/
├── @ohos/
│ ├── http/ # 网络请求库
│ ├── router/ # 路由库
│ └── hypium/ # 测试库
├── example-library/ # 第三方库
└── .bin/ # 可执行文件
5.2 依赖配置管理
// entry/oh-package.json5
{
"dependencies": {
"@ohos/http": "1.0.0",
"@ohos/router": "1.0.0",
"example-library": "file:../library"
}
}
// 项目根目录oh-package.json5
{
"dependencies": {
"@ohos/hypium": "1.0.0"
},
"devDependencies": {
"@ohos/hvigor": "1.0.0"
}
}
六、构建配置详解
6.1 项目级构建配置
// build-profile.json5
{
"app": {
"signingConfigs": [
{
"name": "default",
"type": "harmonyOS",
"scope": "global",
"debug": {
"storeFile": "debug.p12",
"storePassword": "123456",
"keyAlias": "debugKey",
"keyPassword": "123456"
},
"release": {
"storeFile": "release.p12",
"storePassword": "your_password",
"keyAlias": "releaseKey",
"keyPassword": "your_password"
}
}
],
"products": [
{
"name": "default",
"signingConfig": "default",
"compileSdkVersion": "5.0.0",
"compatibleSdkVersion": "5.0.0",
"targetAPIVersion": 12,
"minAPIVersion": 12
}
]
},
"modules": [
{
"name": "entry",
"srcPath": "./entry",
"targets": [
{
"name": "default",
"applyToProducts": [
"default"
]
}
]
}
]
}
6.2 构建脚本配置
// hvigorfile.ts
import { harTasks } from '@ohos/hvigor-ohos-plugin'
export default {
system: harTasks, // 如果是HAR包
// 或者使用应用任务
// system: appTasks,
plugins: [
// 自定义插件
],
tasks: {
// 自定义任务
customTask: {
doLast: {
// 任务逻辑
console.log('执行自定义构建任务')
}
}
}
}
七、资源管理策略
7.1 多设备资源适配
resources/
├── base/ # 默认资源
├── en_US/ # 英文资源
├── zh_CN/ # 中文资源
├── phone/ # 手机资源
├── tablet/ # 平板资源
└── tv/ # 电视资源
7.2 资源引用方式
// 在代码中引用资源
@Component
struct ResourceExample {
build() {
Column() {
// 引用字符串资源
Text($r('app.string.welcome_message'))
.fontSize($r('app.float.text_size'))
.fontColor($r('app.color.primary_color'))
// 引用图片资源
Image($r('app.media.app_icon'))
.width(100)
.height(100)
// 引用尺寸资源
.margin($r('app.float.margin_size'))
}
.width($r('app.float.container_width'))
.height($r('app.float.container_height'))
.backgroundColor($r('app.color.background_color'))
}
}
八、测试代码组织
8.1 测试目录结构
entry/src/ohosTest/
├── ets/
│ ├── test/
│ │ ├── ability/ # Ability测试
│ │ ├── pages/ # 页面测试
│ │ ├── utils/ # 工具类测试
│ │ └── Example.test.ets // 示例测试
│ └── pages/ # 测试页面
└── resources/ # 测试资源
8.2 测试代码示例
// entry/src/ohosTest/ets/test/Example.test.ets
import { describe, it, expect, TestType } from '@ohos/hypium'
import { Index } from '../../../../src/main/ets/pages/Index'
describe('IndexComponentTest', TestType.FUNCTION, () => {
it('test_component_creation', 0, () => {
const index = new Index()
expect(index != null).assertTrue()
})
it('test_initial_state', 0, () => {
const index = new Index()
expect(index.count).assertEqual(0)
})
})
describe('ResourceTest', TestType.FUNCTION, () => {
it('test_resource_loading', 0, () => {
const resource = $r('app.string.app_name')
expect(resource != null).assertTrue()
})
})
九、最佳实践建议
9.1 项目结构优化
// 推荐的目录组织方式
class ProjectStructure {
// 按功能划分模块
static readonly MODULES = {
CORE: 'core', // 核心模块
AUTH: 'auth', // 认证模块
HOME: 'home', // 首页模块
PROFILE: 'profile', // 个人中心模块
SETTINGS: 'settings' // 设置模块
}
// 统一资源命名规范
static readonly RESOURCE_NAMING = {
COLORS: {
PRIMARY: 'color_primary',
SECONDARY: 'color_secondary',
BACKGROUND: 'color_background'
},
DIMENS: {
MARGIN: 'dimen_margin',
PADDING: 'dimen_padding',
CORNER: 'dimen_corner_radius'
}
}
}
9.2 配置管理策略
// 环境配置管理
class EnvironmentConfig {
static readonly DEVELOPMENT = {
API_BASE_URL: 'https://dev.api.example.com',
LOG_LEVEL: 'debug',
ENABLE_DEBUG: true
}
static readonly PRODUCTION = {
API_BASE_URL: 'https://api.example.com',
LOG_LEVEL: 'error',
ENABLE_DEBUG: false
}
static getCurrentConfig() {
// 根据构建类型返回对应配置
return process.env.NODE_ENV === 'production'
? this.PRODUCTION
: this.DEVELOPMENT
}
}
总结
通过本文的详细解析，你应该已经对HarmonyOS项目结构有了全面的理解：
- 层次化结构：AppScope → 模块 → 子目录的清晰层次
- 配置管理：多级配置文件的作用和关联关系
- 资源组织：多设备、多语言的资源适配策略
- 依赖管理：oh_modules机制和依赖配置
- 构建系统：hvigor构建工具和构建配置
掌握项目结构是进行高效开发的基础，建议在实际项目中按照本文的组织规范来管理代码，这将大大提高项目的可维护性和扩展性。
需要参加鸿蒙认证的请点击 鸿蒙认证链接
浙公网安备 33010602011771号