kuikly-animation

Kuikly Animation System Development Assistant (Kuikly DSL). Guides how to implement property animations such as opacity, backgroundColor, transform (translation/scale/rotation/skew), and frame using declarative animations (animate + reactive variables) and imperative animations (animateToAttr + ViewRef), covering Animation curve configuration, serial/parallel animation orchestration, animation cancellation and looping, and other advanced patterns. Use when users need to implement animation effects, troubleshoot animations not taking effect, or perform complex animation orchestration in Kuikly.

Kuikly Animation System

Core Concepts

Kuikly animation describes the property transition process of a view fromState A toState B . Three major elements:

1. Animatable properties: transform (translation/scale/rotation/skew), opacity, backgroundColor, frame (position and size)
2. Animation object: controls the animation curve, duration, delay, and whether to loop
3. Trigger method: declarative (driven by reactive variables) or imperative (directly calling animateToAttr)

Comparison of the two animation approaches

Feature	Declarative animation	Imperative animation
Trigger method	Automatically triggered by changes in reactive variables	Manually call animateToAttr
Core API	attr { animate(animation, value) }	viewRef?.view?.animateToAttr(animation) { ... }
Applicable scenarios	Simple state transition animations	Complex animation orchestration, serial animations
End callback	event { animationCompletion { } }	completion parameter callback
Recommended level	Preferred for simple animations	Recommended for complex animations

---

Animation object

Animation curve types

// 基础曲线
Animation.linear(durationS, key = "")        // 线性
Animation.easeIn(durationS, key = "")        // 先慢后快
Animation.easeOut(durationS, key = "")       // 先快后慢
Animation.easeInOut(durationS, key = "")     // 两端慢中间快

// 弹簧曲线（额外参数：damping 阻尼, velocity 初速度）
Animation.springLinear(durationS, damping, velocity, key = "")
Animation.springEaseIn(durationS, damping, velocity, key = "")
Animation.springEaseOut(durationS, damping, velocity, key = "")
Animation.springEaseInOut(durationS, damping, velocity, key = "")

Animation process control

Animation.linear(0.5f)
    .delay(0.3f)              // 延迟 0.3 秒启动
    .repeatForever(true)      // 无限循环

Parameter description

Parameter	Type	Description
durationS	Float	Animation duration (seconds)
key	String	Animation identifier, used in the animationCompletion callback to distinguish animations
damping	Float	Spring damping coefficient
velocity	Float	Spring initial velocity

---

Animatable properties and Transform class

Transform type

Class	Constructor parameters	Description
Translate(percentageX, percentageY)	X/Y translation percentage [-1,1], can exceed	Translation, supports offsetX/offsetY (dp)
Scale(x, y)	Scale ratio [0, max]	Scale
Rotate(angle)	Angle [-360, 360]	2D rotation (around the Z axis)
Rotate(angle, xAngle, yAngle)	Angle for each axis	3D rotation
Skew(horizontalAngle, verticalAngle)	Skew angle (-90, 90)	Skew
Anchor(x, y)	Anchor point [0, 1]	Center point of transform, default (0.5, 0.5)

transform method signature

fun transform(
    rotate: Rotate = Rotate.DEFAULT,
    scale: Scale = Scale.DEFAULT,
    translate: Translate = Translate.DEFAULT,
    anchor: Anchor = Anchor.DEFAULT,
    skew: Skew = Skew.DEFAULT
)

// 便捷重载（只传单个 transform 类型）
fun transform(rotate: Rotate)
fun transform(scale: Scale)
fun transform(translate: Translate)
fun transform(skew: Skew)

---

Declarative Animation Quick Start

var flag by observable(false)

View {
    attr {
        size(100f, 100f)
        backgroundColor(if (ctx.flag) Color.GREEN else Color.RED)
        animate(Animation.linear(0.5f), ctx.flag)
    }
}

// 触发动画
flag = true

Detailed usage(animate scope, sibling scope, parent-child scope): see DECLARATIVE_ANIMATION.md

Imperative Animation Quick Start

var viewRef: ViewRef<DivView>? = null

View {
    ref { ctx.viewRef = it }
    attr {
        size(100f, 100f)
        backgroundColor(Color.RED)
    }
}

// 触发动画
viewRef?.view?.animateToAttr(Animation.linear(0.5f), attrBlock = {
    backgroundColor(Color.GREEN)
}, completion = { finished ->
    // finished: true=完成, false=被取消
})

Detailed usage: see IMPERATIVE_ANIMATION.md

Advanced animation modes

Serial animations, parallel animations, starting an animation midway, animation cancellation, etc.: see ANIMATION_PATTERNS.md