baidu-maps/harmony-sdk-skills/harmony-empty-project

HarmonyOS NEXT 空工程模板

适用场景

当用户提到以下需求时，使用本技能：

• 创建 HarmonyOS NEXT 空工程 / 空项目 / 最小可运行工程
• 为示例（如地图、SDK Demo 等）快速生成可运行的壳工程
• 在当前仓库中从零创建一个标准 HarmonyOS NEXT 最小工程

本技能指导代理从零创建一个标准的 HarmonyOS NEXT 基于 Stage 模型 + ArkTS的最小可运行工程结构。

工程结构参考（最小可运行工程）

从零创建 HarmonyOS NEXT 空工程时，建议使用如下通用结构（以 {ProjectName} 占位）：

• {ProjectName}/
• oh-package.json5
• build-profile.json5
• hvigorfile.ts
• hvigor/
• hvigor-config.json5
• AppScope/
• app.json5
• resources/...
• entry/
• oh-package.json5
• build-profile.json5
• hvigorfile.ts
• src/main/module.json5
• src/main/ets/entryability/EntryAbility.ets
• src/main/ets/entrybackupability/EntryBackupAbility.ets（可选）
• src/main/ets/pages/Index.ets
• src/main/resources/...

以上结构即为一个最小可运行的 HarmonyOS NEXT 应用工程的推荐布局。

快速使用流程（为用户创建空工程）

当用户要求“创建一个标准的鸿蒙空工程 / HarmonyOS NEXT 最小工程”时，按照以下步骤执行。

步骤一：确认目标信息

从用户上下文中推断或向用户确认（如有必要）：

• 目标工程目录名（例如：harmony-demo, harmony-map-demo）
• 应用包名（如：com.example.demoapp）
• 应用显示名称（如：DemoApp）

工程包名生成规则：

• 若用户明确给出包名（如 com.example.mapdemo），则严格使用用户指定的包名，不要自动改写或追加后缀。
• 若用户未指定包名，则优先根据应用主题 / 业务场景自动生成包名，例如：
• 主题为“地图 Demo”时，可生成 com.example.mapdemo
• 主题为“健康记录”时，可生成 com.example.healthrecord
• 仅当无法从上下文推断出清晰主题时，才退回到通用占位包名（如下所示）。

如果用户未明确指定，使用合理默认值：

• 目录名：harmony-demo
• 包名：默认根据应用主题生成一个语义化包名；若无法识别主题，则使用 com.example.harmonydemo
• 应用名称：Harmony Demo

步骤二：创建工程目录与基础文件

1. 在当前工作目录下创建工程根目录，例如：

• {ProjectName}/（如 harmony-demo/）

1. 在 {ProjectName}/ 下创建以下文件和目录：

• oh-package.json5：包含 modelVersion、description、dependencies、devDependencies 等基本字段，例如：
• modelVersion: "6.0.0"
• devDependencies 中可包含 @ohos/hypium、@ohos/hamock 以支持测试
• 依赖写入规则：一旦在工程中使用某个三方或系统依赖（如地图库、网络库等），必须将对应依赖显式写入到合适层级的 oh-package.json5 的 dependencies 字段中，而不是只在代码中直接 import。
• build-profile.json5：定义 app 级产品与构建模式（products、buildModeSet 等），targetSdkVersion、compatibleSdkVersion 需与开发环境匹配
• hvigorfile.ts：导入 appTasks 并导出默认配置：
• system: appTasks
• plugins: []
• hvigor/hvigor-config.json5：Hvigor 全局配置文件，如果缺失会导致类似 “Hvigor config file .../hvigor/hvigor-config.json5 does not exist” 的构建错误
• AppScope/app.json5：定义 bundleName、vendor、versionCode、versionName、icon、label 等
• AppScope/resources/：至少包含基础字符串和图标资源（可由代理按最小配置生成占位资源）；若使用 layered_image 作为应用图标，须在 AppScope/resources/base/media/ 下同时提供 layered_image.json 及其引用的 background、foreground 媒体文件（如 background.svg、foreground.svg），否则会报资源包错误 11211120。

1. 在 {ProjectName}/entry/ 下创建模块目录及以下文件：

• oh-package.json5：entry 模块自身的包配置文件（与根目录 oh-package.json5 独立，用于避免 DevEco / 构建工具报错 “Missing file \"oh-package.json5\" in entry”）。当某个依赖只在 entry 模块中被使用时，应优先将该依赖写入 entry 模块的 `oh-package.json5` 的 `dependencies` 中。
• build-profile.json5：定义 entry 模块构建配置
• hvigorfile.ts：导入 hapTasks 并导出默认配置：
• system: hapTasks
• plugins: []
• src/main/module.json5：定义模块名、类型、mainElement、deviceTypes、pages、abilities 等
• src/main/ets/entryability/EntryAbility.ets 与 src/main/ets/pages/Index.ets：包含最小 UI 与能力入口代码
• src/main/resources/：包含页面引用到的字符串、浮点值、颜色等资源 JSON

依赖管理与安装规则

