Laya导出的鸿蒙NEXT工程目录说明

结论

• AppScope：应用级配置
• entry：主应用模块，页面入口和资源都在这里
• libSysCapabilities：Laya导出的系统能力桥接层
• entry/src/main/cpp：native层入口，连接liblaya.so

顶层目录说明

• AppScope —— 应用级配置目录（整个App的身份信息

  • AppScope/app.json5：定义了包名、版本、厂商、图标、应用名等全局信息

• entry —— 主应用模块，大多数的接入工作都在这里

  • oh-package.json5：模块依赖
  • build-profile.json5：构建配置
  • src/main/ets：ArkTS页面与业务入口
  • src/main/resources：资源文件
  • src/main/cpp：native构建入口

• libSysCapabilities —— Laya导出的“系统能力适配层”（~ 一头连鸿蒙的ArkTS API - 一头连Laya/native引擎~

  • 接sdk时，通常会改这里或者参考这里的写法拓展（如果sdk需要处理一些比如如下的问题：
    • 调用系统能力
    • 弹原生UI
    • 调起浏览器/网页
    • 网络请求
    • 视频、输入框、设备信息

• oh_modules

  • 类似node_modules，通常不用改，由ohpm/工程构建自动维护

• .hvigor

  • 构建缓存和构建产物索引目录，通常不手改（因为是“构建过程的中间缓存”

• hvigor、hvigorfile.ts —— 鸿蒙工程的构建系统入口

  • 工程级构建任务声明 、 构建插件入口
  • 当前的hvigorfile.ts很简单，说明现在主要使用内置默认构建能力。

• build-profile.json5 —— 工程级构建配置

  • 本例工程包含两个模块：entry 和 libSysCapabilities
  • 还配置了签名信息，兼容SDK版本，目标SDK版本

• dependencies —— 通常是构建过程中用到的依赖辅助目录。一般不作为日常修改入口，优先看oh-package.json5和模块源码。

entry模块内部怎么理解

src/main/module.json5 —— 类似Manifest.xml

• 这是主模块声明文件，后续接SDK时非常重要。
• 当前它负责：
  • 声明模块类型是entry
  • 指定主入口EntryAbility
  • 指定页面路由配置pages：$profile:main_pages
  • 声明权限：requestPermissions ——【需要新增权限这里改
  • 配置一些metadata —— 【需要加metadata比如appId等自定义配置这里改

src/main/resources/base/profile/main_pages.json

• 这个是页面路由表，当前只有一个页面（pages/Index
• 这说明当前工程实际是单页承载Laya内容

src/main/ets/MainAbility/MainAbility.ets

• 应用主入口，鸿蒙Stage模型的UIAbility。它现在主要做了几件事：
  • 调用natievAppLifecycle.onCreate()通知 —— native层。
  • 缓存AbilityContext
  • 初始化WebView内核
  • 调用laya.ConchNAPI_init()，初始化Laya/native引擎
  • 通过onWindowStageCreate，加载pages/Index
  • 配置全屏、隐藏系统栏、常亮 —— 通过getMainWindow得到window对象进行设置
  • 在前后台切换时把生命周期同步给native（onForeground、onBackground

src/main/ets/pages/Index.ets

• 承载Laya画面的ArkUI页面，同时负责挂在原生辅助组件。

• 里面的关键点：

  • XComponent：承载native/Laya渲染内容
  • WorkerManager：启动worker线程
  • NapiHelper.registerUIFunctions()：注册UI线程可调用的桥接方法
  • ForEach()：按需挂载输入框、webView、VideoPlayer等原生组件

• 如果sdk需要以下内容，大概率都和这个页面有关：

  • 原生弹窗
  • 原生登录面板
  • 网页承载
  • 原生视频

src/main/ets/workers —— worker线程相关的代码

• 当前结构：
  • WorkerManager.ets：创建、管理worker
  • LayaWorker.ets： worker线程主逻辑
  • WorkerDataEntity.ets：消息实体
• 意义：
  • 部分逻辑不直接放在UI线程里做
  • 通过worker与UI页面通信
  • 再由桥阶层决定调用系统API还是回调native
• 注：不是所有SDK调用都能随便放线程里做。

src/main/resources —— 资源目录

