简介

CHFramework 是一个专为 CocosCreator 引擎设计的轻量级 MVVM 框架。 引入数据绑定、命令模式、UI管理、网络服务、数据表服务以及编辑器扩展工具等一系列功能，可快速构建结构清晰、可维护性高、易于扩展的项目。

核心功能

• MVVM 架构: 将视图（View）、视图模型（ViewModel）和模型（Model）分离，降低代码耦合度。
• 数据绑定: 实现了视图与数据的自动同步，无需手动更新UI。
• 命令模式: 将请求封装成对象，解耦事件的发送者和接收者。
• UI 管理: 提供强大的 UI 视图管理服务，支持 UI 分层、加载、缓存、遮罩和生命周期管理。
• 数据表服务: 方便地读取和管理游戏配置数据。
• 编辑器扩展: 内置 Excel 工具面板，一键将 Excel 表格转换为 JSON 与 TypeScript 模型定义。

模块详解

1. 数据绑定 (Data Binding)

数据绑定是框架的核心功能之一，它允许视图自动响应数据的变化。

• Observable: 可观察属性类。使用它来包装你的数据，当数据改变时，它会自动通知所有订阅者。
• Binder: 绑定器。用于在视图和视图模型之间建立绑定关系（单向 / 双向）。
• UI Adapters: 框架内置了多种 UI 适配器：
  • LabelAdapter: 用于 Label（始终返回 string）
  • EditBoxAdapter: 用于 EditBox（双向输入）
  • SliderAdapter: 用于 Slider（数值绑定）
  • ……
• 示例：图中 “想要的新昵称”，会随着输入框的内容变化时自动更新，仅需下面一行绑定代码。

    Binder.bindTwoWay(this.vm.nextNickName, new EditBoxAdapter(this.nameEditBox));

2. 命令模式 (Command Pattern)

命令模式用于处理用户输入和系统事件，例如按钮点击。

• CommandBase: 所有命令的基类。
• SimpleCommand: 用于执行同步操作的简单命令。
• AsyncCommand: 用于执行异步操作（如网络请求、动画播放）的命令，支持 canExecute() 条件控制与 canExecuteChanged() 回调。

3. UI 管理 (UI Management)

ViewService 是一个强大的 UI 管理器，它简化了 UI 的创建和流程控制。

• ViewService: 负责 UI 视图的加载、显示、隐藏、销毁和链式操作（串行化打开）。
• ViewBase: 所有 UI 视图的基类，包含生命周期钩子（onCreate / onShown / onHide / onDismiss）。
• ViewModelBase: 视图模型的基类，负责处理视图的业务逻辑和状态。
• UILayers: 支持 UI 分层管理（ViewType.Normal / ViewType.Popup / ViewType.Toast），可轻松控制不同 UI 界面的显示层级与遮罩。
• 遮罩与 Loading:
  • ViewMask: 在打开弹窗时自动插入背景遮罩，支持点击关闭。
  • ViewLoadingUIBase: 自定义 Loading 界面基类，可在 openUI 时显示加载进度。

4. 数据表服务 (Table Service)

用于加载和查询游戏配置数据。

• TableReaderService: 数据表读取服务，支持通过键（通常是 id）快速查询。
• ITableModel: 数据表模型的接口，所有数据表结构都需要实现此接口。

工作流程:

1. 在 Excels 目录下编辑 Excel 表格（第1行注释、第2行类型、第3行字段名、第4行起为数据）。
2. 通过编辑器扩展工具一键转换为 JSON 与 TypeScript 模型定义。
3. 读取表格数据：

// Item 表格读取演示
const items = await Context.getService(TableReaderService).read<IItem>("Item");
items.forEach(item => {
    this.tableInfoLb.string += `${item.id} ${item.title} ${item.type} ${item.quality} ${item.desc}\n`;
});

5. 插件

框架提供了名为 Excel 工具 的插件，用于快速将 Excel 表格转换为项目可用的 JSON 数据与 TypeScript 模型定义。

功能:

• 一键执行转换（支持 .xlsx 格式）

生成内容:

• JSON 文件: 存放于指定的 JSON 输出目录，可被 TableReaderService 读取
• TableModel.ts: 存放于指定的 Model 输出目录，包含所有表格的接口定义（如 IHero / IItem），继承自 ITableModel

