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