第4章_图解HarmonyOS 的结构

第4章图解HarmonyOS 的结构

HarmonyOS 学习系统 | 阶段一：入门筑基期建议学习时长：1-2 周

学习目标

序号	能力
1	理解 App Pack、HAP、entry 与 Feature 模块的关系
2	掌握 Ability 与 AbilitySlice 的概念和区别
3	熟悉资源文件目录结构（resources）
4	能独立解读和修改 config.json 核心配置

核心图解

内容讲解

4.1 App 与 HAP 包

想象你要寄一个"智能音箱"给朋友：

App Pack（应用包）= 整个大快递箱

entry HAP（主模块）= 快递箱里的"音箱主体"------必需品，每个快递箱有且只有一个

Feature HAP（特性模块）= 快递箱里的"额外配件"------可以放蓝牙模块、语音模块等，也可以不放

pack.info = 快递单------记录箱子里每个包裹的信息

config.json = 产品说明书------详细描述每个部件的参数

libs/ = 工具箱------你需要借用别人的工具（第三方库）

resources/ = 装饰贴纸------不同地区用不同的贴纸（多语言资源）

HarmonyOS 的应用软件包以 App Pack 形式发布，它是由一个或多个 HAP（HarmonyOS Ability Package）以及描述每个 HAP 属性的 pack.info 组成的。

entry 与 Feature 模块

模块类型	数量要求	说明	类比
entry HAP	有且只有一个	应用主模块，可独立安装运行	快递箱里的"主体商品"
Feature HAP	零个或多个	动态特性模块，支持按需安装	快递箱里的"可选配件"

在 build 目录下可以找到名为 entry-debug-rich-unsigned.hap 或 entry-debug-rich-signed.hap 的文件，这些 .hap 文件就是 HarmonyOS 的应用安装包。

HAP 内部结构

一个 HAP 由以下部分组成：

src/main/java/：Java 源代码，包含 MainAbility、MainAbilitySlice 等类
src/main/resources/：资源文件（布局、图片、字符串、样式等）
config.json：应用配置文件（核心）
libs/：第三方依赖库（.jar、.har、.so）
build.gradle：模块构建配置

4.2 Ability 与 AbilitySlice

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

类型	全称	说明	类比
FA	Feature Ability	有 UI 界面，用于与用户交互	公司的前台接待
PA	Particle Ability	无 UI 界面，在后台运行或提供数据	公司的后台仓库

FA 目前支持 Page Ability 模板。一个 Page 可以包含一个或多个 AbilitySlice，AbilitySlice 是应用的单个页面及其控制逻辑的总和。

scss 复制代码

MyApplication (AbilityPackage)
  └── MainAbility (Page Ability / FA)
        ├── MainAbilitySlice (默认页面，通过 setMainRoute 指定)
        └── PayAbilitySlice (附加页面，通过 addActionRoute 配置)

从三层架构的角度来看：

Page Ability = 表示层（与用户交互）
Service Ability = 业务层（后台处理业务逻辑）
Data Ability = 数据访问层（对外提供数据访问）

4.3 资源文件

HarmonyOS 应用的资源文件存放在 resources 目录下，包括两大类目录：

目录	用途	文件类型
resources/base/element/	元素资源	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/	原始文件	任意格式文件，不参与编译

限定词目录命名规则

限定词目录可以由一个或多个表征设备特征的限定词组合而成，包括语言、文字、国家或地区、横竖屏、设备类型和屏幕密度 6 个维度。

命名格式 ：语言_文字_国家或地区-横竖屏-设备类型-屏幕密度

语言/文字/国家或地区之间用下划线 _ 连接
其他限定词之间用中划线 - 连接
示例：zh_CN-car-ldpi、en_US-phone-xxhdpi

匹配优先级：区域 > 横竖屏 > 设备类型 > 屏幕密度

4.4 config.json 详解

config.json 是 HarmonyOS 应用的核心配置文件，由三个顶层对象组成，缺一不可：

json 复制代码

{
  "app": {
    "bundleName": "com.example.myapp",
    "vendor": "example",
    "version": { "code": 1, "name": "1.0.0" },
    "minCompatibleVersionCode": 1
  },
  "deviceConfig": {
    "default": {
      "network": { "cleartextTraffic": true }
    }
  },
  "module": {
    "package": "com.example.myapp",
    "name": "entry",
    "deviceType": ["phone"],
    "mainAbility": "MainAbility",
    "abilities": [{
      "name": "MainAbility",
      "type": "page",
      "label": "My App",
      "icon": "$media:icon",
      "launchType": "standard",
      "visible": true
    }],
    "reqPermissions": []
  }
}

