How to Implement Component-Level Animations in Luban H5: A Complete Guide

Luban H5 provides a reusable animation system through the animationMixin that attaches to any component, stores animation sequences in the element model's animations array, and triggers them via the global RUN_ANIMATIONS Vue event.

Component-level animations in Luban H5 (ly525/luban-h5) enable dynamic visual effects on shapes, images, and text elements within the H5 page editor. The system centers around a Vue mixin architecture that abstracts CSS animation handling while providing both programmatic APIs and visual editing capabilities through dedicated core modules.

Core Animation Architecture

The animation system relies on the animation mixin located at src/components/core/mixins/animation.js. This mixin injects the runAnimations() method into components and registers a listener for the global RUN_ANIMATIONS Vue event.

Each element maintains its animation queue in the animations array property defined in src/components/core/models/element.js. The system supports standard Animate.css animation types mapped in src/components/core/constants/animation.js, which exposes the animationOptions list used by the editor interface.

Step-by-Step Implementation

Step 1: Add the Animation Mixin to Your Component

Import animationMixin and include it in your component’s mixins array to enable animation capabilities. The mixin is already implemented in core components like src/components/core/preview/node-wrapper.js and src/components/core/support/shape.js.

// src/components/custom/my-box.vue
<script>
import animationMixin from '@/components/core/mixins/animation.js'

export default {
  name: 'MyBox',
  mixins: [animationMixin],
  // component logic …
}
</script>

Step 2: Define Animation Data on the Element Model

The element model stores animations as objects in the animations array. Each object requires specific properties to control timing and behavior.

{
  type: 'fadeIn',      // animation name (see Animate.css)
  duration: 0.5,       // seconds
  delay: 0,            // seconds
  interationCount: 1, // repeat count
  infinite: false      // true → infinite loop
}

Programmatically update an element’s animations through the store:

import store from '@/store'

// Assume `currentElement` is the element being edited
store.commit('updateElement', {
  id: currentElement.id,
  animations: [
    { type: 'bounceIn', duration: 1, delay: 0, interationCount: 1, infinite: false },
    { type: 'fadeOut',  duration: 0.5, delay: 0.2, interationCount: 1, infinite: false }
  ]
})

Step 3: Trigger Animations via the Global Event

Emit the RUN_ANIMATIONS event to execute the animation queue across all components that include the mixin.

// Anywhere in the app
window.EditorApp && window.EditorApp.$emit('RUN_ANIMATIONS')

When triggered, runAnimations() iterates through the element’s animations queue, builds an inline style object with CSS animation properties, and applies it to the component’s root element. After each animation ends, the animationend listener advances to the next animation or restores the original style.

Step 4: Render Animation Attributes for Preview

During preview rendering, Luban H5 translates the first animation in the queue into data attributes on the DOM element. The system adds data-swiper-animation, data-duration, and data-delay attributes to enable third-party animation libraries (such as Swiper’s Animate.css integration) to play automatically.

Configuring Animations Through the Editor UI

The right-panel editor at src/components/core/editor/right-panel/animation.js provides the RenderAnimationEditor component for visual configuration. This interface allows users to add, reorder, and delete animations without writing code.

Users select animation types from the animationOptions constant defined in src/components/core/constants/animation.js, adjusting duration, delay, and repeat settings. The editor populates the element’s animations array directly, which the mixin consumes at runtime when runAnimations() is invoked.

Summary

• The animation mixin (src/components/core/mixins/animation.js) provides the runAnimations() method and registers the global RUN_ANIMATIONS event listener for all consuming components.
• Animation sequences are stored as objects in the element model's animations array with properties for type, duration, delay, interationCount, and infinite.
• Components must include the mixin in their definition to enable animation capabilities and event responsiveness.
• The preview system renders data-swiper-animation, data-duration, and data-delay attributes for compatibility with third-party animation libraries.
• The right-panel editor offers visual configuration of component-level animations through the RenderAnimationEditor component.

Frequently Asked Questions

How do I add animations to a custom component in Luban H5?

Import animationMixin from @/components/core/mixins/animation.js and include it in your component's mixins array. This injects the runAnimations() method and registers the component to respond to the global RUN_ANIMATIONS Vue event emitted by the editor.

What animation properties does Luban H5 support?

According to the element model in src/components/core/models/element.js, each animation object supports: type (the Animate.css animation name), duration (in seconds), delay (in seconds), interationCount (integer repeat count), and infinite (boolean flag for continuous looping).

How are animations triggered during preview mode?

The system emits the global RUN_ANIMATIONS event via window.EditorApp.$emit('RUN_ANIMATIONS'). The animation mixin catches this event and invokes runAnimations(), which applies CSS animation styles sequentially and listens for animationend events to chain multiple animations on the component.

Can I use infinite loop animations in Luban H5?

Yes. Set infinite: true in the animation object definition. When runAnimations() processes the queue, it checks this property to configure the CSS animation iteration count appropriately, allowing components to animate continuously until the animation data is cleared or the component is destroyed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}