HarmonyOS 小游戏《对战五子棋》开发第2篇-AppScope与entry模块

鸿蒙应用的两级结构

HarmonyOS应用采用应用级 + 模块级的两层结构：

应用 (App)
├── AppScope/           ← 应用级配置（全局唯一）
│   ├── app.json5       ← 应用清单
│   └── resources/      ← 应用级资源
└── entry/              ← 模块（可以有多个）
    ├── build-profile.json5
    ├── oh-package.json5
    └── src/main/
        ├── module.json5  ← 模块清单
        └── ets/          ← 源代码

AppScope：应用级配置

app.json5 --- 应用身份证

{
  "app": {
    "bundleName": "com.example.gomoku",  // 应用唯一标识
    "vendor": "example",                  // 开发者名称
    "versionCode": 1000000,               // 版本号（整数）
    "versionName": "1.0.0",               // 版本名（展示用）
    "icon": "$media:app_icon",            // 应用图标
    "label": "$string:app_name"           // 应用名称
  }
}

关键字段解读：

字段	说明	注意事项
bundleName	应用包名	全局唯一，上架后不可更改
versionCode	版本号	必须为正整数，每次更新必须递增
versionName	版本名	用户可见的版本字符串
icon/label	图标和名称	使用$资源类型:资源名引用资源

应用级资源

AppScope/resources/
├── base/element/string.json    # 默认字符串
└── dark/element/color.json     # 深色模式颜色

base目录存放默认资源，dark目录存放深色模式下的覆盖资源。这种资源限定机制让应用能自动适配不同模式。

entry模块：主功能模块

module.json5 --- 模块配置核心

{
  "module": {
    "name": "entry",                    // 模块名称
    "type": "entry",                    // 模块类型：entry(主模块)/feature(特性模块)
    "mainElement": "EntryAbility",      // 入口Ability
    "deviceTypes": ["phone", "tablet", "2in1"],  // 支持的设备类型
    "deliveryWithInstall": true,        // 是否随应用安装
    "installationFree": false,          // 是否支持免安装
    "pages": "$profile:main_pages",     // 页面路由配置
    "abilities": [...]                  // Ability列表
  }
}

Ability配置

"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"]
      }
    ]
  }
]

skills配置 是应用被系统识别的关键------entity.system.home + action.system.home表示这是一个可以通过桌面图标启动的入口Ability。

页面路由配置

// resources/base/profile/main_pages.json
{
  "src": [
    "pages/Index",
    "pages/TwoPlayerPage",
    "pages/AIBattlePage"
  ]
}

所有页面必须在main_pages.json中注册，否则router.pushUrl()会找不到目标页面。

资源引用机制

鸿蒙使用$资源类型:资源名的语法引用资源：

语法	示例	说明
$string:xxx	$string:app_name	引用字符串
$color:xxx	$color:start_window_background	引用颜色
$media:xxx	$media:app_icon	引用媒体资源
$profile:xxx	$profile:main_pages	引用profile配置

字符串资源示例

// AppScope/resources/base/element/string.json
{
  "string": [
    { "name": "app_name", "value": "五子棋" }
  ]
}

// entry/src/main/resources/base/element/string.json
{
  "string": [
    { "name": "module_desc", "value": "Gomoku module" },
    { "name": "EntryAbility_desc", "value": "Gomoku entry ability" },
    { "name": "EntryAbility_label", "value": "五子棋" }
  ]
}

颜色资源与深色模式

// entry/src/main/resources/base/element/color.json
{
  "color": [
    { "name": "start_window_background", "value": "#F5F5DC" },
    { "name": "board_color", "value": "#D4A868" },
    { "name": "line_color", "value": "#3B2F2F" }
  ]
}

// entry/src/main/resources/dark/element/color.json
{
  "color": [
    { "name": "start_window_background", "value": "#333333" }
  ]
}

深色模式下，start_window_background自动从#F5F5DC（米色）变为#333333（深灰），系统会自动选择对应目录的资源。

模块类型：entry vs feature

特性	entry模块	feature模块
数量	仅1个	可多个
作用	应用入口	动态特性（按需下载）
deliveryWithInstall	必须为true	可为false
mainElement	必须配置	不需要

本项目只使用了单个entry模块，对于小型应用这已经足够。大型应用可以拆分feature模块实现按需加载。

总结

理解鸿蒙应用的两级结构是开发的基础：

• AppScope管应用级别的配置和资源
• entry模块管具体功能和页面
• 资源限定机制让应用自动适配不同设备/模式
• module.json5是模块的核心配置文件

附：

截图图片