# @douyinfe/semi-animation 中文文档

规范地址：https://npmcn.com/package/%40douyinfe/semi-animation/

版本：2\.105\.0
npm 元数据更新时间：2026-11-12T09:39:15.651Z
中文译文更新时间：2026-11-12T17:55:16.908Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40douyinfe/semi-animation
原文对照：https://npmcn.com/package/%40douyinfe/semi-animation/?lang=original
项目主页：https://github.com/DouyinFE/semi-design#readme
源码仓库：https://github.com/DouyinFE/semi-design

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：89.8 kB，73 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2021-10-25T14:53:36.044Z
- 最新版本发布：2026-11-12T09:39:15.465Z
- 近 30 天下载量：87380（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：590（近 12 个月 67 个）

## 中文简介

半自定义动画基础库

## 安装

```sh
npm install @douyinfe/semi-animation
```

也可以使用：`pnpm add @douyinfe/semi-animation`、`yarn add @douyinfe/semi-animation`、`bun add @douyinfe/semi-animation`

## README

> 提供基本的JS动画引擎:

-   根据内插模拟动画变化,性能更自然
-   支持界定各种放松功能
-   提供完整的生命周期钩和操作方法,允许开发者自由控制动画

## 安装

```sh
npm install @douyinfe/semi-animation
```

## 使用量

### 动画

`semi-animation` 提供名为 `Animation` . 它拥有完整的生命周期钩和控制方法,以支持音频和视频等操作动画.

-   用于联署材料

```js
import { Animation } from '@douyinfe/semi-animation';

const div = document.createElement('span');
div.style.display = 'inline-block';
document.body.appendChild(div);

const animation = new Animation({
    from: { value: 0 },
    to: { value: 1 },
});

animation.on('frame', props => {
    const num = props.value.toFixed(2);
    div.style.transform = `scale(${num})`;
    div.innerText = num;
});
```

-   在反应中使用

```jsx
import { Animation } from '@douyinfe/semi-animation';
import { Component } from 'react';

class App extends Component {
    constructor(props) {
        super(props);
        this.state = { value: 0 };

        this.animation = new Animation({
            from: { value: 0 },
            to: { value: 1 },
        });

        this.animation.on('frame', props => {
            this.setState({ value: props.value.toFixed(2) });
        });
    }

    componentDidMount() {
        this.animation.start();
    }

    componentWillUnmount() {
        this.animation.destroy();
    }

    render() {
        const { value } = this.state;

        return <div style={{ display: 'inline-block', transform: `scale(${value})` }}>{value}</div>;
    }
}
```

-   在 Vue 中使用

```html
<template>
    <div :style="{ transform: `scale(${value})`, display: 'inline-block' }">{{value}}</div>
</template>

<script>
    import { Animation } from '@douyinfe/semi-animation';

    export default {
        data() {
            return { value: 0 };
        },
        created() {
            this.animation = new Animation({
                from: { value: 0 },
                to: { value: 1 },
            });

            this.animation.on('frame', props => {
                this.value = props.value;
            });
        },
        mounted() {
            this.animation.start();
        },
        beforeDestroy() {
            this.animation.destroy();
        },
    };
</script>
```

显示结果 :