打开方式: CocosCreator 菜单栏中选择 CHFramework工具 > Excel 转换工具。

6. 拓展组件

1. CHButton：增加了音效播放模块
2. MultiStageProgressBar：支持将进度条分为多个阶段，每个阶段可以有不同的长度和进度值
3. CHWidget：安全区域适配组件，用于适配不同设备的安全区域，避免UI被刘海、胶囊遮挡
4. CHScrollview: 实现可复用的高性能ScrollView组件

项目展示

自定义扩展

CHFramework 支持多种自定义扩展方式，让开发者能够根据项目需求定制框架行为：

• UI 动画与过渡效果：框架支持自定义 UI 界面的打开/关闭动画。
• Loading 界面：可通过继承 ViewLoadingUIBase 实现自定义加载过渡界面。
• Toast 提示组件：可自定义 Toast 样式与动画效果，通过继承 ToastBase 实现。
• 自定义 UI 适配器：框架允许扩展更多 UI 适配器，满足特殊组件的绑定需求。
• 自定义数据表读取服务：支持 JsonReader 外的自定义格式读取器。

项目结构

CHFramework/
├─ Client/                           # CocosCreator 项目根目录
│  ├─ assets/                        # 资源目录
│  │  ├─ CHFramework/                # 框架源码
│  │  │  ├─ Runtime/                 # 框架核心模块
│  │  │  │  ├─ Framework.ts          # 框架主入口文件
│  │  │  │  └─ Framework/            
│  │  │  │     ├─ Binding/           # 数据绑定模块（Observable、Binder、UIAdapter）
│  │  │  │     ├─ Command/           # 命令模式模块（SimpleCommand、AsyncCommand）
│  │  │  │     ├─ Contexts/          # 上下文与依赖注入
│  │  │  │     ├─ Services/          # 核心服务
│  │  │  │     │  ├─ UI/             # UI 管理服务（ViewService、UILayers）
│  │  │  │     │  ├─ Table/          # 数据表服务（TableReaderService）
│  │  │  │     │  └─ Network/        # 网络服务（HttpService）
│  │  │  │     └─ Utils/             # 工具类
│  │  │  ├─ Plugins/                 # 插件与拓展组件
│  │  │  │  ├─ Components/           # 自定义组件（CHButton、CHWidget、CHScrollView等）
│  │  │  │  └─ NodeLibrary/          # 节点库
│  │  │  └─ Demo/                    # 示例工程
│  │  │     ├─ Launcher.ts           # 游戏启动入口
│  │  │     ├─ Constant/             # 常量定义（ViewKeys、GameEvent等）
│  │  │     ├─ Services/             # 业务服务（AudioService、PlayerPrefService等）
│  │  │     ├─ TableModel/           # 自动生成的数据表模型定义（TableModel.ts）
│  │  │     └─ UI/                   # UI 相关
│  │  │        ├─ View/              # 视图目录（MainView、RenameView等）
│  │  │        ├─ Toast/             # Toast 提示组件（可自定义）
│  │  │        └─ UILoading/         # 加载过渡界面（可自定义）
│  │  └─ resources/                  # 资源目录
│  │     └─ Demo_CHFramework/        
│  │        ├─ Audio/                # 音频资源
│  │        ├─ Prefab/               # UI 预制体
│  │        ├─ Table/                # 转换后的 JSON 配置数据
│  │        ├─ Texture/              # 纹理资源
│  │        └─ Animations/           # 动画资源
│  ├─ excels/                        # Excel 配置表源文件（*.xlsx）
│  └─ extensions/                    # 编辑器扩展
│     └─ chframework-tool/           # CHFramework 编辑器工具
└─ Docs/                             # 文档与图片资源
   └─ Images/                        # 演示图片

框架视频教学

CHFramework 框架教学视频：概览

CHFramework 框架教学视频：表格

CHFramework 框架教学视频：快捷创建MVVM

CHFramework 框架教学视频：组件绑定

CHFramework 框架教学视频：音频播放

CHFramework 框架教学视频：网络请求

CHFramework 框架教学视频：命令封装

CHFramework 框架教学视频：自定义扩展

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

如有问题或建议，请通过 GitHub Issues 或邮件联系。