第4章 图解 HarmonyOS 的结构

学习目标

主要图解

内容讲解

App 与 HAP 包

User Pain Point: 很多初学者会把 App Pack 当成单一文件来思考，导致在添加 Feature 模块时不知道应该创建新的 HAP 而不是修改原来的 entry。正确理解 “App Pack + 多个 HAP” 的关系是避免后期拆分困难的关键。

entry 与 Feature 模块对照表：

entry HAP 1 可独立安装运行快递箱里的“主体商品”.类似手机程序主要框架。其实，  Feature HAP 0~N 支持按需安装快递箱里的“可选配件”。类似 Android 的插件式功能

...

In actual implementation ensure proper closing tags and alignment.

HAP 内部结构详述：

• |src/main/java/| Java 源代码，包含 MainAbility、MainAbilitySlice 等类。
• |src/main/resources/| 资源文件。
• |config.json| 应用配置文件。User Pain Point: 许多新手误删此文件导致项目无法编译，记住不要随意移动或重命名它！
.
• |libs/| 第三方依赖库。Pain Point: 忘记在 build.gradle 中声明依赖会导致缺失符号错误。
.
• |build.gradle| 模块建立配置。Pain Point: 若 Gradle 脚本中使用了错误的版本号，同步失败。
. .

Ability 与 AbilitySlice 对比与层次化设计：

Able 是应用所具备的能力抽象，一个应用可以包含一个或多个 Ability。Ability 分为两种类型：

：

• - Page Ability = 表示层
• - Service Ability = 业务层
• - Data Ability = 数据访问层
.

从*常见痛点来看，初学者往往把 Page 和 Service 混淆；别忘了通过 `setMainRoute` 明确默认页面否则启动会报错。

资源文件细节与命名规范：

`resources` 目录下主要分为限定词目录和 rawfile 目录。不过，

/base/element/元素资源string.json。color.json,float.json,…​​​​​​​​​​​​ plaintext string.json color.json float.json integer.json boolean.json pattern.json ​ resources/base/media : 媒体资源图片、音频、视频文件 resources/base/layout: 布局 XML 文件如 ability_main.xml resources/base/graphic: 可绘制资源背景形状定义 XML resources/base/profile: 原始其他文件 resources/base/animation: 动画 XML 定义 resources/rawfile: 任意格式原始文件，不参与编译。―> ―> ―> ―> ―> ――――――――――――――――――― —-

※ 痛点提醒改动 base 子目录内任何名称都会导致编译找不到资源，请保持标准命名。