• 依赖声明位置：
• 在工程中使用到的任意 ohpm 依赖（例如 @bdmap/base、@bdmap/map 等），必须写入实际使用该依赖的具体模块的 oh-package.json5 的 dependencies 字段中（如仅 entry 使用，则写入 {ProjectName}/entry/oh-package.json5）。
• 若依赖为整个应用多个模块共享，可根据实际情况写入工程根目录 oh-package.json5，但仍需保证使用模块的构建能够解析到该依赖。
• 尝试安装依赖：
• 在为用户创建或修改工程时，代理应在对应工程目录（通常为 {ProjectName}/）下尝试执行 ohpm install，以实际安装 oh-package.json5 中声明的依赖。
• 如运行环境不支持实际执行安装命令，应在回答中明确提示用户需要在工程目录手动执行 ohpm install 或相应安装命令，并保证 oh-package.json5 中的依赖列表是完整、正确的。

步骤三：修改应用基础信息

在新工程目录（例如 {ProjectName}/）中，按以下要点设置或修改配置：

• 应用范围信息：`AppScope/app.json5`
• 路径：{ProjectName}/AppScope/app.json5
• 字段：
• bundleName: 设置为目标包名（如 com.example.harmonydemo）
• label: 通常引用字符串资源（如 $string:app_name），如需要可以保持不变
• versionCode / versionName: 若用户要求特定版本号则相应调整

• 如有需要，调整工程名和产品信息：`build-profile.json5`
• 路径：{ProjectName}/build-profile.json5
• 通常保持默认即可；如用户对产品名等有要求，可在 products 中微调。

步骤四：确认模块配置完整

在新工程目录中，检查下列关键文件是否存在且结构完整（通常只需确认，无需改动）：

• {ProjectName}/oh-package.json5
• modelVersion 字段存在，例如 "6.0.0"
• 如需使用测试框架，devDependencies 中包含 @ohos/hypium 等依赖

• {ProjectName}/entry/src/main/module.json5
• module.name 为 "entry"
• mainElement 指向 "EntryAbility"
• pages 指向 $profile:main_pages
• abilities[0].srcEntry 指向 ./ets/entryability/EntryAbility.ets

• {ProjectName}/hvigorfile.ts 与 {ProjectName}/entry/hvigorfile.ts
• 顶层使用 appTasks，entry 模块使用 hapTasks

步骤五：调整首页页面（可选）

如果用户希望定制一个简单首页（而不仅仅是默认 Hello World），可以修改：

• 路径：{ProjectName}/entry/src/main/ets/pages/Index.ets

保持结构为一个 @Entry + @Component 组件，内部 build() 返回一个基础布局（如 RelativeContainer 或 Column）和一个 Text 文本，确保页面结构简单且可编译。

可行性自检（代理执行时的验证要点）

在为用户创建好新的空工程目录后，代理应进行以下自查，以验证结构可行性：

1. 结构检查

• 必须存在：
• {ProjectName}/oh-package.json5
• {ProjectName}/build-profile.json5
• {ProjectName}/hvigorfile.ts
• {ProjectName}/hvigor/hvigor-config.json5
• {ProjectName}/AppScope/app.json5
• {ProjectName}/entry/oh-package.json5
• {ProjectName}/entry/hvigorfile.ts
• {ProjectName}/entry/src/main/module.json5
• {ProjectName}/entry/src/main/ets/pages/Index.ets
• 如果这些文件缺失，由代理补充创建缺失的文件或向用户报告当前结构不完整。

1. 配置一致性检查

• AppScope/app.json5 中的 bundleName 与用户目标包名一致。
• entry/src/main/module.json5 中：
• mainElement 指向的能力在 abilities 列表中真实存在。
• abilities[0].srcEntry 指向的 .ets 文件实际存在。

1. 构建前检查（Auto Run 建议）

• 如果环境中已安装 HarmonyOS NEXT 构建工具链，建议将 Hvigor 构建命令配置为 auto run 流程的一部分：在新工程创建完成或模板被修改后，在新工程目录下自动运行 hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon（或 DevEco Studio 提供的等效构建命令），并确认无明显结构性错误。
• 对基于本空工程继续开发的场景，建议在仓库层面配置提交前或 CI 的 auto run 脚本，统一执行上述构建命令，确保任何基于该模板的改动都能通过基本编译检查。
• 如果构建工具不可用，则以结构符合本技能中“工程结构参考”与“可行性自检”的要求为“可行”的判断标准，并在文档或回答中提示用户需要在本地具备工具链后手动执行 hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon 完成最终校验。

资源包与媒体资源约束（必读）

为避免构建报错 Error Code: 11211120, Resource Pack Error: The resource reference '$media:xxx' is not defined，创建或复制空工程时须遵守以下约束：

1. layered_image 与引用必须成对存在

