cos-design

55 个 React 视觉特效组件 · 活动页 / 品牌页 / 创意展示开箱即用

在线预览 · 快速开始 · v3.0 发布博客 · 完整指南 · 更新日志

这是什么？

cos-design 是一个面向视觉表达的 React 组件库——不是 Ant Design 的替代品，而是给页面加氛围、加趣味、加记忆点的「特效层」。

适合用在：

| 场景 | 你可以用它做什么 | | ------------ | ---------------------------------- | | 营销活动页 | 转盘抽奖、刮刮乐、红包雨、烟花庆祝 | | 品牌 Landing | 极光背景、霓虹标题、全息卡片 | | 数据大屏 | 翻牌器、仪表盘、液体进度环 | | 创意作品集 | 牛顿摆、DNA 螺旋、迷宫生成 |

15 个组件太单薄，55 个刚好组成一套完整的「视觉工具箱」。

快速开始

完整说明见 QUICKSTART.md · Playground 内访问 #/quickstart

安装

pnpm add cos-design

最简示例

import { Fireworks, ScrambleText, ScratchCard } from 'cos-design';

export default function Page() {
  return (
    <>
      <ScrambleText text="GRAND OPENING" />
      <ScratchCard prize="🎉 恭喜中奖！" />
      <Fireworks width={800} height={500} />
    </>
  );
}

无需手动引入 CSS，样式自动注入。完整 TypeScript 类型开箱即用。

使用注意（摘要）

| 注意点 | 说明 | | -------- | --------------------------------------------------------------- | | SSR | Canvas 组件需在 Next.js 等框架中 dynamic(..., { ssr: false }) | | 尺寸 | Canvas 组件需明确 width / height，父容器也应有可见高度 | | 密度 | 建议每页「一个强背景 + 若干局部交互」，避免多 Canvas 抢性能 | | 权限 | AudioVisualizer 开启麦克风时需 HTTPS 与用户授权 | | 省电 | 标签页隐藏时，多数 Canvas 动画自动暂停 |

组件一览（55 个 · 6 大分类）

| 组件 | 说明 | | ----------------- | ------------------------ | | MatrixRain | 黑客帝国数字雨 | | MeteorRain | 流星雨穿越 | | ParticleNetwork | 粒子连线网络（支持触摸） | | Aurora | 极光渐变光带 | | RippleWater | 点击水波纹 | | SmokeFog | 烟雾雾气飘动 | | CyberGrid | 赛博透视地面 | | Snowfall | 雪花 / 樱花飘落 | | Starfield | 3D 纵深星空 |

| 组件 | 说明 | | -------------- | ------------ | | Typewriter | 终端打字机 | | NeonText | 霓虹发光字 | | GlitchText | 故障风闪烁 | | ScrambleText | 乱码解密文字 | | SplitReveal | 字母分裂入场 | | WaveText | 正弦波浪文字 | | GradientFlow | 流光渐变字 | | BurnAway | 燃烧消失 | | BarcodeScan | 扫描线覆盖 |

| 组件 | 说明 | | ----------------- | ------------ | | WaveButton | 水波扩散按钮 | | Spotlight | 手电筒照亮 | | MagneticButton | 磁吸按钮 | | HolographicCard | 全息反光卡片 | | ClickSpark | 点击火花 | | CursorTrail | 光标拖尾 | | LiquidGlass | 液态毛玻璃 |

| 组件 | 说明 | | --------------- | ------------ | | Turntable | 抽奖转盘 | | Confetti | 彩纸喷射庆祝 | | Charge | 充电动效 | | ScratchCard | 刮刮乐 | | SlotMachine | 老虎机 | | DiceRoll | 3D 掷骰子 | | RedPacketRain | 红包雨 | | ProgressChest | 宝箱进度 | | RadarScan | 雷达扫描 HUD |

| 组件 | 说明 | | ----------------- | --------------- | | CanvasClock | Canvas 模拟时钟 | | FlipCounter | 机械翻牌数字 | | Countdown | 活动倒计时 | | LiquidProgress | 液体进度环 | | AudioVisualizer | 音频可视化 | | Speedometer | 速度仪表盘 | | TimelinePulse | 时间轴脉冲 | | OrbitalChart | 轨道占比图 |

| 组件 | 说明 | | ----------------- | ------------ | | Fireworks | 烟花燃放 | | ReturnCity | 回城传送特效 | | NewtonCradle | 牛顿摆 | | GravityBalls | 重力球池 | | DnaHelix | DNA 双螺旋 | | ElectricArc | 电弧闪电 | | MazeGenerator | 迷宫生成器 | | DoublePendulum | 双摆混沌轨迹 | | PlasmaBall | 等离子静电球 | | MetaballPool | 液态融合球 | | SolarSystem | 太阳系公转 | | LorenzAttractor | 洛伦兹吸引子 | | RopeChain | 绳索链条摆动 |

特性

• 55 个组件，覆盖背景、文字、交互、营销、数据、物理六大场景
• React 19 + Vite 8 + TypeScript 5 现代技术栈
• ESM / CJS 双格式，完整 .d.ts 类型
• 样式自动注入，无需 import 'cos-design/dist/index.css'
• Canvas 组件页面隐藏时自动暂停动画，省电友好
• GitHub Actions 自动 lint、构建、npm 发布

本地开发

要求 Node.js >= 20（推荐 Node 22，项目含 .nvmrc）

git clone [email protected]:jiaxiantao/cos-design.git
cd cos-design
nvm use
npm run setup          # 安装依赖（绕过 corepack 问题）
npx --yes pnpm@9 dev   # 启动 Playground

访问 http://localhost:4000 — 按分类浏览全部 55 个组件，右侧可查看与复制示例代码。

常用命令

| 命令 | 说明 | | ------------------------ | -------------- | | npm run setup | 安装依赖 | | npx --yes pnpm@9 dev | 启动本地演示 | | npx --yes pnpm@9 build | 构建组件库 | | npx --yes pnpm@9 lint | 代码检查 | | npx --yes pnpm@9 pub | 构建并发布 npm |

使用注意

详见 QUICKSTART.md。以下为高频场景摘要：

Canvas 组件请客户端渲染（依赖 window / canvas / requestAnimationFrame）：

import dynamic from 'next/dynamic';

const Fireworks = dynamic(() => import('cos-design').then((m) => m.Fireworks), { ssr: false });

控制使用密度 — 一个页面建议「一个强视觉背景 + 若干局部交互」，避免全场动画互相抢戏。

文档

| 文档 | 内容 | | ----------------------------------------------------------- | -------------------------------- | | 快速开始 | 安装、用法、注意事项与常见问题 | | v3.0 发布博客 | 重大升级解读、分类体系、技术实现 | | 完整介绍与实践指南 | 架构、使用规则、组件详解 | | CHANGELOG | 版本更新记录 | | CONTRIBUTING | 参与贡献指南 |

自动发布

推送到 master 后，GitHub Actions 自动 lint、构建，并将新版本发布到 npm。

首次配置需在 GitHub Secrets 中设置 NPM_TOKEN（需勾选 Bypass 2FA for publish）。详见 npm Access Tokens。

参与贡献

欢迎提交 Issue 与 Pull Request！

如果觉得有用，欢迎 Star ⭐

MIT © jiaxiantao