字节笔记本

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 + col

Props 参数

PropTypeDefaultDescription
sequence*number[][]-帧数组,每帧是要激活的点索引数组
colsnumber7网格列数
rowsnumber7网格行数
dotSizenumber8每个点的大小(像素)
gapnumber4点之间的间隙(像素)
intervalnumber100动画间隔(毫秒)
shape'rounded' | 'square' | 'circle''rounded'点的形状
colorstring'#10b981'激活状态的颜色
inactiveColorstring'rgba(16, 185, 129, 0.1)'未激活状态的颜色
activeDotStyleCSSProperties-激活点的额外样式

示例:加载动画

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 参数

PropTypeDefaultDescription
text*string-要显示和动画的文本
durationnumber300动画总时长(毫秒)
intervalnumber50字符更新间隔
charsstring'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'打乱使用的字符集
animatebooleantrue是否在文本变化时播放动画
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 参数

PropTypeDefaultDescription
items*DotFlowItem[]-包含标题和帧的项目数组
activeIndexnumber-受控的当前索引
autoPlaynumber-自动轮播间隔(毫秒)
direction'horizontal' \'vertical''horizontal'
spacingnumber16矩阵与文本之间的间距
matrixDotMatrixConfig-DotMatrix 组件的配置
scrambleScrambleTextConfig-ScrambleText 组件的配置
textSizenumber \string16
textColorstring-文本颜色
textWeightnumber \string500
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

项目链接

分享: