@shijiu/jsview-vue 2.3.151-test.0 → 3.0.0

package/utils/JsViewVueWidget/JsvFreeMoveActor/ActorControl.ts

@@ -4,6 +4,56 @@
  * @LastEditors: donglin.lu@qcast.cn
  * @Description: file content
  */
+
+/*
+ * ActorControl
+ * 对 JsvFreeMoveActorDiv 进行控制
+ * 
+ * 开发者通过 ActorControl 的实例, 来对 JsvFreeMoveActorDiv 进行控制, 思路:
+ * 拿到ActorControl实例后, 通过 run(cmdPackList) 讲编排好的指令集一次性组织好, 送到render进行执行,
+ * 执行过程中，除了condition触发的(ActorState)=>{} 类型的回调外, 其余动画处理都不会与js端进行交互。
+ * 
+ * 进行动画设计时, 尽量避免 (ActorState)=>{} 回调中再调用 ActorControl.run(...)的模式, 以规避js性能低的问题影响到动画的流畅性。
+ * 比较好的设计模式是, ActorControl.run(...) 几乎都是界面初始化或者用户输入时进行(例如focusBlock的onKeyDown),
+ * 而 (ActorState)=>{} 回调中, 最好只放置辅助用户输入判断的状态的更新, 以及 state().updateBaseOffset(...) 这种对dom元素进行重新定位的场景。
+ * dom元素重新定位也一般只用于动画结束,要永久保留动画后的位置的场景。
+ * 
+ * cmdPackList: 
+ *     由 action(), state(), condition() 组成的指令集
+ *     在condition().xxxx.then() 中, 多一种指令类型 (actorState)=>{}, 用于对接此condition触发后, 讲actor信息同步给js
+ * 
+ * ------------------------------------------------------------
+ * 以下是 JsvFreeMoveActorDiv 中坐标概念说明:
+ * 
+ * JsvFreeMoveActorDiv 的基准坐标: baseX, baseY
+ * 此坐标不会被直接记录, 在组件内部以 baseOffsetX, baseOffsetY 记录, 初始值为(0, 0)
+ * baseX = -baseOffsetX
+ * baseY = -baseOffsetY
+ * 主要用于解决div的style.top, style.left改变前后, condition设置的条件中的坐标不会发生偏移。
+ * 具体思路是: condition创建时, 会记录当时的 baseOffset 坐标, 进行判断的时候将其条件中设定的x和y以当时记录的baseOffset转成baseX和baseY坐标,
+ * 而与之进行比较的 drawX 和 drawY, 也通过最新的baseOffset转成baseX和baseY坐标, 然后再进行比较。
+ * baseOffset的变更, 发生在本div的style.top, style.left进行改变时, 开发者会通过 state().updateBaseOffset(
+ *     originStyle.top - style.top, 
+ *     originStyle.left - style.left) 主动同步信息到控制系统。
+ * 
+ * JsvFreeMoveActorDiv 的绘制坐标: drawX, drawY
+ * 
+ * JsvFreeMoveActorDiv 的最终屏幕坐标:
+ * x = 父dom节点的屏幕坐标x + 本div的style.left + drawX;
+ * y = 父dom节点的屏幕坐标y + 本div的style.top + drawY;
+ * 
+ * ------------------------------------------------------------
+ * 每个JsvFreeMoveActorDiv内部状态变量分为8个:
+ * drawX: 参考上述坐标说明, 每帧会被SpeedX调整, 也可通过 action() 或者 state() 直接改变
+ * drawY: 参考上述坐标说明, 每帧会被SpeedY调整, 也可通过 action() 或者 state() 直接改变
+ * baseOffsetX: 参考上述坐标说明, 改变方式只有 state().updateBaseOffset(...)
+ * baseOffsetY: 参考上述坐标说明, 改变方式只有 state().updateBaseOffset(...)
+ * SpeedX: 帧间运行后，对drawX的增量, 只能通过 action() 改变
+ * SpeedY: 帧间运行后，对drawY的增量, 只能通过 action() 改变
+ * AccelerationX: 帧间运行后，对SpeedX的增量, 只能通过 action() 改变
+ * AccelerationY: 帧间运行后，对SpeedY的增量, 只能通过 action() 改变
+ */
+
 import ConditionPackBuilder from "./SetCondition";
 import ActionPackBuilder from "./SetAction"
 import StatePackBuilder from "./SetState";
@@ -16,6 +66,19 @@ interface CmdListCreator {
   (builders: BuilderFactory): Array<Object>;
 }
 
+interface ConditionConfig {
+  group?: number;
+  multiTimes?: boolean;
+  specName?: string | null;
+  shoudRenderBreak?: boolean;
+}
+
+interface ActionConfig {
+  xySpeedKeeps?: number;
+  xyAccKeeps?: number;
+  nexusRecv?: NexusNode | null;
+}
+
 class BuilderFactory {
   private _SharedQuickConditionPackBuilder: ConditionPackBuilder;
   private _SharedQuickActionPackBuilder: ActionPackBuilder;
@@ -36,67 +99,167 @@ class BuilderFactory {
 
   /**
    * Condition
-   * 获取创建 ConditionPack 的工厂对象
+   * 获取创建 Condition指令 的工厂对象
+   * 用法示例:
+   *   actorControl.run((cmds)=>[ // cmds: 即为 BuilderFactory 的实例
+   *     cmds.condition(...).条件指令(...).then([  // 条件指令: 例如 wallPosition()
+   *       cmds.condition(...).其他条件指令(...),  // 其他condition创建
+   *       (actorState)=>{
+   *         // 条件满足时预设的指令集
+   *         console.log(
+   *           "condition triggered",
+   *           actorState.xPos, actorState.yPos,
+   *           actorState.xSpd, actorState.ySpd,
+   *           actorState.xAcc, actorState.yAcc);
+   *       },
+   *       ...  // 其他command
+   *     ]),
+   *     ...  // 其他command
+   *   ]);
+   * 
    * ConditionPack对应支持 .then(cmdPackList), 可传入同 Run 的处理队列
-   * 可用方法见 ./SetCondition.js
-   * @param {int} group 可选参数，默认为0, 有效值为0~3, 对应默认组, 1组, 2组, 3组, 便于remove时，按组进行清理
+   * cmdPackList中是新的由 action(), state(), condition(), (actorState)=>{} 组成的指令集
+   * 其中(actorState)=>{} 是 condition().xxxx.then() 中独有的指令类型, 用于对接此condition触发后, 进行js端的回调
+   * actorState {
+   *   xPos: number, // 当前drawX的值
+   *   yPos: number, // 当前drawY的值
+   *   xSpd: number, // 当前SpeedX的值
+   *   ySpd: number, // 当前SpeedY的值
+   *   xAcc: number, // 当前AccelerationX的值
+   *   yAcc: number, // 当前AccelerationY的值
+   * }
+   * 
+   * 创建condition时, 会记录当时的 baseOffset 坐标, 其设定值在进行比较时会转换成baseX和baseY坐标, 然后进行比较
+   * 所以不同担心div的style.top, style.left改变后, condition设置的条件中的坐标会发生偏移导致需要重新设置
+   * 比如: wallPosition(), boxPosition() 这种要常驻的condition
+   * 
+   * boxPosition 用法示例(边界框与背景div尺寸一致):
+   *   // div1 背景: (0, 0) -> (400, 400)
+   *   cmds.condition({ multiTimes: true })
+   *     .boxPosition(0, 0, 400, 400)
+   *     .then([cmds.action().stopMoving(true)]);
+   * 
+   *   // div2 背景: (0, 0) -> (200, 200)
+   *   cmds.condition({ multiTimes: true })
+   *     .boxPosition(0, 0, 200, 200)
+   *     .then([cmds.action().stopMoving(true)]);
+   * 
+   * condition创建时, 可以用group和specName进行归类, 以便于后续按需清理, 例如: 
+   * wallPosition()在一启动的时候有, 后续就没有了, 而还有其他condition存在, 不能使用state().clearConditions()全清理
+   * 
+   * action指令内部也可能自己创建一些associated condition, 这些condition会被action执行完成后自动回收, 不需要通过state指令主动清理
+   * 
+   * 可用方法见 @file://./SetCondition.ts
+   * @param {int | ConditionConfig} configOrGroup 可选参数，默认为0, 有效值为0~3, 对应默认组, 1组, 2组, 3组, 便于remove时，按组进行清理, 单个Anim中唯一, Anim之间可重名
+   *                                     也可以传入一个Object, 包含 group, multiTimes, specName, shoudRenderBreak 四个属性
    * @param {boolean} multiTimes 可选参数，默认为false, 是否要多次执行, 
    *                      若为单次, 当group未设定时自动作废，当group设定时，不作废但改为deactive状态
-   * @param {string} specName 可选参数，默认null, 命名condition, 用于指定名字进行active/deactive动作的场景
+   * @param {string} specName 可选参数，默认null, 命名condition, 单个Anim中唯一, Anim之间可重名, 用于指定名字进行active/deactive动作的场景
    * @param {boolean} shoudRenderBreak 可选参数，默认false, 关联的回调是否会发起RenderBreak
-   * @return {ConditionPackBuilder} ConditionPack 的工厂对象
+   * @return {ConditionPackBuilder} Condition指令的工厂对象
    */
   condition(
-    group: number = 0,
-    multiTimes: boolean = false,
-    specName: string | null = null,
-    shoudRenderBreak: boolean = false
+    configOrGroup?: ConditionConfig | number,
+    multiTimes?: boolean,
+    specName?: string | null,
+    shoudRenderBreak?: boolean
   ): ConditionPackBuilder {
+    let _group: number = 0;
+    let _multiTimes: boolean = false;
+    let _specName: string | null = null;
+    let _shoudRenderBreak: boolean = false;
+
+    if (typeof configOrGroup === 'object') {
+      _group = (configOrGroup as ConditionConfig).group || 0;
+      _multiTimes = (configOrGroup as ConditionConfig).multiTimes || false;
+      _specName = (configOrGroup as ConditionConfig).specName || null;
+      _shoudRenderBreak = (configOrGroup as ConditionConfig).shoudRenderBreak || false;
+    } else {
+      _group = configOrGroup ?? 0;
+      _multiTimes = multiTimes ?? false;
+      _specName = specName ?? null;
+      _shoudRenderBreak = shoudRenderBreak ?? false;
+    }
+
     // 注意: 不支持获取condition后，多次复制
     let builder: ConditionPackBuilder = this._SharedQuickConditionPackBuilder;
     if (builder.isInUsing()) {
       // 用于加速的builder被占用了，为了防止状态问题，使用新建builder
       builder = new ConditionPackBuilder(this._Callbacks, this._SelfNexusRecv, this);
     }
-    builder.updateCommandInfo(group, multiTimes, specName, shoudRenderBreak);
+    builder.updateCommandInfo(_group, _multiTimes, _specName, _shoudRenderBreak);
     return builder;
   }
 
   /**
    * Action
-   * 获取创建 ActionPack 的工厂对象
-   * 注意: ActionPack 是指会改变 speed 或 accelerate 并自动生成子condition的指令，
-   * 每个新的Action会覆盖掉前一次的Action设置，包括其关联的condition，
-   * 以及上一个action中的回调，以及上一个action中规划中的ActionEvent
-   * 可用方法见 ./SetAction.js
+   * 获取创建 Action指令 的工厂对象
    * 
-   * @param {int} xySpeedKeeps xy轴上的速度是否保持(与新Action不冲突的才会被保留)，
+   * 用法示例:
+   *   actorControl.run((cmds)=>[ // cmds: 即为 BuilderFactory 的实例
+   *     cmds.action(...).动作指令(...),  // 动作指令: 例如 teleportOffset()
+   *     ...  // 其他command
+   *   ]);
+   * 
+   * Action主要是改变speed和accelerate的值，在Action指令中还包含一些综合指令, 例如:
+   *    brakeToPosition: 通过内部创建一些associated condition来实现减速并停止到目标位置
+   *    setSpdAndAccel: 同时设置速度和加速度，并提供拐点回调(用于抛物线处理)
+   * 
+   * Action有个重要个规则: 一个FreeMoveActor中, 一个时间只会激活一条Action指令,
+   * 当下一条Action指令激活时, 会默认自动重置因为上一条Action而改变的SpeedX/Y(重置为0), AccelerationX/Y(重置为0), 以及其associated condition
+   * 但也可以进行主动保持, 通过 xySpeedKeeps 和 xyAccKeeps 参数控制
+   * 
+   * 可用方法见 @file://./SetAction.ts
+   * 
+   * @param {int | ActionConfig} configOrSpeedKeeps xy轴上的速度是否保持(与新Action不冲突的才会被保留)，
    *                           x轴保持为1, y轴保持为2，可"与或"让两个轴都保持
+   *                           也可以传入一个Object, 包含 xySpeedKeeps, xyAccKeeps, nexusRecv 三个属性
    * @param {int} xyAccKeeps xy轴上的加速度是否保持(与新Action不冲突的才会被保留)，
    *                         x轴保持为1, y轴保持为2，可"与或"让两个轴都保持
    * @param {NexusNode} nexusRecv 此动作发出的 nexusEvent 的接受者
-   * @return {ActionPackBuilder} ActionPack 的工厂对象
+   * @return {ActionPackBuilder} Action指令的工厂对象
    */
   action(
-    xySpeedKeeps: number = 0,
-    xyAccKeeps: number = 0,
-    nexusRecv: NexusNode | null = null
+    configOrSpeedKeeps?: ActionConfig | number,
+    xyAccKeeps?: number,
+    nexusRecv?: NexusNode
   ): ActionPackBuilder {
+    let _xySpeedKeeps: number = 0;
+    let _xyAccKeeps: number = 0;
+    let _nexusRecv: NexusNode | null = null;
+
+    if (typeof configOrSpeedKeeps === 'object') {
+      _xySpeedKeeps = (configOrSpeedKeeps as ActionConfig).xySpeedKeeps || 0;
+      _xyAccKeeps = (configOrSpeedKeeps as ActionConfig).xyAccKeeps || 0;
+      _nexusRecv = (configOrSpeedKeeps as ActionConfig).nexusRecv || null;
+    } else {
+      _xySpeedKeeps = configOrSpeedKeeps ?? 0;
+      _xyAccKeeps = xyAccKeeps ?? 0;
+      _nexusRecv = nexusRecv ?? null;
+    }
+
     let builder: ActionPackBuilder = this._SharedQuickActionPackBuilder;
     if (builder.isInUsing()) {
       // 用于加速的builder被占用了，为了防止状态问题，使用新建builder
       builder = new ActionPackBuilder(this._Callbacks, this._SelfNexusRecv);
     }
-    builder.updateCommonInfo(xySpeedKeeps, xyAccKeeps, nexusRecv);
+    builder.updateCommonInfo(_xySpeedKeeps, _xyAccKeeps, _nexusRecv);
     return builder;
   }
 
   /**
    * State
-   * 获取创建 StatePack 的工厂对象
+   * 获取创建 State指令 的工厂对象
+   * 
+   * 用法示例:
+   *   actorControl.run((cmds)=>[ // cmds: 即为 BuilderFactory 的实例
+   *     cmds.state(...).状态指令(...),  // 状态指令: 例如 clearConditions()
+   *     ...  // 其他command
+   *   ]);
+   * 
    * 在下一帧运行前的设置值，例如清理condition, 或者在下一帧运动的前调整启动运动的位置
-   * 可用方法见 ./SetState.js
-   * @return {StatePackBuilder} StatePack 的工厂对象
+   * 可用方法见 @file://./SetState.ts
+   * @return {StatePackBuilder} State指令的工厂对象
    */
   state(): StatePackBuilder {
     return this._StatePackBuilder;
@@ -122,6 +285,11 @@ class ActorControl {
     this._Builders = new BuilderFactory(this, this._Callbacks, this._SelfNexusRecv);
   }
 
+  /**
+   * 内部API
+   * 
+   * asSizeMode
+   */
   asSizeMode() {
     if (this._BindAnim != null) {
       console.error("error: asSizeMode should call before bindForgeView");
@@ -134,6 +302,15 @@ class ActorControl {
   //   return this._BindAnim?.AnimNativeId;
   // }
 
+  /**
+   * 内部API
+   * 
+   * bindForgeView
+   * 为普通的div创建ActorControl控制
+   * 
+   * @param {any} bindView forgeView实例
+   * @param {boolean} instantActive 是否立即激活动画
+   */
   bindForgeView(bindView: any, instantActive: boolean) {
     this._BindView = bindView;
 
@@ -143,7 +320,26 @@ class ActorControl {
   }
 
   /**
-   * run 执行编排好的intent集合
+   * run 创建并执行编排好的指令队列
+   * 
+   * 用法为
+   * actorControl.run((cmds)=>[ // 指令队列
+   *   cmds.state(...).状态指令(...),
+   *   cmds.action(...).动作指令(...),
+   *   cmds.condition(...).条件指令(...).then([
+   *     // 条件满足时预设的指令集队列
+   *     cmds.condition(...).其他条件指令(...),
+   *     (actorState)=>{
+   *       console.log(
+   *         "condition triggered",
+   *         actorState.xPos, actorState.yPos,
+   *         actorState.xSpd, actorState.ySpd,
+   *         actorState.xAcc, actorState.yAcc);
+   *     },
+   *     ...
+   *   ]),
+   *   ...
+   * ]);
    *
    * @param {CmdListCreator} commandsCreator 
    *                         命令指令队列创建回调
@@ -176,11 +372,21 @@ class ActorControl {
     RunFreeMoveCmdPacks(this._BindView, cmdPackList);
   }
 
+  /**
+   * 内部API
+   * 
+   * getBindedAnim
+   */
   getBindedAnim() {
     this._EnsureAnim();
     return this._BindAnim;
   }
 
+  /**
+   * 内部API
+   * 
+   * getBindedView
+   */
   getBindedView() {
     this._EnsureAnim();
     return this._BindView;
@@ -190,6 +396,9 @@ class ActorControl {
    * addCondCycleListener
    * 追加 cond cycle listener，可以根据start和end来进行callback时序排序
    * 
+   * 应对场景为, 在condition的 (ActorState)=>{} 回调中, 
+   * 当一帧中condition的多个回调发生时(可能复数的condition被触发,也可能是一个condition有多个回调), 协调这些回调的处理逻辑的场景
+   * 
    * @param {Function} startCycleCallback   开始执行一帧的js回调(condition的callback)
    * @param {Function} endCycleCallback  执行一帧的js回调完毕
    */
@@ -209,6 +418,13 @@ class ActorControl {
     }
   }
 
+  /**
+   * removeCondCycleListener
+   * 移除由 addCondCycleListener 加入的回调
+   * 
+   * @param {Function} startCycleCallback   开始执行一帧的js回调(condition的callback)
+   * @param {Function} endCycleCallback  执行一帧的js回调完毕
+   */
   removeCondCycleListener(startCycleCallback: Function, endCycleCallback: Function) {
     if (startCycleCallback && this._CondCycleStartList) {
       for (let i = 0; i < this._CondCycleStartList.length; i++) {
@@ -232,6 +448,7 @@ class ActorControl {
     // 遇到layout后仍然会因为新broadcast有动作时，一帧中可能会有多次回调
     let retJsonObject: any = JSON.parse(retJson);
     let echoRetList: Array<any> = retJsonObject["retList"];
+    delete retJsonObject["retList"]; // 删除retList, 避免回调中读取
     if (echoRetList) {
       if (this._CondCycleStartList && this._CondCycleStartList.length > 0) {
         for (let startCb of this._CondCycleStartList) {

package/utils/JsViewVueWidget/JsvFreeMoveActor/{FreeMoveActor.vue → JsvFreeMoveActor.vue}

@@ -23,7 +23,7 @@
  *          sizeMode: Boolean, 从控制div左上角坐标的模式改为改为通过div矩形宽高
  *                    (指令控制右下角坐标，实现对[0,0]->[右下角x,y]的矩形的宽高调整，另外，不支持负坐标)
  *      expose说明:
- *          control: Object 控制器句柄，具体参考 ActorControl
+ *          control: ActorControl ActorControl实例，详细使用规则见 @file://./ActorControl.ts
 -->
 <script setup>
 import ActControl from "./ActorControl.ts";

package/utils/JsViewVueWidget/JsvFreeMoveActor/SetAction.ts

@@ -193,6 +193,7 @@ class ActorPackBuilder {
    * @param {double} ySpeed 运行速度，使用时会自动取绝对值，单位(pixel/帧)
    *                       undefined时，若targetY设置, 则把edge作为运动目标，以另一轴速度反推此速度, 否则不改变该轴速度
    * @param {function} endCallback 参数(x, y) 运动到目标位置后的回调函数, x或者y达到后即回调，以先到为准，回报当前Actor的相对于原始位置的x,y
+   *                              是通过condition().then([(ActorState)=>{}])实现
    * @return CommandPack(放入run或者then的CmdPackList队列)
    */
   public moveTo(
@@ -249,6 +250,7 @@ class ActorPackBuilder {
    *      ySpeed      (double) 带符号整数，符号表示方向，标识运动的运行速度，单位(pixel/帧), 可设undefined代表不改变该轴速度
    *      spreadFrame    (int) 选填，正整数, 变速需要经历帧数, 若为立即变速，则设置为0，或者不再设置(undefined)
    *      finishCallback (Function(xSpeed, ySpeed)) 选填，达到目标速度后的回调，当costTime不为0时有效
+   *                              是通过condition().then([(ActorState)=>{}])实现
    */
   altSpeed(
     xSpeed: number | undefined,
@@ -300,7 +302,9 @@ class ActorPackBuilder {
    *      targetX      (int) 带符号整数，目标运动终点位置，如果设置为undefined，标识不以此轴为终点
    *      targetY      (int) 带符号整数，目标运动终点位置，如果设置为undefined，标识不以此轴为终点
    *      finishCallback  (Function(x,y)) 运动到目标位置后的回调函数, x或者y达到后即回调，以先到为准，回报当前Actor的相对于原始位置的x,y
+   *                              是通过condition().then([(ActorState)=>{}])实现
    *      rejectedCallback  (Function()) 当前速度无法达到target位置时，回调此函数，然后放弃改变任何速度和加速度
+   *                              是通过condition().then([(ActorState)=>{}])实现
    */
   brakeToPosition(
     targetX: number | undefined,
@@ -420,7 +424,7 @@ class ActorPackBuilder {
     return CmdPackBuilder.InitActCmdPack(this._SpeedKeeps, this._AccKeeps, this._NexusRecv?.token, cmdList);
   }
 
-  /*
+  /**
    * setSpdAndAccel 
    * 同时设置速度和加速度，并提供拐点回调(用于抛物线处理)
    * 
@@ -429,8 +433,8 @@ class ActorPackBuilder {
    *      spdY      (double) y 速度有效值，可正可负, 每帧的posY移动量, 可以传入undefined来决定此值不设置
    *      accelX    (double) 加速度有效值，可正可负，每帧spdX的调整量，可以传入undefined来决定此值不设置
    *      accelY    (double) 加速度有效值，可正可负，每帧spdY的调整量，可以传入undefined来决定此值不设置
-   *      onRevertX (function) x速度开始反向运动时，进行回调(例如抛物到达顶点)
-   *      onRevertY (function) y速度开始反向运动时，进行回调(例如抛物到达顶点)
+   *      onRevertX (function) x速度开始反向运动时，进行js回调(例如抛物到达顶点, 是通过condition().then([(ActorState)=>{}])实现)
+   *      onRevertY (function) y速度开始反向运动时，进行js回调(例如抛物到达顶点, 是通过condition().then([(ActorState)=>{}])实现)
    */
   setSpdAndAccel(
     spdX: number | undefined,
@@ -461,10 +465,12 @@ class ActorPackBuilder {
     return CmdPackBuilder.InitActCmdPack(this._SpeedKeeps, this._AccKeeps, this._NexusRecv?.token, cmdList);
   }
 
-  /*
+  /**
    * stopMoving
    * 停止运动
-   *      isExact (boolean) 设置为true时, 如果在positionCondition中会按照condition的位置进行精准停止
+   *      isExact (boolean) 设置为true时, 
+   *          如果在positionCondition中会按照condition的位置进行精准停止
+   *          从而解决在condition.then中停止时,停止的位置因为上帧的drawX/Y + speedX/Y并不是完全和condition不吻合,而希望吻合的问题
    */
   stopMoving(
     isExact: boolean = true