• base/…：鸿蒙标准资源，如字符串、颜色、页面profile
• rawfile/…：Laya资源包
  • config.ini —— 配置包括watermark的
  • scripts —— js库
  • image —— logo
  • font —— empty.txt
  • ca ——cert…a…？
  • cache/dcc2.0 —— Content-Addressable Storage（SHA-1）

src/main/cpp —— native入口目录

• 关键文件：
  • CMakeLists.txt
  • napi_init.cpp —— 注册N-API模块
  • libentry/index.d.ts —— 声明native模块laya
  • libentry/oh-package.json5
  • 以上让ArkTS侧可以通过 import laya from ‘liblaya.so’ 调用native导出能力
  • 如果遇到“某个SDK只有C/C++so” 或者 “必须从native层封装能力”，这里就是入口。

libSysCapabilities模块内部怎么理解

这是干什么的

• 这个模块本质上是一个har库（类似jar），名字叫做libSysCapabilities。它把鸿蒙系统能力按Laya可调用的形式包装了一层。
• 当前已经封装好的能力包括：
  • DeviceUtils
  • ApplicationManager
  • NetworkUtils
  • LayaHttpClient
  • Dialog
  • WebView
  • VideoPlayer
  • EditBox
  • SoundUtils
  • JumpManager

核心文件（libSysCapabilities/src/

• main/ets/napi/NapiHelper.ets —— 最重要的桥接注册文件。

  • 这里通过laya.JSBind.bindFunction(…)把ArkTS方法名暴露给Laya/native调用。
  • 新增SDK能力怎么做：
    • 在某个XxxManager.ets写好方法
    • 在这里注册
    • 让Laya侧按约定的方法名来调

• main/ets/event/HandleMessageUtils.ets —— 预留的消息处理入口

  • 给异步/同步消息扩展留了位置
  • 如果SDK需要一个统一的事件分发层，这里是很适合扩展的点

• main/ets/utils/WorkerMsgUtils.ets —— worker线程不能直接碰某些UI能力

  • 负责处理worker发到主线程的消息，并按模块分发到（之所以分发是因为需要通过消息回到主线程处理）：
    • Dialog
    • WebView
    • JumpManager

• main/ets/common/GlobalContext.ets —— 一个全局对象缓存器

  • 当前用来保存（后续SDK接入时，经常需要上下文、页面实例、全局单例经常会用到这）：
    • AbilityContext
    • worker实例
    • WebView/VideoPlayer/EditBox的实例表
    • dialog控制器等。

当前工程的启用和调用链

• 整体图景：

• MainAbility启动应用 -> 加载Index页面 -> Index挂载XComponent和原生组件

• 启动Worker -> libSysCapabillities负责桥接鸿蒙API -> liblaya.so/native引擎执行底层逻辑。

• 更细一点：

  • MainAbility.ets —— 初始化应用与native引擎
  • Index.ets —— 承载画面和UI组件
  • LayaWorker.ets —— 负责worker线程逻辑
  • WorkerMsgUtils.ets / HandleMessageUtils.ets —— 负责消息分发
  • NapiHelper.ets —— 负责把ArkTS方法暴露给Laya/native
  • entry/src/main/cpp —— 负责native 模块注册

哪些目录可以改，哪些尽量别动

日常可改

• AppScope
• entry/src/main/ —— ets/resources/cpp/module.json5
• entry/oh-package.json5
• entry/build-profile.json5
• libsysCapabilities/src/main —— ets/modules.json5

一般不要手改 ——（构建产物，依赖缓存，IDE生成内容

• .hvigor
• oh_modules
• entry/build
• libSysCapabilities/build
• .idea

修改定位

• AppScope/app.json5：改包名、版本、应用名
• entry/src/main/module.json5（Manifest.xml）：加权限、metadata、入口能力
• entry/src/main/ets/MainAbility/MainAbility.ets：生命周期函数（改页面启动，前后台生命周期
• entry/src/main/ets/pages/Index.ets：改Laya承载页面
• entry/src/main/ets/workers：改线程通信
• libSysCapabilities/src/main/ets：改系统桥接能力
• entry/src/main/cpp：接native so / N-API
• entry/src/main/resources/rawfile：放游戏资源或静态配置

工程概括

• Laya导出的鸿蒙壳工程，接入sdk基本就是在这个壳和桥之间继续加能力
  • entry：应用壳【*
  • libSysCapabilities：平台能力桥【*
  • liblaya.so：native引擎接口
  • rawfile：游戏资源包