# ohos_view_animations

**Repository Path**: miosas/ohos_view_animations

## Basic Information

- **Project Name**: ohos_view_animations
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-08
- **Last Updated**: 2026-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# view_animations

## 简介

view_animations 是一个 OpenHarmony 视图动画库，提供了丰富多样的动画效果。该库灵感来源于 Animate.css，为 OpenHarmony 开发者提供优雅、易用的动画效果，支持通过流式 API 轻松实现各种视图动画。

该库提供 63 种预定义动画效果，包括注意力效果、弹跳效果、淡入淡出、翻转、旋转、滑动、缩放等，支持自定义动画时长、延迟、重复次数、插值器等参数，可扩展性强，支持自定义动画效果。

## 效果展示

![效果展示](./resource/demo.gif)

## 下载安装

```bash
ohpm install @ohos/view_animations
```

OpenHarmony ohpm 环境配置等更多内容，请参考[如何安装 OpenHarmony ohpm 包](https://gitcode.com/openharmony-tpc/docs/blob/master/OpenHarmony_har_usage.md)。

## 约束与限制

### 兼容性

- DevEco Studio: 6.0.2(22), SDK: API 12 Release(5.0.0.71), ROM: 5.0.0.71+

### 权限要求

无

## 使用示例

以下示例展示了如何使用 view_animations 库在组件上播放抖动动画：

```typescript
import { YoYo, Techniques, YoYoAttributeModifier } from '@ohos/view_animations'

@Entry
@Component
struct Example {
  @State yoYoAttributeModifier: YoYoAttributeModifier = new YoYoAttributeModifier(this.getUIContext())

  build() {
    Column() {
      Text('Hello World')
        .fontSize(42)
        .attributeModifier(this.yoYoAttributeModifier)
        .onClick(() => {
          YoYo.with(Techniques.Shake)
            .duration(700)
            .playOn(this.yoYoAttributeModifier.target)
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}
```

## 使用说明

### 基本使用

使用 YoYoAttributeModifier 创建动画目标，通过 YoYo 类的流式 API 配置并播放动画：

```typescript
import { YoYo, Techniques, YoYoAttributeModifier } from '@ohos/view_animations'

@Entry
@Component
struct BasicExample {
  @State modifier: YoYoAttributeModifier = new YoYoAttributeModifier(this.getUIContext())

  build() {
    Column() {
      Text('Click me')
        .fontSize(24)
        .attributeModifier(this.modifier)
        .onClick(() => {
          YoYo.with(Techniques.Tada)
            .duration(1000)
            .playOn(this.modifier.target)
        })
    }
  }
}
```

### 配置动画参数

支持配置动画时长、延迟、重复次数、插值器、锚点等参数：

```typescript
YoYo.with(Techniques.FadeIn)
  .duration(1500)
  .delay(200)
  .repeat(3)
  .interpolate(Curve.EaseInOut)
  .pivot('50%', '50%')
  .playOn(this.modifier.target)
```

### 重复模式

支持两种重复模式：RESTART（重新开始）和 REVERSE（反向播放）：

```typescript
import { AnimationRepeatMode } from '@ohos/view_animations'

YoYo.with(Techniques.Pulse)
  .repeat(5)
  .repeatMode(AnimationRepeatMode.REVERSE)
  .playOn(this.modifier.target)
```

### 动画事件监听

支持监听动画的开始、结束、取消、重复事件：

```typescript
YoYo.with(Techniques.Bounce)
  .duration(800)
  .withListener({
    onAnimationStart: () => {
      console.info('Animation started')
    },
    onAnimationEnd: () => {
      console.info('Animation ended')
    },
    onAnimationCancel: () => {
      console.info('Animation cancelled')
    },
    onAnimationRepeat: () => {
      console.info('Animation repeated')
    }
  })
  .playOn(this.modifier.target)
```

### 控制动画

使用 YoYoString 对象控制动画的播放状态：

```typescript
@Entry
@Component
struct ControlExample {
  @State modifier: YoYoAttributeModifier = new YoYoAttributeModifier(this.getUIContext())
  private yoYoString: YoYoString | undefined = undefined

  build() {
    Column() {
      Text('Animation Target')
        .attributeModifier(this.modifier)

      Button('Play')
        .onClick(() => {
          this.yoYoString = YoYo.with(Techniques.Shake)
            .duration(700)
            .playOn(this.modifier.target)
        })

      Button('Stop')
        .onClick(() => {
          this.yoYoString?.stop()
        })

      Button('Check Status')
        .onClick(() => {
          console.info('Is running: ' + this.yoYoString?.isRunning())
          console.info('Is started: ' + this.yoYoString?.isStarted())
        })
    }
  }
}
```

### 自定义动画

继承 BaseViewAnimator 创建自定义动画效果：

```typescript
import { BaseViewAnimator, KeyframeStep, KeyframeTarget } from '@ohos/view_animations'

class MyCustomAnimator extends BaseViewAnimator {
  protected prepare(_target: KeyframeTarget): KeyframeStep[] {
    return [
      { fraction: 0.0, values: { opacity: 1, scaleX: 1, scaleY: 1 } },
      { fraction: 0.5, values: { opacity: 0.5, scaleX: 1.2, scaleY: 1.2 } },
      { fraction: 1.0, values: { opacity: 1, scaleX: 1, scaleY: 1 } }
    ]
  }
}

YoYo.with(new MyCustomAnimator())
  .duration(1000)
  .playOn(this.modifier.target)
```

## 接口说明

### API

| 名称 | 描述 | 类型 | 参数 | 返回值 | 必填 | OpenHarmony平台支持 |
|-----|-----|------|------|--------|------|-----------------|
| YoYo.with | 创建动画构建器 | 方法 | Techniques 或 BaseViewAnimator | AnimationComposer | 是 | 是 |
| AnimationComposer.duration | 设置动画时长 | 方法 | duration: number | AnimationComposer | 否 | 是 |
| AnimationComposer.delay | 设置动画延迟 | 方法 | delay: number | AnimationComposer | 否 | 是 |
| AnimationComposer.repeat | 设置重复次数 | 方法 | times: number | AnimationComposer | 否 | 是 |
| AnimationComposer.repeatMode | 设置重复模式 | 方法 | mode: AnimationRepeatMode | AnimationComposer | 否 | 是 |
| AnimationComposer.interpolate | 设置插值器 | 方法 | curve: string \| Curve \| ICurve | AnimationComposer | 否 | 是 |
| AnimationComposer.pivot | 设置锚点 | 方法 | x: number \| string, y: number \| string | AnimationComposer | 否 | 是 |
| AnimationComposer.withListener | 添加动画监听器 | 方法 | listener: AnimatorListener | AnimationComposer | 否 | 是 |
| AnimationComposer.playOn | 在目标上播放动画 | 方法 | target: KeyframeTarget | YoYoString | 是 | 是 |
| YoYoString.stop | 停止动画 | 方法 | reset?: boolean | void | 否 | 是 |
| YoYoString.isRunning | 是否正在运行 | 方法 | 无 | boolean | - | 是 |
| YoYoString.isStarted | 是否已开始 | 方法 | 无 | boolean | - | 是 |
| YoYoAttributeModifier | 属性修改器 | 类 | context: UIContext | YoYoAttributeModifier | 是 | 是 |
| YoYoAttributeModifier.target | 获取动画目标 | 属性 | 无 | BindTarget | - | 是 |
| BaseViewAnimator | 动画基类 | 抽象类 | 无 | BaseViewAnimator | - | 是 |
| BaseViewAnimator.setDuration | 设置动画时长 | 方法 | duration: number | BaseViewAnimator | 否 | 是 |
| BaseViewAnimator.setStartDelay | 设置延迟 | 方法 | delay: number | BaseViewAnimator | 否 | 是 |
| BaseViewAnimator.setRepeatTimes | 设置重复次数 | 方法 | times: number | BaseViewAnimator | 否 | 是 |
| BaseViewAnimator.setRepeatMode | 设置重复模式 | 方法 | mode: number | BaseViewAnimator | 否 | 是 |
| BaseViewAnimator.setInterpolator | 设置插值器 | 方法 | curve: string \| Curve \| ICurve | BaseViewAnimator | 否 | 是 |
| BaseViewAnimator.start | 开始动画 | 方法 | 无 | void | - | 是 |
| BaseViewAnimator.animate | 开始动画 | 方法 | 无 | void | - | 是 |
| BaseViewAnimator.isRunning | 是否正在运行 | 方法 | 无 | boolean | - | 是 |
| BaseViewAnimator.isStarted | 是否已开始 | 方法 | 无 | boolean | - | 是 |

### 枚举

#### Techniques

动画效果枚举，定义了所有可用的动画效果：

| 分类 | 动画效果 |
|------|---------|
| 注意力效果 | Flash, Pulse, RubberBand, Shake, Swing, Wobble, Bounce, Tada, StandUp, Wave |
| 特殊效果 | Hinge, RollIn, RollOut, DropOut, Landing, TakingOff |
| 弹跳进入 | BounceIn, BounceInDown, BounceInLeft, BounceInRight, BounceInUp |
| 淡入效果 | FadeIn, FadeInUp, FadeInDown, FadeInLeft, FadeInRight |
| 淡出效果 | FadeOut, FadeOutDown, FadeOutLeft, FadeOutRight, FadeOutUp |
| 翻转效果 | FlipInX, FlipInY, FlipOutX, FlipOutY |
| 旋转进入 | RotateIn, RotateInDownLeft, RotateInDownRight, RotateInUpLeft, RotateInUpRight |
| 旋转退出 | RotateOut, RotateOutDownLeft, RotateOutDownRight, RotateOutUpLeft, RotateOutUpRight |
| 滑动进入 | SlideInLeft, SlideInRight, SlideInUp, SlideInDown |
| 滑动退出 | SlideOutLeft, SlideOutRight, SlideOutUp, SlideOutDown |
| 缩放进入 | ZoomIn, ZoomInDown, ZoomInLeft, ZoomInRight, ZoomInUp |
| 缩放退出 | ZoomOut, ZoomOutDown, ZoomOutLeft, ZoomOutRight, ZoomOutUp |

#### AnimationRepeatMode

动画重复模式枚举：

| 名称 | 值 | 描述 |
|------|-----|------|
| RESTART | 0 | 重新开始 |
| REVERSE | 1 | 反向播放 |

### 接口类型

#### AnimatorListener

动画监听器接口：

| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| onAnimationStart | () => void | 否 | 动画开始回调 |
| onAnimationEnd | () => void | 否 | 动画结束回调 |
| onAnimationCancel | () => void | 否 | 动画取消回调 |
| onAnimationRepeat | () => void | 否 | 动画重复回调 |

#### AnimValues

动画值接口：

| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| opacity | number | 是 | 透明度 |
| translateX | number | 是 | X 轴平移 |
| translateY | number | 是 | Y 轴平移 |
| scaleX | number | 是 | X 轴缩放 |
| scaleY | number | 是 | Y 轴缩放 |
| rotate | number | 是 | 旋转角度 |
| rotateX | number | 是 | X 轴旋转角度 |
| rotateY | number | 是 | Y 轴旋转角度 |
| startVector | StartVector | 是 | 旋转向量 |

#### KeyframeStep

关键帧步骤接口：

| 字段名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| fraction | number | 是 | 关键帧位置（0.0-1.0） |
| values | Partial\<AnimValues\> | 是 | 关键帧值 |

#### AnimRunOptions

动画运行选项接口：

| 字段名 | 类型 | 必填 | 默认值 | 描述 |
|--------|------|------|--------|------|
| duration | number | 是 | 1000 | 动画时长（毫秒） |
| delay | number | 是 | 0 | 动画延迟（毫秒） |
| iterations | number | 是 | 1 | 重复次数，-1 表示无限循环 |
| playMode | number | 是 | 0 | 播放模式 |
| curve | string \| Curve \| ICurve | 是 | 0 | 插值器 |
| pivotXValue | number \| string | 是 | '50%' | X 轴锚点 |
| pivotYValue | number \| string | 是 | '50%' | Y 轴锚点 |

## 关于混淆

在项目混淆规则配置文件 `obfuscation-rules.txt` 中添加：

```
-keep-file-name
index
Index
```

## 目录结构

```
ohos_view_animations/
├── entry/                    # 示例应用模块
│   └── src/main/ets/
│       └── pages/            # 示例页面
├── library/                  # 核心库模块
│   ├── Index.ets             # 库入口文件
│   └── src/main/ets/
│       ├── animation/        # 动画效果实现
│       │   ├── attention/    # 注意力效果
│       │   ├── bouncingEntrances/  # 弹跳进入
│       │   ├── fadingEntrances/    # 淡入效果
│       │   ├── fadingExits/        # 淡出效果
│       │   ├── flippers/           # 翻转效果
│       │   ├── rotatingEntrances/  # 旋转进入
│       │   ├── rotatingExits/      # 旋转退出
│       │   ├── sliders/            # 滑动效果
│       │   ├── specials/           # 特殊效果
│       │   ├── zoomingEntrances/   # 缩放进入
│       │   └── zoomingExits/       # 缩放退出
│       ├── models/           # 数据模型
│       ├── BaseViewAnimator.ets    # 动画基类
│       ├── ViewKeyframeAnimation.ets  # 关键帧动画
│       ├── YoYoAttributeModifier.ets  # 属性修改器
│       └── interface.ets     # 接口定义
├── build-profile.json5       # 构建配置
└── oh-package.json5          # 包配置
```

## 贡献代码

使用过程中发现任何问题都可以提 [Issue](https://gitcode.com/openharmony-tpc/ohos_view_animations/issues) 给我们，当然，我们也非常欢迎你发来 [PR](https://gitcode.com/openharmony-tpc/ohos_view_animations/pulls) 。

## 开源协议

本项目基于 [MIT License](https://gitcode.com/openharmony-tpc/ohos_view_animations/blob/master/LICENSE) ，请自由地享受和参与开源。