字
字节笔记本
2026年2月22日
dot-anime-react:轻量级 React 点阵动画库
dot-anime-react 是一个轻量级的 React 动画库,专门用于创建点阵矩阵动画效果。它提供了简洁的声明式 API,零依赖,仅 3KB 压缩后大小,并且完全支持 TypeScript。
项目简介
dot-anime-react 由 IveTian 开发维护,旨在为 React 应用添加微妙而引人入胜的点阵动画效果。该库采用纯 React 实现,无需任何外部依赖,非常适合用于加载动画、状态指示器和装饰性动画。
核心特性
- 零依赖: 纯 React 实现,无外部依赖
- TypeScript 支持: 内置完整的类型定义
- 轻量级: 仅 3KB gzipped,不会增加包体积负担
- 高度可定制: 丰富的属性选项支持深度自定义
- 高性能: 针对 60fps 流畅动画优化
安装
bash
npm install dot-anime-react核心组件
DotMatrix
DotMatrix 是核心的点阵矩阵动画组件,通过定义网格和帧序列来创建动画。
基本用法
tsx
import { DotMatrix } from "dot-anime-react";
const sequence = [
[24], // 中心点
[17, 23, 25, 31], // 十字图案
[10, 16, 18, 24, 30, 32, 38], // 扩展图案
];
<DotMatrix
sequence={sequence}
cols={7}
rows={7}
dotSize={10}
gap={5}
interval={120}
color="#34d399"
/>网格索引系统
理解网格索引系统对于创建动画至关重要:
text
7×7 Grid Index Layout:
0 1 2 3 4 5 6
7 8 9 10 11 12 13
14 15 16 17 18 19 20
21 22 23 [24] 25 26 27 <- center
28 29 30 31 32 33 34
35 36 37 38 39 40 41
42 43 44 45 46 47 48
Formula: index = row × cols + colProps 参数
| Prop | Type | Default | Description |
|---|---|---|---|
| sequence* | number[][] | - | 帧数组,每帧是要激活的点索引数组 |
| cols | number | 7 | 网格列数 |
| rows | number | 7 | 网格行数 |
| dotSize | number | 8 | 每个点的大小(像素) |
| gap | number | 4 | 点之间的间隙(像素) |
| interval | number | 100 | 动画间隔(毫秒) |
| shape | 'rounded' | 'square' | 'circle' | 'rounded' | 点的形状 |
| color | string | '#10b981' | 激活状态的颜色 |
| inactiveColor | string | 'rgba(16, 185, 129, 0.1)' | 未激活状态的颜色 |
| activeDotStyle | CSSProperties | - | 激活点的额外样式 |
示例:加载动画
tsx
const loadingSequence = [
[21, 22, 23],
[22, 23, 24],
[23, 24, 25],
[24, 25, 26],
[25, 26, 27],
[24, 25, 26],
[23, 24, 25],
[22, 23, 24],
];
<DotMatrix
sequence={loadingSequence}
cols={7}
rows={7}
interval={100}
/>发光效果
tsx
<DotMatrix
sequence={sequence}
color="#34d399"
activeDotStyle={{
boxShadow: "0 0 10px #34d39980",
}}
/>ScrambleText
ScrambleText 组件创建文本打乱/解码动画效果,当文本内容变化时触发。
基本用法
tsx
import { ScrambleText } from "dot-anime-react";
<ScrambleText
text="Hello World"
duration={400}
interval={30}
/>Props 参数
| Prop | Type | Default | Description |
|---|---|---|---|
| text* | string | - | 要显示和动画的文本 |
| duration | number | 300 | 动画总时长(毫秒) |
| interval | number | 50 | 字符更新间隔 |
| chars | string | 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789' | 打乱使用的字符集 |
| animate | boolean | true | 是否在文本变化时播放动画 |
| onComplete | () => void | - | 动画完成时的回调 |
自定义打乱字符
tsx
// 二进制风格
<ScrambleText text="Loading..." chars="01" />
// 符号风格
<ScrambleText text="Processing" chars="!@#$%^&*()_+-=[]{}|;:,.<>?" />
// 日文片假名
<ScrambleText text="アニメーション" chars="アイウエオカキクケコサシスセソタチツテト" />受控动画
tsx
import { useState } from "react";
function ControlledScramble() {
const [text, setText] = useState("Initial");
return (
<div>
<ScrambleText text={text} />
<button onClick={() => setText("Updated!")}>
Change Text
</button>
</div>
);
}DotFlow
DotFlow 是一个复合组件,结合 DotMatrix 和 ScrambleText 创建流动的多项目动画,支持自动轮播。
基本用法
tsx
import { DotFlow } from "dot-anime-react";
const items = [
{
title: "Loading",
frames: [[24], [17, 23, 25, 31], [24]],
},
{
title: "Processing",
frames: [[21, 22, 23], [22, 23, 24], [23, 24, 25]],
},
{
title: "Complete",
frames: [[16, 18, 30, 32], [24]],
},
];
<DotFlow
items={items}
autoPlay={2000}
direction="horizontal"
/>DotFlowItem 类型
tsx
interface DotFlowItem {
title: string; // 显示的文本
frames: number[][]; // 该项目的动画帧
}Props 参数
| Prop | Type | Default | Description |
|---|---|---|---|
| items* | DotFlowItem[] | - | 包含标题和帧的项目数组 |
| activeIndex | number | - | 受控的当前索引 |
| autoPlay | number | - | 自动轮播间隔(毫秒) |
| direction | 'horizontal' \ | 'vertical' | 'horizontal' |
| spacing | number | 16 | 矩阵与文本之间的间距 |
| matrix | DotMatrixConfig | - | DotMatrix 组件的配置 |
| scramble | ScrambleTextConfig | - | ScrambleText 组件的配置 |
| textSize | number \ | string | 16 |
| textColor | string | - | 文本颜色 |
| textWeight | number \ | string | 500 |
| onChange | (index: number) => void | - | 当前索引变化时的回调 |
垂直布局
tsx
<DotFlow
items={items}
direction="vertical"
spacing={12}
/>自定义矩阵配置
tsx
<DotFlow
items={items}
matrix={{
cols: 5,
rows: 5,
dotSize: 6,
gap: 3,
color: "#60a5fa",
inactiveColor: "#60a5fa20",
}}
/>受控模式
tsx
import { useState } from "react";
function ControlledDotFlow() {
const [index, setIndex] = useState(0);
return (
<div>
<DotFlow
items={items}
activeIndex={index}
onChange={setIndex}
/>
<div>
{items.map((_, i) => (
<button key={i} onClick={() => setIndex(i)}>
{i + 1}
</button>
))}
</div>
</div>
);
}Playground 交互 playground
dot-anime-react 提供了在线 Playground,可以实时调整参数预览效果:
- 调整网格大小(行列数)
- 修改点的大小和间隙
- 选择不同的形状(圆角、方形、圆形)
- 设置动画间隔
- 选择预设动画序列(脉冲、加载、螺旋、波浪、心跳)
- 切换颜色主题
- 开启/关闭发光效果
- 实时生成代码
访问地址: https://dotanime.dev/playground
项目链接
- 官方网站: https://dotanime.dev
- GitHub 仓库: https://github.com/IveTian/dot-anime-react
- NPM 包: https://www.npmjs.com/package/dot-anime-react
- 在线文档: https://dotanime.dev/docs
分享: