6 February 2020 / 开发笔记

Cocos Creator控制龙骨DragonBones动画

前言

Cocos Creator要是用龙骨DragonBones动画，可以使用自带的组件：DragonBones组件: dragonBones.ArmatureDisplay

DragonBones

官方文档：https://docs.cocos.com/creator/manual/zh/components/dragonbones.html
接口文档：https://docs.cocos.com/creator/api/zh/modules/dragonBones.html

仔细看的话，会发现，这个组件只暴露了一些非常简单也很有限的接口，文档也写的过于简单。

如果要对龙骨动画进行精细化控制，则需要调用DragonBones库的接口，而这个库的接口是没有文档的。

DragonBones库的代码，在Cocos Creator的引擎代码中可以找到，然后可以从dragonBonse.d.ts文件里查看相应的接口。
CocosCreator_DragonBones_01

这里整理一下相关的操作。

操作列表

1. 播放动画

术语

骨架 = Armatrue
动画 = Animation

通常一个龙骨项目包含多个Armature，而每个Armature可以包含多个Animation。

所以，一般来说，我们实际的需求是切换动画，而不是切换骨架。

接口

这个功能可以通过修改dragonBones.ArmatureDisplay组件的属性来实现：
CocosCreator_DragonBones_02

指定骨架
dragonBones.ArmatureDisplay.armatureName = 骨架名称
播放该骨架下的动画
dragonBones.ArmatureDisplay.playAnimation("动作名", 循环次数);

参数

-1 表示使用配置文件中的默认值；
0 表示无限循环；
>0 表示循环次数

示例

@property(dragonBones.ArmatureDisplay)
display:dragonBones.ArmatureDisplay = null;

display.armatureName = "move";
display.playAnimation("跑", -1);

文档

https://docs.cocos.com/creator/api/zh/classes/ArmatureDisplay.html#armatureName

2. 中止动画

dragonBones.ArmatureDisplay组件并没有提供stop方法，只能去dragonBones库去找了。
在dragonBonse.d.ts文件中发现，dragonBones.Animation类有很多方法可以用。

接口

获取骨骼
dragonBones.ArmatureDisplay.armature()
获取动画
dragonBones.ArmatureDisplay.armature().Animation

注意，这个方法返回的是dragonBones.Animation对象。

停止动画
dragonBones.Animation.stop("动画名")

参数
要停止的指定动画名，如果，不指定，则停止所有动画。

示例

// 终止所有的动作
display.armature().animation.stop();

3. 从动画中间开始播放

有时候，我们需要从动画的中间开始播放，这个功能也只能通过dragonBones.Animation对象来实现。

接口

从指定帧播放
gotoAndPlayByFrame(animationName: string, frame?: number, playTimes?: number): AnimationState | null;
从指定时间播放
gotoAndPlayByTime(animationName: string, time?: number, playTimes?: number): AnimationState | null;
从指定的百分比进度播放
gotoAndPlayByProgress(animationName: string, progress?: number, playTimes?: number): AnimationState | null;

示例

display.armature().animation.gotoAndPlayByFrame(animationName, nFrame, loop);

4. 根据事件中止动画

这个功能需要先监听指定动画事件，然后在事件处理方法中调用2.的中止方法。

dragonBones.ArmatureDisplay组件提供了事件监听方法
https://docs.cocos.com/creator/api/zh/classes/ArmatureDisplay.html#addeventlistener

接口

监听
dragonBones.ArmatureDisplay.addEventListener(eventType, callback, target)
取消监听
dragonBones.ArmatureDisplay.removeEventListener(eventType, callback, target)
事件列表
** 帧事件（需在龙骨动画里添加动画事件）
dragonBones.EventObject.FRAME_EVENT
** 动画循环播放完成一次。
dragonBones.EventObject.LOOP_COMPLETE
** 动画播放完成。
dragonBones.EventObject.COMPLETE

事件对象的细节，以及更多事件可以在ArmatureDisplay.js文件中找到。


/**
 * !#en
 * Animation start play.
 * !#zh
 * 动画开始播放。
 *
 * @event dragonBones.EventObject.START
 * @param {String} type - A string representing the event type to listen for.
 * @param {Function} callback - The callback that will be invoked when the event is dispatched.
 *                              The callback is ignored if it is a duplicate (the callbacks are unique).
 * @param {dragonBones.EventObject} [callback.event]
 * @param {String} [callback.event.type]
 * @param {dragonBones.Armature} [callback.event.armature]
 * @param {dragonBones.AnimationState} [callback.event.animationState]
 */

/**
 * !#en
 * Animation loop play complete once.
 * !#zh
 * 动画循环播放完成一次。
 *
 * @event dragonBones.EventObject.LOOP_COMPLETE
 * @param {String} type - A string representing the event type to listen for.
 * @param {Function} callback - The callback that will be invoked when the event is dispatched.
 *                              The callback is ignored if it is a duplicate (the callbacks are unique).
 * @param {dragonBones.EventObject} [callback.event]
 * @param {String} [callback.event.type]
 * @param {dragonBones.Armature} [callback.event.armature]
 * @param {dragonBones.AnimationState} [callback.event.animationState]
 */

/**
 * !#en
 * Animation play complete.
 * !#zh
 * 动画播放完成。
 *
 * @event dragonBones.EventObject.COMPLETE
 * @param {String} type - A string representing the event type to listen for.
 * @param {Function} callback - The callback that will be invoked when the event is dispatched.
 *                              The callback is ignored if it is a duplicate (the callbacks are unique).
 * @param {dragonBones.EventObject} [callback.event]
 * @param {String} [callback.event.type]
 * @param {dragonBones.Armature} [callback.event.armature]
 * @param {dragonBones.AnimationState} [callback.event.animationState]
 */

/**
 * !#en
 * Animation fade in start.
 * !#zh
 * 动画淡入开始。
 *
 * @event dragonBones.EventObject.FADE_IN
 * @param {String} type - A string representing the event type to listen for.
 * @param {Function} callback - The callback that will be invoked when the event is dispatched.
 *                              The callback is ignored if it is a duplicate (the callbacks are unique).
 * @param {dragonBones.EventObject} [callback.event]
 * @param {String} [callback.event.type]
 * @param {dragonBones.Armature} [callback.event.armature]
 * @param {dragonBones.AnimationState} [callback.event.animationState]
 */

/**
 * !#en
 * Animation fade in complete.
 * !#zh
 * 动画淡入完成。
 *
 * @event dragonBones.EventObject.FADE_IN_COMPLETE
 * @param {String} type - A string representing the event type to listen for.
 * @param {Function} callback - The callback that will be invoked when the event is dispatched.
 *                              The callback is ignored if it is a duplicate (the callbacks are unique).
 * @param {dragonBones.EventObject} [callback.event]
 * @param {String} [callback.event.type]
 * @param {dragonBones.Armature} [callback.event.armature]
 * @param {dragonBones.AnimationState} [callback.event.animationState]
 */

/**
 * !#en
 * Animation fade out start.
 * !#zh
 * 动画淡出开始。
 *
 * @event dragonBones.EventObject.FADE_OUT
 * @param {String} type - A string representing the event type to listen for.
 * @param {Function} callback - The callback that will be invoked when the event is dispatched.
 *                              The callback is ignored if it is a duplicate (the callbacks are unique).
 * @param {dragonBones.EventObject} [callback.event]
 * @param {String} [callback.event.type]
 * @param {dragonBones.Armature} [callback.event.armature]
 * @param {dragonBones.AnimationState} [callback.event.animationState]
 */

/**
 * !#en
 * Animation fade out complete.
 * !#zh
 * 动画淡出完成。
 *
 * @event dragonBones.EventObject.FADE_OUT_COMPLETE
 * @param {String} type - A string representing the event type to listen for.
 * @param {Function} callback - The callback that will be invoked when the event is dispatched.
 *                              The callback is ignored if it is a duplicate (the callbacks are unique).
 * @param {dragonBones.EventObject} [callback.event]
 * @param {String} [callback.event.type]
 * @param {dragonBones.Armature} [callback.event.armature]
 * @param {dragonBones.AnimationState} [callback.event.animationState]
 */

/**
 * !#en
 * Animation frame event.
 * !#zh
 * 动画帧事件。
 *
 * @event dragonBones.EventObject.FRAME_EVENT
 * @param {String} type - A string representing the event type to listen for.
 * @param {Function} callback - The callback that will be invoked when the event is dispatched.
 *                              The callback is ignored if it is a duplicate (the callbacks are unique).
 * @param {dragonBones.EventObject} [callback.event]
 * @param {String} [callback.event.type]
 * @param {String} [callback.event.name]
 * @param {dragonBones.Armature} [callback.event.armature]
 * @param {dragonBones.AnimationState} [callback.event.animationState]
 * @param {dragonBones.Bone} [callback.event.bone]
 * @param {dragonBones.Slot} [callback.event.slot]
 */

/**
 * !#en
 * Animation frame sound event.
 * !#zh
 * 动画帧声音事件。
 *
 * @event dragonBones.EventObject.SOUND_EVENT
 * @param {String} type - A string representing the event type to listen for.
 * @param {Function} callback - The callback that will be invoked when the event is dispatched.
 *                              The callback is ignored if it is a duplicate (the callbacks are unique).
 * @param {dragonBones.EventObject} [callback.event]
 * @param {String} [callback.event.type]
 * @param {String} [callback.event.name]
 * @param {dragonBones.Armature} [callback.event.armature]
 * @param {dragonBones.AnimationState} [callback.event.animationState]
 * @param {dragonBones.Bone} [callback.event.bone]
 * @param {dragonBones.Slot} [callback.event.slot]
 */

示例

// 监听
display.addEventListener(dragonBones.EventObject.FRAME_EVENT, this.onFrameEvent, this);

// 事件处理
onFrameEvent(evt){
    if(this._stopEvent == evt.name){
        evt.armature.animation.stop(this._currentAnimation);
        this._stopEvent = undefined;
    }
}

扫一扫关注微信公众号：耿直的IT男阿斌

聊一聊IT男眼中的世界