工程结构

目录结构

MyApp/
├── AppScope/                     # 应用级配置（全局）
│   ├── app.json5                 # ★ 应用级配置：bundleName、版本号、图标
│   └── resources/
│       └── base/
│           ├── element/string.json   # 应用名等字符串资源
│           └── media/                # 应用图标 app_icon.png
│
├── entry/                        # 主 HAP 模块（入口）
│   └── src/
│       ├── main/
│       │   ├── ets/              # ArkTS 源码
│       │   │   ├── entryability/
│       │   │   │   └── EntryAbility.ets   # ★ UIAbility 入口
│       │   │   ├── pages/        # 页面目录
│       │   │   │   └── Index.ets          # ★ 入口页面
│       │   │   └── components/   # 自定义组件
│       │   │       └── Header.ets
│       │   ├── resources/        # 模块资源
│       │   │   └── base/
│       │   │       ├── element/      # string.json / color.json / float.json
│       │   │       ├── media/        # 图片资源
│       │   │       └── profile/      # main_pages.json 路由表等
│       │   └── module.json5      # ★ 模块级配置（最重要）
│       ├── ohosTest/             # 测试代码
│       └── build-profile.json5   # 模块构建配置
│
├── hvigor/                       # 构建脚本
├── build-profile.json5           # ★ 工程构建配置（签名、产物、SDK）
├── oh-package.json5              # ★ 工程依赖（ohpm）
└── hvigorfile.ts

关键配置文件

AppScope/app.json5（应用级）

{
  "app": {
    "bundleName": "com.example.myapp",    // 应用唯一标识，上架后不可改
    "vendor": "example",
    "versionCode": 1,                      // 整数版本号，每次更新递增
    "versionName": "1.0.0",                // 展示版本号
    "icon": "$media:app_icon",            // 应用图标
    "label": "$string:app_name"           // 应用名（引用资源）
  }
}

entry/src/main/module.json5（模块级）

{
  "module": {
    "name": "entry",
    "type": "entry",                      // entry / feature / shared
    "deviceTypes": ["phone", "tablet"],   // 支持设备类型
    "mainElement": "EntryAbility",        // 入口 UIAbility
    "pages": "$profile:main_pages",       // 页面列表（@ohos.router 用）
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:app_icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:app_icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [                        // 启动入口（桌面图标点开）
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ],
    "requestPermissions": [                // ★ 权限声明
      {
        "name": "ohos.permission.INTERNET",
        "reason": "$string:reason_net",
        "usedScene": {}
      }
    ]
  }
}

最常改的地方：

• 加权限 → requestPermissions 加项
• 加 UIAbility → abilities 加项
• 改支持设备 → deviceTypes

resources/base/profile/main_pages.json（路由表）

{
  "src": [
    "pages/Index",
    "pages/DetailPage",
    "pages/SettingsPage"
  ]
}

注意：Navigation 方案的页面不需要在这里登记。

build-profile.json5（工程级）

{
  "app": {
    "signingConfigs": [],      // 上架时配置签名
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compileSdkVersion": 11,
        "compatibleSdkVersion": "10"
      }
    ]
  }
}

oh-package.json5（依赖管理）

{
  "name": "myapp",
  "version": "1.0.0",
  "description": "My HarmonyOS App",
  "dependencies": {
    "@some/lib": "^1.0.0"
  }
}

安装依赖：ohpm install @some/lib

资源引用

资源放 resources/<qualifier>/，qualifier 如 base（默认）、zh_CN（中文）、dark（暗色）。

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

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

// 图片
$r('app.media.logo')

// 尺寸
$r('app.float.title_size')

// 系统资源
$r('sys.color.primary')
$r('sys.string.ok')

资源定义示例：

// resources/base/element/string.json
{
  "string": [
    { "name": "app_name", "value": "我的应用" },
    { "name": "welcome", "value": "欢迎使用" }
  ]
}

// resources/base/element/color.json
{
  "color": [
    { "name": "primary", "value": "#007DFF" },
    { "name": "background", "value": "#F5F5F5" }
  ]
}

多模块工程

大型应用拆分：

模块类型	说明
entry	必须有一个，作为应用入口
feature	按功能拆分的 HAP，动态加载
HSP	动态共享包，多 HAP 共享代码与资源
HAR	静态库，编译时打包进去

创建模块：DevEco → File → New → Module

构建与运行

# 命令行构建
hvigorw assembleHap      # 打 HAP 包
hvigorw assembleApp      # 打 APP 上架包

# 产物位置
entry/build/default/outputs/default/entry-default-signed.hap