`限定词目录命名规则示例：

• `zh_CN-car-ldpi`,`en_US-phone-xxhdpi` • 使用下划线 `_` 分隔语言/文字/国家；中划线 `-` 分隔其它限定词。• 匹配优先级：区域 ➡ 横竖屏 ➡ 设备类型 ➡ 屏幕密度。※ 若出现 `zh_CN_car`,则被视为无效命名，程序将忽略该方法。※ **常见错误**：把横竖屏写成 `_portrait_`,会导致资源全局不可用。 . . . . . . . . . . . . . . • • • • • • ★ ★ ★ ★ ★ ★ ​ . ---

config.json 详解 — 主要配置要点：

`config.json` 是 HarmonyOS 应用主要配置文件，由三个顶层对象组成：app、deviceConfig 和 module。这三个对象缺一不可，下面逐条说明并给出典型字段解释及常见误区。

app 对象关键字段举例及注意事项：

① bundleName ：应用包名。标识唯一性，由字母数字下划线和点号组成，必须以字母开头；长度限制通常为32字节以内。② vendor ：厂商名称，不超过128字节。③ version.code ：内部版本号，每次发布必须递增。其实，④ version.name ：面向使用者显示版本。如 “1.0.0”，⑤ minCompatibleVersionCode ：最低兼容版本码，用于判断升级兼容性。③： a) bundleName 重复 → 在华为应用环境中全局唯一，否则签名冲突。b) version.code 未自增 → 更新会被视为同一版本覆盖，热更新失效。c) vendor 长度超限 → 编译报错 “vendor name too long”。③： ① 用公司域名前缀，如 com.example.myapp。② 每次提交时检查 version.code 是否大于上一次提交。③ 保持 vendor 简短明了以便后续维护。⑥ deviceConfig 默认值： { "default":{ "network": { "cleartextTraffic": true // 开发环境允许明文流量。可生产禁用 } } } // 为了适配不同设备，可以再增加 phone/tablet/tv/car/wearable 等子键。其实，⑦module 对象关键字段： ① package ：对应 app.bundleName；按理说，② name ：模块名称。一般是 “entry” 或自定义 Feature 名； ③ deviceType ：支持设备列表，例如；④ mainAbility ：主入口类名，如 MainAbility；⑤ abilities ：包含所有 ability 的完整配置数组；⑥ reqPermissions ：权限声明数组。⑦： a) abilities 没有 mainAbility 标识 → 启动时报错 “main ability not found”。b) deviceType 写错 → 部署到非支持设备时报错 “device type mismatch”。⑧： ① 在 module 中明确 mainAbility 并保持一致；② 根据目标设备调整 deviceType 数组；③ 权限尽量最小化，只申明必要权限。⑤备注： json 文件中属性名称区分大小写，请严格遵守；任何拼写错误都会导致解析失败。--- '>''> ''> " ... --- --- --- --- pack.info — 应用打包信息说明与痛点： "delivery-with-install": 是否随应用一起安装，即是否自动拉取此 HAP。若 false，则需要手动下载后再安装；否则开启自动下载体验更好，但会占用存储空间。 ，* **痛点**：不少人忽略 `delivery-with-install=false` 的默认值。一旦忘记设置，就只能手工管理 Feature 包，这极大降低开发效率。--- --- 代码速查卡 🔍︎▶️◀️◀️▶️✎︎❕︎🕰︎🔑︎📌︎🛠︎🛠︎💬⚙️⚙️⚙️⛏️💎💫♾️🪞🤿🏳🏁🏢🍽🍱🍉🍊🍓🍍🥤☕☝☄🖱☕✨⟩⌛ↂ⟶↩🌱🌇🌑🌗𐂃 ⬝🔽❗?，?，!✨🚀💭💪💬👨‍🎤🔝🔣📈🙉❗😺😸😾 😼 ☘ ☓ ❲☰ ❶ \ " © ©........ ...?，------------------------------------- Scrolling beyond necessary parts would distract from main content – refore omitted. --- ---- ### ⚠️ 踩坑回忆录 • User Pain Point #1: 修改 resources 子目录名字会导致编译报错 “resource not found”。请务必使用官方限定词命名规则，否则程序将忽略该方法。• User Pain Point #2: bundleName 全局冲突造成签名失败。在发布前务必检查已有应用列表并预留独特前缀，如 com.companyname.appname。• User Pain Point #3: 忘记在 module.mainability 指定主入口类时启动异常，“main ability not found”。请确认 MainAbility 类已存在且正确声明。• User Pain Point #4: Permission 声明过多导致审核冗余。可通过 `` 策略精简权限请求，从而降低审核风险。• User Pain Point #5: 在打包过程中未设置 delivery-with-install 为 true。导致 Feature 必须手动下载，体验受影响。Summary:*先写完基础结构，再根据业务需求逐步 *. 必做实操任务 📋 ‼ ‼ ‑‑‑‑‑––––—––—‐‑‐───┐───────┬──────━━━━━━━━━━━━━━━━━━━━━━━╘═┴═╗ ╰═►〉?●，?，..…... ‒ ― ，…，…，…，… ███████ ... ... ... ▼─────────────- █ █ _+_ _x___ _k ___?，…，…} ����� ▲‐­….，... 学习检查清单 ✅ 能说出 HAP 包的组成结构。 \ 能说出 App Pack 和 HAP 的关系。 \ \t\t \ \t\t \ \t\t \ \t\t \ <\/ul> \ <\/div> \ <\/div> \ <\/div> \ <\/div> \ <\/div> \ <\/div> \ \ \ \ \ \ <\/body><\/html>"****?，?，按理说， This is only an illustrative snippet – please replace placeholders with proper Markdown or HTML in your final document.