diff --git a/doc/imgs/module.png b/doc/imgs/module.png deleted file mode 100644 index 1153c43..0000000 Binary files a/doc/imgs/module.png and /dev/null differ diff --git a/doc/imgs/qq.png b/doc/imgs/qq.png deleted file mode 100644 index a537b6a..0000000 Binary files a/doc/imgs/qq.png and /dev/null differ diff --git a/doc/mvvm/MvvmInfo.md b/doc/mvvm/MvvmInfo.md new file mode 100644 index 0000000..1cce473 --- /dev/null +++ b/doc/mvvm/MvvmInfo.md @@ -0,0 +1,53 @@ +### 框架原作者文档链接 +使用文档: https://github.com/wsssheep/cocos_creator_mvvm_tools/tree/master/docs +Github 地址: https://github.com/wsssheep/cocos_creator_mvvm_tools + +### 项目结构 + +核心脚本文件存放在 assets\Script\modelView 路径,要使用必须全部引入 + +- **JsonOb.ts** - 实现基础的 观察者模式, 改变绑定的数据会自动调用回调函数。你可以随时替换成自己写的观察者。 +- **ViewModel.ts** - VM的核心模块,动态管理ViewModel,使用 cc.director.emit 通知 游戏内的节点组件改变状态。 +- **VMBase.ts** - VM监听核心组件,用于接收ViewModel 的数值变动消息。VMCustom /VMEvent 之类的衍生组件都是继承自VMBase +- **VMParent.ts** - VM父组件,适合 多实例的 prefab 弹窗使用, 它将数据绑定在继承 VMparent 的组件上,只属于此次创建的实例。 需要以特殊方式继承使用。 + +**** + +### 组件简介 + + +- `VMCustom` — 挂载VMCustom,然后会自动识别当前节点的组件(也可以自行设置)。填上你的数值路径,大功告成。 +- `VMLabel` — 挂在VMLabel ,不用担心你的数值是整是零,使用模板语法 {{0:int}}自动格式化,解决文本数据显示的问题 +- `VMState` — 解决节点状态的切换问题 +- `VMProgress` — 解决进度条显示问题 +- `VMEvent `—挂载VMEventCall, 触发事件。在值变化时调用其他组件方法(结合其他组件使用事半功倍) +- `VMParent` — 定义局部范围使用 的 ViewModel数据 + +定义数据模型: `VM.add(data,"tag")` + +一直被 cc.find、getChildByName,getComponent, 所以一直想要整理个好的方案。部分参考了Vue(OS:假装参考了), 以适合 Creator 组件化的方式引入 MVVM。你甚至可以不写一行代码就完成大部分的复杂的UI逻辑,非常适合高强度的细节修改 (os:让策划自己改去)。 +这套工具核心在于提供的组件集合,而不是Mvvm本身。使用的是低耦合度的组件脚本来控制数值监听的绑定,侵入性较低。 + +**** + +### 用法说明 + +- **导入框架** - 导入 assets\Script\modelView 中的所有脚本 + +- **建立数据模型** - 任意位置新建一个数据脚本,定义自己的数据模型,使用`VM.add(data,'tag')` 添加viewModel。 可以通过VM直接管理该数据,或者自己全局管理 data 数据模型。 + +- **挂脚本** - 编辑器中直接添加组件 VMCustom ,它会自动识别绑定到需要设置值的组件和组件的属性,比如cc.Label、cc.Progress等。 你只要填写对应的watchPath, 就会自动赋值到组件的属性上。比如填写 global.play.hp ,就会在游戏运行时赋值给绑定的组件属性。 + +- **改数据** - 在游戏中任意改变 global.play.hp的值,对应的label 就会自动改变数值。 + +- **全局注册VM**: (全局自由使用路径) VM.add(data,'tag'); // + +- **局部组件使用VM**: (只在组件内使用的相对路径) + + 1.继承VMParent 组件 + + 2.在组件内设置 data 数据(data属性) + + 3.相对路径 使用 *.name 的方式设置 watchPath,VMParent 会在 onLoad 的时候自动将 * 替换成 实际的 ViewModel 标签,以便监听数据变化。 + +**** diff --git a/doc/mvvm/VMBase.md b/doc/mvvm/VMBase.md new file mode 100644 index 0000000..83fa210 --- /dev/null +++ b/doc/mvvm/VMBase.md @@ -0,0 +1,39 @@ +## VM Base + +### 介绍 + +VM基础组件,只实现了数据绑定, 需要被继承使用。你可以通过继承VM Base来实现自己的VM组件。当然一般情况下使用这个工具所提供的其他组件脚本就够用了。 + +### 脚本属性 + +- `watchPath` - 需要监听的路径,,你在VM怎么定义的结构,就在这里写上取值的路径。 + + 比如global 标签的 viewModel 要取值player.atk, 就是gloabl.player.atk。 + +- `watchPathArr` - 需要监听的多路径 数组, 和上面一样,不过需要监听的是一个路径的数组。 + +- `templateMode` - 模板模式(多路径模式),启用后才能监听 watchPathArr 数组中的所有路径 + +- `templateValueArr` - 缓存监听路径的值,当监听某个路径的值发生变动时,会自动更新该数组中缓存的值。一般不需要考虑使用。 + +- `VM` - VMManager 对象的引用,参考ViewModel 的说明 + +- `onLoad()` - 提前拆分、并且解析 监听的路径,可以捕获一些错误 + + **如果需要重写onLoad 方法**,请根据顺序调用 **super.onLoad()**,执行默认方法。直接覆盖将会导致函数的功能丢失。 + +- `onEnable()` - 激活节点时,更新对象初始值,同时开启对 watchPath 的监听。 + + **可重写**,重写时需要调用 super.onEnable() 处理父方法 + +- `onDisable()`- 关闭节点时,关闭对 watchPath 的监听。 + + **可重写**,重写时需要调用 super.onDisable() 处理父方法 + +- `onValueInit()`- 初始化值时调用函数 + + 虚方法,可以直接被重写。 + +- `onValueChanged(newValue,oldValue,pathArray)` - 当值改变时调用函数 + + 虚方法,可以直接被重写。 \ No newline at end of file diff --git a/doc/mvvm/VMCompsEdit.md b/doc/mvvm/VMCompsEdit.md new file mode 100644 index 0000000..5b48f54 --- /dev/null +++ b/doc/mvvm/VMCompsEdit.md @@ -0,0 +1,31 @@ +## VM Component Edit + +### 介绍 + +VM组件编辑,提供一些基础的功能。可以搜索当前节点下的 组件内容,便于查询出被绑定的节点,方便调试信息。 + +### 编辑器属性 + +- `Find List` - 需要查询的组件名称 + +- `Action Type` - 操作行为 + + `SEARCH_COMPONENT` - 查询组件 + + `ENABLE_COMPONENT` - 激活关闭组件 + + `REPLACE_WATCH_PATH` - 替换组件路径 + + `DELETE_COMPONENT` - 删除所有匹配组件 + +- `Trigger` - 勾选框就会立刻执行对应的命令, 不同模式下Trigger名称不同 + +- `Can Collect Nodes` - 将节点收集起来 放在 Collect Nodes 中,Action Type 为 SEARCH_COMPONENT 类型时 才能使用 + +- `Target Path` - 准备搜索的目标路径,Action Type 为 REPLACE_WATCH_PATH 时可用 + +- `Replace Path` - 准备替换的路径值,Action Type 为 REPLACE_WATCH_PATH 时可用 + +### 手动编辑器 + +在层级管理器中 搜索 t:VMBase, 也可以查询到所有VM组件的节点,然后你可以进行手动的管理操作 \ No newline at end of file diff --git a/doc/mvvm/VMCustom.md b/doc/mvvm/VMCustom.md new file mode 100644 index 0000000..442335a --- /dev/null +++ b/doc/mvvm/VMCustom.md @@ -0,0 +1,17 @@ +## VM Custom + +### 介绍 + +VM组件自定义, 可以设置需要监听的 组件名称和组件属性,并且挂载时还能自动识别组件名。比较泛用。适合任意的自制组件。(如果想自动识别自己写的组件名,可以修改脚本配置内容)。 + +### 编辑器属性 + +- `Controller` - 激活controller,以开启双向绑定,否则只能接收消息 +- `Watch Path` - 绑定数值监听路径 + +- `Component Name` - 绑定组件的名字 (会根据脚本配置自动识别) + +- `Component Property` - 绑定组件上需要监听的属性 (会根据脚本配置自动识别) + +- `refreshRate` - 刷新间隔频率 (只影响脏检查的频率) ,controller开启后生效 + diff --git a/doc/mvvm/VMEvent.md b/doc/mvvm/VMEvent.md new file mode 100644 index 0000000..7f726b2 --- /dev/null +++ b/doc/mvvm/VMEvent.md @@ -0,0 +1,22 @@ +## VM Event + +### 介绍 + +VM组件事件,监听watchPath 路径 数值的变动情况,调用回调函数。可以同时监听复数路径的值。适合需要自己处理数值变化行为的场合。比如获得1金币,想让数字闪烁一下,有了VMEvent ,你就不用手动去让数字闪烁了。可以在编辑器中直接设置回调,来触发别的组件的函数。 + +### 编辑器属性 + +- `Template Mode` - 多路径模板模式,开启后可以监听多路径 +- `Watch Path ` - 绑定数值监听路径 + +- `Watch PathArr` - 绑定数值监听的路径数组 (多路径模板模式开启后出现) + +- `Component Name` - 绑定组件的名字 (会根据脚本配置自动识别) + +- `Component Property` - 绑定组件上需要监听的属性 (会根据脚本配置自动识别) + +- `Trigger Once` - 事件通知只传递一次,然后自动 disabled 该组件 + +- `Filter Mode` - 根据条件过滤通知事件,比如 当值>=30 才会通知事件去调用 Change Events + +- `Change Events` - 值路径改变事件,和按钮回调事件类似 在编辑器里绑定对应要执行的节点函数 \ No newline at end of file diff --git a/doc/mvvm/VMLabel.md b/doc/mvvm/VMLabel.md new file mode 100644 index 0000000..aa0486a --- /dev/null +++ b/doc/mvvm/VMLabel.md @@ -0,0 +1,34 @@ + +## VM Label + +### 介绍 + +VM组件文本监听,用于处理 Label 的监听问题。监听watchPath 路径 数值的变动情况,变动Label文本内容。使用模板模式,还可以将输入的字符串格式化。可以监听多路径,来同时在一个label上显示多个数据源的信息。 + +### 编辑器属性 + +- `Template Mode` - 多路径模板模式,开启后可以监听多路径,并且可以设置文本模板 +- `Watch Path ` - 绑定数值监听路径 + +- `Watch PathArr` - 绑定数值监听的路径数组 (多路径模板模式开启后出现) + +- `Label Type` - 只读属性,自动绑定cc.Label 或者 cc.RichText,你可以在脚本修改自己定义的Label + + + +### 关于模板解析 + +使用 {{0}} {{1}} {{2}} 方式设置模板内容(设置label 的 String 默认值)。在运行时,会动态的获取多路径监听的值,按数组内index 顺序替换掉 {{index}}。你可以额外添加修饰符号来格式化信息源,比如 {{0:int}} 会将数字内容以整数显示,{{0:time}} 以时间格式显示时间戳 等。 + +以下是目前支持的格式化内容: + +- `int` - 只显示整数部分 +- `fix(n)` -显示小数位数 +- `kmbt` - 以 K M B T 单位 缩短数字长度 +- `per ` - 显示百分比 +- `sep` - 以千位分号分割数字 +- `limit(n)` - 限制文本字符长度 + +### 自定义模板格式 + +所有 文本格式处理 都放在 StringFormat 类中,你可以根据自定义需要修改其中的函数。 \ No newline at end of file diff --git a/doc/mvvm/VMModify.md b/doc/mvvm/VMModify.md new file mode 100644 index 0000000..96d6399 --- /dev/null +++ b/doc/mvvm/VMModify.md @@ -0,0 +1,29 @@ +## VM Modify + +### 介绍 + +VM组件 修改数据,修改指定 路径 watchPath 的 数据。一般配合 cc.Button 组件使用,可以点击按钮后直接修改指定路径的值。 + +### 编辑器属性 + +- `Watch Path ` - 绑定数值监听路径 +- `Value Clamp` - 是否限制数字的修改范围 +- `Value Min` - 限制最小值不低于 +- `Value Min` - 限制最大值不高于 + +### 使用方式 + +类似 Click Events 的设置调用节点上组件的方法, 去调用VMModify 组件上的对应函数,就可以修改 watch Path 监听的 路径的值。 + +- `vAddInt` - 增加整数 +- `vSubInt` - 减少整数 +- `vMulInt` - 乘以整数 +- `vDivInt` - 除以整数 +- `vAdd` - 增加浮点数 +- `vSub` - 减少浮点数 +- `vMul` - 乘以浮点数 +- `vDiv` - 除以浮点数 +- `vString` - 设置字符串 +- `vNumberInt` - 设置 整数 +- `vNumber` - 设置 浮点数 + diff --git a/doc/mvvm/VMParent.md b/doc/mvvm/VMParent.md new file mode 100644 index 0000000..d88acec --- /dev/null +++ b/doc/mvvm/VMParent.md @@ -0,0 +1,23 @@ +## VM Parent + +### 介绍 + +如果你想要让你的组件具有 动态监听数据的能力,需要继承 VMParent 使用。监听的数据类型为组件实例自身所有,是局部的数据而非全局数据。 + +### 属性 + +`data` - 定义需要绑定的数据类型,只在该组件内有效。定义后,这些数据就会被自动绑定。 + +`onBind()` - 数据绑定完成后调用该方法 + +`onUnBind()` - 数据绑定解除之前调用该方法 + +`tag` - 绑定的标签,可以通过这个tag 获取 当前的 vm 实例 + +`VM` - VM 管理对象,可以使用该对象获取值路径 + +### 注意事项 + +- 如果你不清楚继承机制,不要随意覆盖 onLoad() 事件,请使用 onBind() 函数代替 onLoad() 函数, onUnBind() 函数代替 onDestroy() 函数。如果你熟悉,可以使用super.onLoad() 的方式 调用父方法 +- 不要过多的嵌套使用VMParent, 在绑定时可能会影响一点性能 + diff --git a/doc/mvvm/VMProgress.md b/doc/mvvm/VMProgress.md new file mode 100644 index 0000000..f8ef46f --- /dev/null +++ b/doc/mvvm/VMProgress.md @@ -0,0 +1,14 @@ +## VM Progress + +### 介绍 + +VM组件 进度条设置,适合任意的进度条组件,比如 ProgressBar,cc.Slider 等。接受两个watchPath 的值,最后会将变动结果反映在 progress 属性上。使用方式和 VM Custom 组件一致。 + +### 编辑器属性 + +- `Controller` - 激活controller,以开启双向绑定,否则只能接收消息 +- `Watch Path Arr` - 绑定数值监听路径数组,注意你必须设置一个 长度为 2 的数组,第一个值是最小值,第二个值是最大值,这样才会正确的计算出 progres 属性 +- `Component Name` - 绑定组件的名字 (会根据脚本配置自动识别) +- `Component Property` - 绑定组件上需要监听的属性 (会根据脚本配置自动识别) +- `refreshRate` - 刷新间隔频率 (只影响脏检查的频率) ,controller开启后生效 + diff --git a/doc/mvvm/VMState.md b/doc/mvvm/VMState.md new file mode 100644 index 0000000..c9c5e1d --- /dev/null +++ b/doc/mvvm/VMState.md @@ -0,0 +1,42 @@ +## VM State + +### 介绍 + +VM组件 状态条件,根据watchPath 路径,判断值是不是符合条件,再设置对应节点的状态。 可以根据数据改变节点的颜色,节点的激活与关闭等等情况。 + +### 编辑器属性 + +- `Watch Path ` - 绑定数值监听路径 +- `Foreach Child Mode` - 特殊的比较值的方式,它会拿当前节点下的所有子节点的名字作为值的比较,来控制所有子节点的显示状态。 +- `Foreach Child Type` - `NODE_INDEX` 比较节点的index 值 或者 `NODE_NAME` 比较节点的名字 +- `Condition` - 判断条件,判断值的的大小是否符合条件 +- `Value Action`- 效果行为,当状态满足时候执行的条件 +- `Watch Nodes` - 需要变化状态的节点,如果不设置,默认就会改变本节点以及子节点的所有状态。 + +### 效果行为 + +- `NODE_ACTIVE` - 改变节点的激活状态(挂载到本节点无效) + +- `NODE_VISIBLE` - 改变节点的显示状态(不透明度切换) ,挂载到本节点有效,只影响显示。 + +- `NODE_OPACITY` - 改变节点的不透明度 + + `Action Opacity` - 设置 不透明的值 + +- `NODE_COLOR` - 改变节点的颜色 + + `Action Color` - 设置颜色的值 + +- `COMPONENT_CUSTOM` - 完全自定义改变组件属性 + + `Component Name` - 组件名 + + `Component Property` - 组件上的属性 + + `Default Value` - 默认值 + + `Action Value` - 满足条件改变的值 + +### 注意事项 + +NODE_ACTIVE 条件 不会改变自身节点的 激活状态 \ No newline at end of file diff --git a/doc/mvvm/ViewModelScript.md b/doc/mvvm/ViewModelScript.md new file mode 100644 index 0000000..a6261dc --- /dev/null +++ b/doc/mvvm/ViewModelScript.md @@ -0,0 +1,107 @@ +## View Model Script + +### 介绍 + +View Model 的脚本用法 + +### 方法 + +VM是 VMManager 的实例, 用于管理所有的 ViewModel 实例。ViewModel实例 主要用于实现数据的双向绑定,内部使用了 cc.director.emit 方法 来发送数据变动的消息,在使用时你可以不用关注于这些细节。 + +我们可以通过 import VM(VMManager) 对象 来管理 所有的 ViewModel ,**不建议**直接去使用 ViewModel 实例。 + +```typescript +//TS 使用 import 引入 +import { VM } from './ViewModel'; + +//JS 可以使用 require 的方式引入,其他用法没有区别 +const { VM } = require('./ViewModel'); +``` + +- `add` - 创建并且添加一个 ViewModel 对象 + + ``` typescript + VM.add(data,tag); + //data - 你想要进行 绑定 的数据对象 + //tag - 该数据对象的索引标签,用于之后获取该 ViewModel 对象 + ``` + +- `get` - 获取 + + ```typescript + let vm = VM.get(tag);//获取的结果是一个 ViewModel 对象 + let data = vm.$data; //获取 vm 绑定的 data 对象 + vm.active = false; // 关闭 vm 的数据通知功能 + ``` + +- `remove` - 移除 + + ```typescript + VM.remove(tag);//移除一个指定 tag 的 ViewModel 对象 + ``` +- `setValue` - 设置一个值(以tag开头的全局路径) + + ```typescript + VM.setValue('global.player.name','wss'); + //注意 global 是 ViewModel 的标签,player.name 是 ViewModel 内部的取值路径 + //使用 VM 全局管理,必须按这种全局路径的方式设置值 + ``` +- `addValue` - 累加一个值(以tag开头的全局路径) + + ```typescript + VM.addValue('global.player.hp',10); + ``` + +- `getValue` - 获取一个值(以tag开头的全局路径) + + ```typescript + VM.getValue('global.player.name',default);//default 是 默认值 + ``` + +- `setObjValue` - 以路径的形式 设置 一个 对象的值 +- `getObjValue` - 以路径的形式 获取 一个 对象的值 +- `bindPath` - 绑定需要监听的路径 +- `unbindPath` - 取消绑定需要监听的路径 +- `active` - 激活 数值变动的事件通知 +- `inactive` - 关闭 数值变动的事件通知 + +### 例子 + +```typescript +import { VM } from './ViewModel'; + +//构建数据对象 +let data = { + name:'user', + gold:12200, + info:{ + id:0 + } +} +//创建 VM 对象,并且添加到 VMManager 来进行管理, 标记为 'user' 标签 +VM.add(data,'user'); + + //通过 'user' 标签获取一个 ViewModel 的实例 +let vm = VM.get('user'); +vm.$data; // vm.$data === data; + + //设置新的属性值 +vm.setValue('name','new Name'); + +//获取属性 +vm.getValue('gold'); + + //通过相对路径获取属性 +vm.getValue('info.id'); + +//一旦修改值,将会通知 cc.director, 使用emit 发送消息 +data.name = 'my_name'; + +//关闭激活状态后,就不会通知 cc.director 传递信息了 +vm.active = false; + +//移除ViewModel,并且释放 data 的引用 +VM.remove('user'); +data = null; +``` +