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 --- 应用身份证

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 --- 模块配置核心

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配置

json5 复制代码
"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。

页面路由配置

json5 复制代码
// 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配置

字符串资源示例

json 复制代码
// 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": "五子棋" }
  ]
}

颜色资源与深色模式

json 复制代码
// 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是模块的核心配置文件

附:

截图图片

相关推荐
爱写Bug的浮游14 小时前
初识仓颉:5 分钟看懂核心语法
harmonyos·编程语言
羽落•无痕(苏晗默)16 小时前
华为数通IA——14、网络服务与应用:TCP/UDP 传输层协议与 FTP、Telnet、SSH 实践
网络·网络协议·tcp/ip·网络安全·华为·udp·信息与通信
程序猿追1 天前
鸿蒙 PC 的 Ionic 工单有两个错误,按下生成后光标该去哪儿
华为·harmonyos
KevinChaos1 天前
随手备忘录手记 04|HarmonyOS 7.0新特性实验:物品图鉴的加载逻辑
华为·harmonyos
Sirius_Ji2 天前
从硬解基座到字幕与滤镜链:ffmpeg-for-HarmonyOS v0.3.2
harmonyos
用户86194177207412 天前
uni-app 鸿蒙端提现点不动?我用 UTS 插件补上了微信"确认收款"
微信·harmonyos
码间留白2 天前
uni-app 鸿蒙端提现点不动?我用 UTS 插件补上了微信"确认收款"
uni-app·harmonyos·鸿蒙·uts插件·微信商家转账
GitCode官方2 天前
开源鸿蒙跨平台直播|AI 时代,用 cj-tauri 开发鸿蒙 PC 应用
人工智能·华为·harmonyos·atomgit
程序猿追2 天前
鸿蒙 PC 用 Tauri 做本地查找,怎样让慢请求给新请求让路
华为·状态模式·harmonyos
程序猿追2 天前
鸿蒙 PC 用 Ionic 做巡检目录,缩窄窗口后草稿还在吗
华为·harmonyos