三个顶层对象说明

对象	作用	关键字段
app	应用全局配置	bundleName（包名）、vendor（厂商）、version（版本）
deviceConfig	设备配置	default/phone/tablet/tv/car/wearable 各设备特殊配置
module	HAP 模块配置	package、name、deviceType、abilities\[\]、reqPermissions\[\]

app 对象关键字段

bundleName：应用包名，标识应用唯一性，由字母、数字、下划线和点号组成，必须以字母开头，长度 7-127 字节
vendor：应用开发厂商描述，不超过 255 字节
version.code：应用版本号（内部管理用），每次更新必须递增
version.name：面向用户展示的版本号，如 "1.0.0"

module 对象关键字段

name：模块名称，通常为 "entry" 或自定义 Feature 名
deviceType：支持的设备类型数组，如 ["phone", "tablet"]
abilities[]：Ability 配置数组，每个 Ability 包含 name、type、label、icon 等
reqPermissions[]：权限声明数组

4.5 pack.info

pack.info 文件由 IDE 编译生成，用于描述应用软件包中每个 HAP 的属性，应用市场根据该文件进行拆包和分类存储：

delivery-with-install：该 HAP 是否支持随应用安装
name：HAP 文件名
module-type：模块类型，为 entry 或 feature
device-type：支持该 HAP 运行的设备类型

代码速查卡

API/语法	功能	示例
`ResourceTable.Layout_xxx`	引用布局资源	`ResourceTable.Layout_ability_main`
`ResourceTable.Id_xxx`	引用组件 ID	`ResourceTable.Id_text_helloworld`
`ResourceTable.String_xxx`	引用字符串资源	`ResourceTable.String_app_name`
`$media:icon`	引用媒体资源	config.json 中的图标引用
`$string:app_name`	引用字符串	config.json 中的标签引用
`$graphic:btn_bg`	引用可绘制资源	XML 中的背景引用

与 Android/iOS 对比

功能	HarmonyOS (config.json)	Android (AndroidManifest.xml)	iOS (Info.plist)
包名声明	app.bundleName	manifest@package	CFBundleIdentifier
组件注册	module.abilities\[\]	`<activity>`/`<service>`	无需显式注册
权限声明	module.reqPermissions\[\]	`<uses-permission>`	Info.plist 权限描述
设备类型	module.deviceType\[\]	build.gradle productFlavors	TARGETED_DEVICE_FAMILY
配置格式	JSON	XML	XML/PLIST
应用包格式	HAP (.hap)	APK (.apk)	IPA (.ipa)

⚠️ 踩坑回忆录

刚开始学的时候，我在 resources 目录下随意改了一个文件夹的名字，结果编译直接报错找不到资源。后来才知道 resources 目录下的目录名（base、en_US 等）是系统约定的 ，不能随意修改。限定词目录的命名规则也很严格，zh_CN-car 和 zh_CN_car 是不同的------语言/文字/国家用下划线，其他用中划线，搞混了就不会被识别。

另外，bundleName 在整个华为应用生态中必须全局唯一。我第一次起名叫 com.test.myapp，结果签名时提示与其他应用冲突，改了个独特的名字才解决。

必做实操任务

序号	任务	难度
1	逐层分析 Hello World 工程的目录结构，写出每个目录的作用	★★☆
2	打开 config.json，解读 app、deviceConfig、module 三个对象的含义	★★☆
3	修改应用图标（替换 media 目录下的 icon.png）和应用名称（修改 string.json）	★★☆
4	在 resources/base/element/string.json 中添加新的字符串资源并在布局中引用	★★☆
5	创建一个限定词目录 `en_US`，放入英文版本的字符串资源	★★★

学习检查清单

能说出 HAP 包的组成结构（entry vs Feature）
能说出 App Pack 和 HAP 的关系
能区分 Ability 和 AbilitySlice
能说出 resources 目录下各子目录的用途
能修改 config.json 中的基本配置
理解限定词目录的命名规则和匹配优先级
能解释 pack.info 文件的作用

阶段一学习路径

进阶方向

尝试创建一个 Feature 模块，理解多模块开发
了解 HAR（HarmonyOS Archive）共享库的打包和使用
深入学习 config.json 中 abilities 的所有配置项

第4章_图解HarmonyOS 的结构