![](https://npmcn.com/package/%40douyinfe/semi-animation/docs/assets/img/semi-animation-demo-simple.gif)

### API 密码

```js
new Animation({ ...props }, { ...config });
```

**道具**

| Propa 名称 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| 从 | 对象 | Y |  | 初始状态 |
| 改为 | 对象 | Y |  | 终止状态 |

**配置**

| Propa 名称 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| 会期 | 数目 | 无 | 1 000个 | 动画持续时间. 如果通过此参数, 动画的放松功能将使用松动或线性函数, unit: ms |
| 放宽 | 函数 QQ 串 | 无 |  | 减轻动画功能. 如果持续时间没有通过,则默认使用弹簧松动功能. 如果持续时间参数被传入,则默认会使用线性宽松函数. 例如,收到的 `"cubic-bezier(.17,.67,.83,.67)"` 将会使动画帧更新按照此轻松功能进行 |
| 紧张 | 数目 | 无 | 170国 | 紧张,用于弹簧松动功能 |
| 摩擦 | 数目 | 无 | 页:1 | Friction,用于弹簧松动功能 |

**实例方法**

| 名称 | 参数 | 返回时 | 说明 |
| --- | --- | --- | --- |
| 开始 |  |  | 开始动画 |
| 暂停 |  |  | 暂停动画 挖掘后,您必须使用恢复方法继续播放,而不是使用开始 . |
| 恢复 |  |  | 继续动画 只有动画暂停时才有效果. |
| 倒转 |  |  | 倒转动画 |
| 停下来 |  |  | 停止动画。 只在动画重播、暂停和结束后产生效果 |
| 结束 |  |  | 立即终止动画,并将动画的最终状态值传递给回调方法 |
| 重设 |  |  | 重置动画 |
| 销毁 |  |  | 摧毁动画 |
| 获得初始状态 |  | 对象 | 获取初始状态 |
| 获取当前状态 |  | 对象 | 获取当前状态 |
| 获取最终状态 |  | 对象 | 获取最终状态 |
| 打开 | 事件Name:字符串, 事件Handler: 功能( 程序: 对象): 无效 |  | 绑定事件调用方法。 每个调用收到的参数是当前动画状态对象 . |

#### 支助活动

-   `start`: 动画开始时触发
-   `pause`:动画暂停时触发(当动画状态从播放变为暂停时触发事件,在其他情况下不会被触发)
-   `resume`: 当动画继续播放时触发( 当动画状态从暂停状态变为播放状态时触发事件, 而在其他情况下不会被触发)
-   `frame`: 动画框架更新时触发
-   `rest`: 当动画结束时触发( 当动画正常结束时事件会被触发)
-   `stop`: 动画停止时触发( 当实例停止方法调用时触发此事件)

开发者可以使用 `animation.on(eventName: string, cb: Function(currentStyle: object))` 以约束上述事件.

```jsx
import { Animation } from '@douyinfe/semi-animation';
// ...
const animation = new Animation(
    {
        from: { value1: 0, value2: 1 /* ... */ },
        to: { value1: 1, value2: 2 /* ... */ },
    },
    {
        duration: 1000, // After passing in duration, the default is linear interpolation
    }
);

animation.on('frame', currentState => {
    // currentState: is the state value object at the current moment
    // { value1: xxx, value2: xxx, ... }
});

// The callbacks such as start and pause are the same as the frame above, and the parameters are also the same.
animation.on('start', currentState => { /* ... */ });
animation.on('pause', currentState => { /* ... */ });
animation.on('resume', currentState => { /* ... */ });
animation.on('rest', currentState => { /* ... */ });
animation.on('stop', currentState => { /* ... */ });
```

## 许可证

麻省理工学院

## 常见问题

### @douyinfe/semi-animation 是什么？

半自定义动画基础库

### 如何安装 @douyinfe/semi-animation？

在项目目录运行 npm install @douyinfe/semi-animation，或使用 pnpm add / yarn add / bun add。

### @douyinfe/semi-animation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @douyinfe/semi-animation 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @douyinfe/semi-animation 可以商用吗？

@douyinfe/semi-animation 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @douyinfe/semi-animation 的下载量有多少？

根据 npm 官方下载统计，@douyinfe/semi-animation 在 2026/10/13 – 2026/11/11 这 30 天内被下载 87,380 次，日均约 2,913 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @douyinfe/semi-animation 还在维护吗？

最新版本 2\.105\.0 发布于 2026/11/12（1 天前）；至今共发布 590 个版本，其中过去 12 个月发布了 67 个；首次发布于 2021/10/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。