更新记录

1.0.0（2025-11-03） 下载此版本

更新日志

[1.0.0] - 2025-11-03

平台兼容性

uni-app(3.6.12)

uni-app x(3.6.12)

其他

hy-animation-plus

增强型动画与过渡效果组件库

为 uni-app 应用提供丰富、流畅、易用的动画解决方案

📖 简介

hy-animation-plus 是一个功能强大的动画组件库，专为 uni-app 开发者打造。提供多种预设动画和自定义动画能力，支持链式动画、交互动画、过渡动画等，可以轻松为您的应用添加生动的动画效果。

✨ 核心特性

• 🎭 多种预设动画：淡入淡出、滑动、缩放、旋转、弹跳等 50+ 预设动画
• 🔗 链式动画：支持多个动画按顺序或并行执行
• 🖱️ 交互动画：支持点击、长按、滑动等交互触发动画
• ⏱️ 过渡动画：页面切换和组件状态变化的过渡效果
• 🎨 自定义动画：支持自定义关键帧动画
• 📱 性能优化：使用 CSS3 动画和硬件加速，保证流畅性
• 🔄 条件渲染动画：为进入/退出的元素添加过渡效果
• 📋 列表过渡：为列表项的添加、删除、移动提供动画
• 🎯 手势识别：内置手势识别器，支持滑动、捏合等手势
• 🌐 全平台支持：支持 H5、App、小程序等全平台

📦 安装

使用 uni_modules 安装（推荐）

1. 在 HBuilderX 中右键项目根目录
2. 选择 "从插件市场导入插件"
3. 搜索 "hy-animation-plus"
4. 点击导入

手动安装

将 hy-animation-plus 文件夹复制到项目的 uni_modules 目录下。

🚀 快速开始

基础用法

1. 使用预设动画

<template>
  <hy-animation-plus animation="fadeIn" :config="{ duration: 500 }">
    <view class="content">淡入动画</view>
  </hy-animation-plus>
</template>

<script>
export default {
  data() {
    return {};
  }
};
</script>

2. 交互触发动画

<template>
  <hy-animation-plus 
    animation="bounce" 
    trigger="click"
    :auto-play="false"
  >
    <view class="button">点击我</view>
  </hy-animation-plus>
</template>

3. 链式动画

<template>
  <hy-animation-plus :chain="animationChain">
    <view class="content">链式动画</view>
  </hy-animation-plus>
</template>

<script>
export default {
  data() {
    return {
      animationChain: [
        { animation: 'fadeIn', config: { duration: 300 } },
        { animation: 'bounce', config: { duration: 500 } },
        { animation: 'pulse', config: { duration: 300 } }
      ]
    };
  }
};
</script>

4. 条件渲染动画

<template>
  <view>
    <button @click="show = !show">切换显示</button>
    <hy-animate-presence 
      :show="show"
      enter-animation="slideInRight"
      exit-animation="slideOutLeft"
    >
      <view class="content">条件渲染的内容</view>
    </hy-animate-presence>
  </view>
</template>

<script>
export default {
  data() {
    return {
      show: true
    };
  }
};
</script>

5. 列表过渡动画

<template>
  <hy-transition-group 
    :items="list"
    item-key="id"
    enter-animation="slideInUp"
    leave-animation="slideOutDown"
    :stagger="50"
  >
    <template v-slot="{ item, index }">
      <view class="list-item">{{ item.name }}</view>
    </template>
  </hy-transition-group>
</template>

<script>
export default {
  data() {
    return {
      list: [
        { id: 1, name: '项目 1' },
        { id: 2, name: '项目 2' },
        { id: 3, name: '项目 3' }
      ]
    };
  }
};
</script>

📚 组件文档

HyAnimationPlus 主动画组件

为元素添加动画效果的主要组件。

Props

Events

Methods

HyAnimatePresence 条件渲染动画组件

为条件渲染的元素添加进入和退出动画。

Props

Events

HyTransitionGroup 列表过渡动画组件

为列表项的添加、删除、移动提供过渡动画。

Props

Events

🎭 预设动画列表

淡入淡出动画

• fadeIn - 淡入
• fadeOut - 淡出

滑动动画

• slideInLeft - 从左滑入
• slideInRight - 从右滑入
• slideInUp - 从下滑入
• slideInDown - 从上滑入
• slideOutLeft - 向左滑出
• slideOutRight - 向右滑出
• slideOutUp - 向上滑出
• slideOutDown - 向下滑出

缩放动画

• zoomIn - 放大进入
• zoomOut - 缩小退出
• zoomInBounce - 弹跳放大进入
• zoomOutBounce - 弹跳缩小退出

旋转动画

• rotateIn - 旋转进入
• rotateOut - 旋转退出
• rotateInDownLeft - 左下旋转进入
• rotateInDownRight - 右下旋转进入
• rotateInUpLeft - 左上旋转进入
• rotateInUpRight - 右上旋转进入