• layered_image.json 中引用的 $media:background、$media:foreground 表示同目录下必须存在名为 background、foreground 的媒体文件（如 background.svg、foreground.svg）。
• 若在 AppScope 使用 icon: "$media:layered_image"（见 AppScope/app.json5），则必须在 AppScope/resources/base/media/ 下同时放置：
• layered_image.json
• background.svg（或 background.png，推荐 svg）
• foreground.svg（或 foreground.png，推荐 svg）
• 若在 entry 模块使用 icon: "$media:layered_image"（见 entry/src/main/module.json5），则必须在 entry/src/main/resources/base/media/ 下同样放置上述三件（或至少 background、foreground 两个媒体文件 + layered_image.json）。
• 仅复制 layered_image.json 而不复制或创建 background、foreground 媒体文件会导致 11211120 报错。

1. 其他 $media 引用

• 配置中出现的任意 $media:资源名（如 $media:startIcon）都必须在对应模块的 resources/base/media/ 下存在同名文件（如 startIcon.svg），否则同样会触发资源包错误。
• $media:资源名 的解析只发生在工程自身的资源目录（如 entry/src/main/resources/base/media/、AppScope/resources/base/media/），不会从 .cursor/skills/... 等技能目录读取；技能文档仅用于指导代理生成/拷贝资源源码。

1. 代理创建空工程时的要求

• 使用本技能模板创建新工程时，凡涉及 layered_image.json 的目录，必须一并生成或说明需要放置的 background、foreground 媒体文件（推荐使用最小可用的 svg 占位图），不得只创建 layered_image.json。
• 图标统一使用 svg：应用/能力图标相关媒体资源（包括但不限于 layered_image 的 background/foreground、startWindowIcon 的 startIcon）应优先生成 svg 格式文件。
• 生成优先级规则：优先根据用户 app 场景（应用名称/主题/业务类型，如地图、出行、工具等）自动生成符合场景的 svg；若生成失败或用户未提供任何场景信息，再从本技能文档中提供的示例源码拷贝一份作为兜底占位资源（并仍写入到工程的 resources/base/media/ 下）。

更多说明见 HarmonyOS 资源工具 restool。

参考模板代码

本节以仓库中提供的标准最小可执行示例工程为蓝本，给出最小可执行工程的模板代码与配置。代理在生成文件时应与此保持一致（仅替换目录名 / 包名等标识），并确保图标等媒体资源使用 svg 而非 png。

1. 根目录 oh-package.json5

{ "modelVersion": "6.0.0", "description": "Please describe the basic information.", "dependencies": { }, "devDependencies": { "@ohos/hypium": "1.0.24", "@ohos/hamock": "1.0.0" } }

2. 根目录 build-profile.json5

{ "app": { "signingConfigs": [], "products": [ { "name": "default", "signingConfig": "default", "targetSdkVersion": "6.0.0(20)", "compatibleSdkVersion": "5.0.4(16)", "runtimeOS": "HarmonyOS", "buildOption": { "strictMode": { "caseSensitiveCheck": true, "useNormalizedOHMUrl": true } } } ], "buildModeSet": [ { "name": "debug", }, { "name": "release" } ] }, "modules": [ { "name": "entry", "srcPath": "./entry", "targets": [ { "name": "default", "applyToProducts": [ "default" ] } ] } ] }

3. 根目录 hvigorfile.ts

import { appTasks } from '@ohos/hvigor-ohos-plugin';

export default { system: appTasks, / Built-in plugin of Hvigor. It cannot be modified. / plugins: [] / Custom plugin to extend the functionality of Hvigor. / }

4. 根目录 hvigor/hvigor-config.json5

{ "modelVersion": "6.0.0", "dependencies": { }, "execution": { // "analyze": "normal", // "daemon": true, // "incremental": true, // "parallel": true, // "typeCheck": false, // "optimizationStrategy": "memory" }, "logging": { // "level": "info" }, "debugging": { // "stacktrace": false }, "nodeOptions": { // "maxOldSpaceSize": 8192, // "exposeGC": true } }

5. AppScope/app.json5

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

6. AppScope/resources/base/element/string.json

{ "string": [ { "name": "app_name", "value": "Harmony Demo" } ] }

7. AppScope/resources/base/media/layered_image.json

{ "layered-image": { "background": "$media:background", "foreground": "$media:foreground" } }

约束：$media:background、$media:foreground 必须在同目录 AppScope/resources/base/media/ 下存在对应文件（如 background.svg、foreground.svg），否则构建报错 11211120。详见上文「资源包与媒体资源约束」。推荐使用 svg，勿仅创建本 JSON 而不创建 background/foreground 文件。

8. entry 模块 oh-package.json5

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

9. entry 模块 build-profile.json5

{ "apiType": "stageMode", "buildOption": { "resOptions": { "copyCodeResource": { "enable": false } } }, "buildOptionSet": [ { "name": "release", "arkOptions": { "obfuscation": { "ruleOptions": { "enable": false, "files": [ "./obfuscation-rules.txt" ] } } } }, ], "targets": [ { "name": "default" }, { "name": "ohosTest", } ] }

10. entry 模块 hvigorfile.ts

import { hapTasks } from '@ohos/hvigor-ohos-plugin';

export default { system: hapTasks, / Built-in plugin of Hvigor. It cannot be modified. / plugins: [] / Custom plugin to extend the functionality of Hvigor. / }

11. entry 模块 src/main/module.json5