9.3 KiB
MVVM框架
**本文档引用的文件** - [MvvmInfo.md](file://doc/mvvm/MvvmInfo.md) - [VMBase.md](file://doc/mvvm/VMBase.md) - [VMCustom.md](file://doc/mvvm/VMCustom.md) - [VMLabel.md](file://doc/mvvm/VMLabel.md) - [VMState.md](file://doc/mvvm/VMState.md) - [VMProgress.md](file://doc/mvvm/VMProgress.md) - [VMEvent.md](file://doc/mvvm/VMEvent.md) - [VMParent.md](file://doc/mvvm/VMParent.md) - [ViewModelScript.md](file://doc/mvvm/ViewModelScript.md) - [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts) - [HInfoComp.ts](file://assets/script/game/map/HInfoComp.ts) - [SIconComp.ts](file://assets/script/game/map/SIconComp.ts)目录
简介
Oops Plugin Framework的MVVM实现机制旨在通过数据驱动的方式简化UI逻辑开发，实现无代码或低代码的UI开发模式。该框架借鉴了Vue的设计理念，通过观察者模式和事件系统，实现了数据与UI的双向绑定。开发者无需频繁使用cc.find、getChildByName、getComponent等繁琐的DOM操作，而是通过简单的配置即可实现复杂的UI逻辑。
该框架的核心优势在于其组件化的实现方式，提供了多个低耦合的VM组件，如VMLabel、VMState、VMProgress等，这些组件可以直接在Cocos Creator编辑器中挂载和配置，极大地提高了开发效率和可维护性。
Section sources
核心组件
ViewModel
ViewModel是MVVM框架的核心模块，负责动态管理数据模型，并通过cc.director.emit通知游戏内的节点组件状态变化。它是数据模型的包装器，提供了数据绑定、监听和通知的功能。
VMBase
VMBase是所有VM组件的基类，实现了基础的数据绑定功能。其他VM组件如VMLabel、VMState等都继承自VMBase。它提供了路径监听、值变化回调等核心功能。
VM组件类型
- VMCustom：通用组件，可自定义绑定任意组件的属性
- VMLabel：专门用于文本显示，支持模板语法和格式化
- VMState：根据数据值控制节点状态（激活、显示、颜色等）
- VMProgress：用于进度条显示，支持双向绑定
- VMEvent：在值变化时触发事件，调用其他组件的方法
- VMParent：用于定义局部范围的ViewModel数据
Section sources
数据模型注册与管理
数据模型注册
通过VM.add(data, 'tag')方法注册数据模型，其中data是要绑定的数据对象，tag是该数据模型的唯一标识标签。注册后，该数据模型将被VMManager管理，可以通过标签进行访问和操作。
// 构建数据对象
let data = {
name: 'user',
gold: 12200,
info: {
id: 0
}
}
// 创建VM对象并添加到VMManager进行管理，标记为'user'标签
VM.add(data, 'user');
数据模型管理API
add(data, tag)：创建并添加ViewModel对象get(tag)：获取指定标签的ViewModel实例remove(tag)：移除指定标签的ViewModel对象setValue(path, value)：设置值（支持全局路径）addValue(path, value)：累加值getValue(path, defaultValue)：获取值（支持默认值）
Section sources
UI组件与数据绑定机制
VMCustom组件
VMCustom是通用的绑定组件，可以绑定任意组件的任意属性。在编辑器中挂载VMCustom组件后，需要设置以下属性：
- Controller：启用后支持双向绑定
- Watch Path：要监听的数据路径
- Component Name：要绑定的组件名称
- Component Property：要绑定的组件属性
- refreshRate：刷新频率（仅在Controller启用时生效）
VMLabel组件
VMLabel专门用于文本显示，支持模板语法和多种格式化方式。其主要特性包括：
- 支持单路径和多路径监听
- 使用
{{0}}、{{1}}等模板语法 - 支持多种格式化：
int（整数）、fix(n)（小数位数）、kmbt（千位分隔）、per（百分比）等
VMState组件
VMState根据数据值控制节点状态，可以实现条件显示、颜色变化等功能。主要配置包括：
- Watch Path：监听的数据路径
- Condition：判断条件（如等于、大于等）
- Value Action：满足条件时执行的操作（如节点激活、可见性、不透明度、颜色等）
VMProgress组件
VMProgress用于进度条显示，需要设置两个监听路径（最小值和最大值）。其配置与VMCustom类似，但专门针对进度条组件。
Section sources
UI自动更新机制
事件驱动更新
当数据模型的值发生变化时，ViewModel会通过cc.director.emit触发事件，通知所有监听该路径的组件进行更新。这种事件驱动的机制确保了数据变化能够实时反映到UI上。
flowchart TD
A[修改数据模型] --> B{数据变化}
B --> C[ViewModel检测到变化]
C --> D[cc.director.emit触发事件]
D --> E[VM组件接收到通知]
E --> F[更新UI显示]
Diagram sources
双向绑定
通过启用VMCustom组件的Controller功能，可以实现UI到数据的反向绑定。例如，当用户拖动进度条时，不仅可以更新UI显示，还可以自动更新对应的数据模型值。
局部数据管理
对于局部组件，可以继承VMParent组件来管理局部数据。这种方式适用于弹窗等需要独立数据管理的场景。VMParent会在onLoad时自动将*.name形式的路径中的*替换为实际的ViewModel标签。
Section sources
编辑器配置与使用示例
HInfoComp组件分析
HInfoComp是英雄信息显示组件，展示了如何通过VM组件实现数据绑定：
classDiagram
class HInfoComp {
+h_uuid : number
+heroNodes : Node[]
+update_data(uuid : number)
+load_all_hero(uuid : number)
+next_hero()
+prev_hero()
}
HInfoComp --> VMLabel : "使用"
HInfoComp --> VMProgress : "使用"
HInfoComp --> VMState : "使用"
Diagram sources
SIconComp组件分析
SIconComp是技能图标组件，展示了简单的数据绑定：
classDiagram
class SIconCompComp {
+update_data(s_uuid : number)
}
SIconCompComp --> VMCustom : "使用"
Diagram sources
编辑器配置步骤
- 在节点上添加VM组件（如VMLabel、VMState等）
- 设置Watch Path为对应的数据路径（如
user.gold） - 配置组件特定属性（如VMLabel的模板格式）
- 运行游戏，数据变化将自动反映到UI上
数值格式化示例
// 在VMLabel中使用模板语法
// {{0:int}} 显示整数
// {{0:fix(2)}} 显示两位小数
// {{0:kmbt}} 使用K/M/B/T单位缩写
// {{0:per}} 显示百分比
// {{0:sep}} 使用千位分隔符
节点状态切换示例
// 使用VMState控制节点状态
// Condition: value >= 30
// Value Action: NODE_VISIBLE
// Watch Nodes: 指定要控制的节点
进度条更新示例
// 使用VMProgress更新进度条
// Watch Path Arr: [currentValue, maxValue]
// Component Name: ProgressBar
// Component Property: progress
Section sources
高级功能与最佳实践
VMEvent组件
VMEvent组件可以在值变化时触发事件，调用其他组件的方法。适用于需要自定义处理逻辑的场景，如数值变化时播放动画、播放音效等。
VMModify组件
VMModify组件提供了便捷的数据修改方法，可以通过事件调用实现数据的增减操作：
vAddInt：增加整数vSubInt：减少整数vMulInt：乘以整数vDivInt：除以整数vString：设置字符串vNumber：设置数值
性能优化建议
- 合理使用局部数据管理（VMParent），避免全局数据的过度监听
- 控制刷新频率（refreshRate），避免不必要的频繁更新
- 及时移除不再使用的ViewModel，防止内存泄漏
- 避免过度嵌套使用VMParent，以免影响性能
调试技巧
- 使用
VM.get(tag)获取ViewModel实例进行调试 - 通过
vm.active = false临时关闭通知功能进行问题排查 - 利用编辑器的组件配置界面直观地查看和修改绑定关系
Section sources