翻转动画

• flipInX - X轴翻转进入
• flipInY - Y轴翻转进入
• flipOutX - X轴翻转退出
• flipOutY - Y轴翻转退出

弹跳动画

• bounceIn - 弹跳进入
• bounceOut - 弹跳退出
• bounce - 弹跳

注意力吸引动画

• shake - 摇晃
• swing - 摆动
• rubberBand - 橡皮筋
• pulse - 脉冲
• heartBeat - 心跳
• flash - 闪烁
• jello - 果冻
• headShake - 摇头

光速动画

• lightSpeedInRight - 光速从右进入
• lightSpeedInLeft - 光速从左进入
• lightSpeedOutRight - 光速向右退出
• lightSpeedOutLeft - 光速向左退出

滚动动画

• rollIn - 滚动进入
• rollOut - 滚动退出

后退动画

• backInDown - 后退从上进入
• backInUp - 后退从下进入
• backInLeft - 后退从左进入
• backInRight - 后退从右进入
• backOutDown - 后退向下退出
• backOutUp - 后退向上退出
• backOutLeft - 后退向左退出
• backOutRight - 后退向右退出

💡 进阶用法

使用 JS SDK

import { 
  createAnimation, 
  playAnimation, 
  playChainAnimation,
  getPresetAnimationNames 
} from '@/uni_modules/hy-animation-plus/js_sdk/index.js';

export default {
  methods: {
    // 创建动画实例
    startAnimation() {
      const element = this.$refs.myElement;
      const engine = createAnimation(element);
      engine.playPresetAnimation('bounce', { duration: 500 });
    },

    // 播放动画的便捷方法
    quickPlay() {
      const element = this.$refs.myElement;
      playAnimation(element, 'fadeIn', { duration: 300 });
    },

    // 播放链式动画
    async chainPlay() {
      const element = this.$refs.myElement;
      await playChainAnimation(element, [
        { animation: 'fadeIn' },
        { animation: 'bounce' },
        { animation: 'pulse' }
      ]);
      console.log('链式动画完成');
    },

    // 获取所有预设动画
    getAllAnimations() {
      const names = getPresetAnimationNames();
      console.log('所有预设动画:', names);
    }
  }
};

自定义动画

<template>
  <hy-animation-plus :animation="customAnimation">
    <view class="content">自定义动画</view>
  </hy-animation-plus>
</template>

<script>
export default {
  data() {
    return {
      customAnimation: {
        keyframes: [
          { transform: 'translateX(0) scale(1)', opacity: 0 },
          { transform: 'translateX(50px) scale(1.2)', opacity: 1 },
          { transform: 'translateX(0) scale(1)', opacity: 1 }
        ],
        config: {
          duration: 1000,
          easing: 'cubic-bezier(0.68, -0.55, 0.265, 1.55)',
          iterationCount: 1
        }
      }
    };
  }
};
</script>

手势识别

import { createGestureRecognizer } from '@/uni_modules/hy-animation-plus/js_sdk/index.js';

export default {
  mounted() {
    const element = this.$refs.gestureElement;
    const recognizer = createGestureRecognizer(element, {
      swipeThreshold: 50,
      swipeTimeout: 300
    });

    recognizer.on('swipeleft', (e) => {
      console.log('向左滑动');
    });

    recognizer.on('swiperight', (e) => {
      console.log('向右滑动');
    });
  }
};

🎨 动画配置选项

通用配置

{
  duration: 1000,        // 动画持续时间（毫秒）
  delay: 0,              // 延迟时间（毫秒）
  easing: 'ease-in-out', // 缓动函数
  iterationCount: 1,     // 迭代次数（1 或 'infinite'）
  direction: 'normal',   // 方向：'normal'、'reverse'、'alternate'、'alternate-reverse'
  fillMode: 'both'       // 填充模式：'none'、'forwards'、'backwards'、'both'
}

缓动函数

支持以下缓动函数：

• 标准：linear、ease、ease-in、ease-out、ease-in-out
• 二次方：easeInQuad、easeOutQuad、easeInOutQuad
• 三次方：easeInCubic、easeOutCubic、easeInOutCubic
• 四次方：easeInQuart、easeOutQuart、easeInOutQuart
• 五次方：easeInQuint、easeOutQuint、easeInOutQuint
• 指数：easeInExpo、easeOutExpo、easeInOutExpo
• 圆形：easeInCirc、easeOutCirc、easeInOutCirc
• 回弹：easeInBack、easeOutBack、easeInOutBack

📝 注意事项

1. 平台差异：nvue 页面部分动画效果与 vue 页面略有差异，建议在目标平台测试
2. 性能考虑：避免同时播放大量动画，可能影响性能
3. 动画叠加：多个动画同时作用于同一元素时，后者会覆盖前者
4. 硬件加速：使用 transform 和 opacity 属性可获得更好的性能
5. 条件编译：部分功能在小程序中可能受限，建议使用条件编译