cos-design 3.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [3.0.1] - 2026-06-22
9
+
10
+ ### Fixed
11
+
12
+ - `ScratchCard` 修复 HiDPI 屏幕下刮开进度检测不准确
13
+ - `SlotMachine` 修复开奖符号与中间行不对齐;合并为单 rAF 循环;卸载时取消动画
14
+ - `AudioVisualizer` 修复组件卸载时麦克风流未释放
15
+ - `OrbitalChart` 中心标签改为显示占比最大的数据项
16
+ - `DiceRoll` 修复卸载时 `setTimeout` 未清理
17
+ - `BurnAway` / `Turntable` 修复卸载后仍触发回调的问题
18
+ - `RedPacketRain` 修复结束时动画循环被意外重启
19
+ - `TimelinePulse` 修复轴线与圆点垂直不对齐
20
+ - `NewtonCradle` 修复摆动不符合动量守恒的视觉问题
21
+
22
+ ### Changed
23
+
24
+ - `CanvasClock`、`LiquidProgress` 页面隐藏时暂停动画循环
25
+ - 优化 `README.md` 排版与组件分类展示
26
+
8
27
  ## [3.0.0] - 2026-06-18
9
28
 
10
29
  ### Added
@@ -127,6 +146,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
127
146
  - Webpack 及相关 loader 依赖
128
147
  - UMD 格式产物
129
148
 
149
+ [3.0.1]: https://github.com/jiaxiantao/cos-design/compare/v3.0.0...v3.0.1
130
150
  [3.0.0]: https://github.com/jiaxiantao/cos-design/compare/v2.4.1...v3.0.0
131
151
  [2.4.1]: https://github.com/jiaxiantao/cos-design/compare/v2.4.0...v2.4.1
132
152
  [2.4.0]: https://github.com/jiaxiantao/cos-design/compare/v2.3.0...v2.4.0
package/README.md CHANGED
@@ -1,158 +1,257 @@
1
+ <div align="center">
2
+
1
3
  # cos-design
2
4
 
5
+ **49 个 React 视觉特效组件 · 活动页 / 品牌页 / 创意展示开箱即用**
6
+
3
7
  [![CI](https://github.com/jiaxiantao/cos-design/actions/workflows/ci.yml/badge.svg)](https://github.com/jiaxiantao/cos-design/actions/workflows/ci.yml)
4
8
  [![npm version](https://img.shields.io/npm/v/cos-design.svg)](https://www.npmjs.com/package/cos-design)
5
9
  [![license](https://img.shields.io/npm/l/cos-design.svg)](https://github.com/jiaxiantao/cos-design/blob/main/LICENSE)
10
+ [![React](https://img.shields.io/badge/React-19-61dafb)](https://react.dev/)
11
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6)](https://www.typescriptlang.org/)
6
12
 
7
- 基于 React 19 + Vite 8 + TypeScript 5 的 React 组件库。
13
+ [在线预览](https://github.com/jiaxiantao/cos-design#本地开发) · [v3.0 发布博客](./docs/cos-design-v3-release.md) · [完整指南](./docs/cos-design-intro.md) · [更新日志](./CHANGELOG.md)
8
14
 
9
- ## 特性
15
+ </div>
16
+
17
+ ---
18
+
19
+ ## 这是什么?
20
+
21
+ **cos-design** 是一个面向**视觉表达**的 React 组件库——不是 Ant Design 的替代品,而是给页面加氛围、加趣味、加记忆点的「特效层」。
22
+
23
+ 适合用在:
24
+
25
+ | 场景 | 你可以用它做什么 |
26
+ | ------------ | ---------------------------------- |
27
+ | 营销活动页 | 转盘抽奖、刮刮乐、红包雨、烟花庆祝 |
28
+ | 品牌 Landing | 极光背景、霓虹标题、全息卡片 |
29
+ | 数据大屏 | 翻牌器、仪表盘、液体进度环 |
30
+ | 创意作品集 | 牛顿摆、DNA 螺旋、迷宫生成 |
31
+
32
+ > 15 个组件太单薄,49 个刚好组成一套完整的「视觉工具箱」。
10
33
 
11
- - 开箱即用的 React 组件
12
- - ESM / CJS 双格式输出,完整 TypeScript 类型支持
13
- - 样式自动注入,无需手动引入 CSS
14
- - 使用 pnpm + Vite 的现代工程化方案
34
+ ---
15
35
 
16
- ## 安装
36
+ ## 30 秒上手
17
37
 
18
38
  ```bash
19
39
  pnpm add cos-design
20
- # or
21
- npm install cos-design
22
- # or
23
- yarn add cos-design
24
40
  ```
25
41
 
26
- ## 使用
27
-
28
42
  ```tsx
29
- import { CanvasClock, Charge, ReturnCity, Turntable } from 'cos-design';
30
-
31
- function App() {
32
- return <CanvasClock width={400} height={400} />;
43
+ import { Fireworks, ScrambleText, ScratchCard } from 'cos-design';
44
+
45
+ export default function Page() {
46
+ return (
47
+ <>
48
+ <ScrambleText text="GRAND OPENING" />
49
+ <ScratchCard prize="🎉 恭喜中奖!" />
50
+ <Fireworks width={800} height={500} />
51
+ </>
52
+ );
33
53
  }
34
54
  ```
35
55
 
36
- ## 组件(49 个 · 6 大分类)
56
+ 无需手动引入 CSS,样式自动注入。完整 TypeScript 类型开箱即用。
37
57
 
38
- ### 背景氛围
58
+ ---
39
59
 
40
- `MatrixRain` · `MeteorRain` · `ParticleNetwork` · `Aurora` · `RippleWater` · `SmokeFog` · `CyberGrid` · `Snowfall` · `Starfield`
60
+ ## 组件一览(49 个 · 6 大分类)
41
61
 
42
- ### 文字动效
62
+ <details open>
63
+ <summary><strong>背景氛围</strong> — 9 个 · 动态场景与粒子背景</summary>
64
+
65
+ <br>
66
+
67
+ | 组件 | 说明 |
68
+ | ----------------- | ------------------------ |
69
+ | `MatrixRain` | 黑客帝国数字雨 |
70
+ | `MeteorRain` | 流星雨穿越 |
71
+ | `ParticleNetwork` | 粒子连线网络(支持触摸) |
72
+ | `Aurora` | 极光渐变光带 |
73
+ | `RippleWater` | 点击水波纹 |
74
+ | `SmokeFog` | 烟雾雾气飘动 |
75
+ | `CyberGrid` | 赛博透视地面 |
76
+ | `Snowfall` | 雪花 / 樱花飘落 |
77
+ | `Starfield` | 3D 纵深星空 |
43
78
 
44
- `Typewriter` · `NeonText` · `GlitchText` · `ScrambleText` · `SplitReveal` · `WaveText` · `GradientFlow` · `BurnAway` · `BarcodeScan`
79
+ </details>
45
80
 
46
- ### 交互玩具
81
+ <details>
82
+ <summary><strong>文字动效</strong> — 9 个 · 标题与 Banner 动画</summary>
47
83
 
48
- `WaveButton` · `Spotlight` · `MagneticButton` · `HolographicCard` · `ClickSpark` · `CursorTrail` · `LiquidGlass`
84
+ <br>
49
85
 
50
- ### 游戏营销
86
+ | 组件 | 说明 |
87
+ | -------------- | ------------ |
88
+ | `Typewriter` | 终端打字机 |
89
+ | `NeonText` | 霓虹发光字 |
90
+ | `GlitchText` | 故障风闪烁 |
91
+ | `ScrambleText` | 乱码解密文字 |
92
+ | `SplitReveal` | 字母分裂入场 |
93
+ | `WaveText` | 正弦波浪文字 |
94
+ | `GradientFlow` | 流光渐变字 |
95
+ | `BurnAway` | 燃烧消失 |
96
+ | `BarcodeScan` | 扫描线覆盖 |
51
97
 
52
- `Turntable` · `Confetti` · `Charge` · `ScratchCard` · `SlotMachine` · `DiceRoll` · `RedPacketRain` · `ProgressChest` · `RadarScan`
98
+ </details>
53
99
 
54
- ### 数据装饰
100
+ <details>
101
+ <summary><strong>交互玩具</strong> — 7 个 · 鼠标驱动的趣味反馈</summary>
55
102
 
56
- `CanvasClock` · `FlipCounter` · `Countdown` · `LiquidProgress` · `AudioVisualizer` · `Speedometer` · `TimelinePulse` · `OrbitalChart`
103
+ <br>
57
104
 
58
- ### 物理创意
105
+ | 组件 | 说明 |
106
+ | ----------------- | ------------ |
107
+ | `WaveButton` | 水波扩散按钮 |
108
+ | `Spotlight` | 手电筒照亮 |
109
+ | `MagneticButton` | 磁吸按钮 |
110
+ | `HolographicCard` | 全息反光卡片 |
111
+ | `ClickSpark` | 点击火花 |
112
+ | `CursorTrail` | 光标拖尾 |
113
+ | `LiquidGlass` | 液态毛玻璃 |
59
114
 
60
- `Fireworks` · `ReturnCity` · `NewtonCradle` · `GravityBalls` · `DnaHelix` · `ElectricArc` · `MazeGenerator`
115
+ </details>
61
116
 
62
- ## 本地开发
117
+ <details>
118
+ <summary><strong>游戏营销</strong> — 9 个 · 抽奖与活动玩法</summary>
63
119
 
64
- > **要求 Node.js >= 20**(项目含 `.nvmrc`,推荐使用 Node 22)
120
+ <br>
65
121
 
66
- ### 第一步:切换 Node 版本
122
+ | 组件 | 说明 |
123
+ | --------------- | ------------ |
124
+ | `Turntable` | 抽奖转盘 |
125
+ | `Confetti` | 彩纸喷射庆祝 |
126
+ | `Charge` | 充电动效 |
127
+ | `ScratchCard` | 刮刮乐 |
128
+ | `SlotMachine` | 老虎机 |
129
+ | `DiceRoll` | 3D 掷骰子 |
130
+ | `RedPacketRain` | 红包雨 |
131
+ | `ProgressChest` | 宝箱进度 |
132
+ | `RadarScan` | 雷达扫描 HUD |
67
133
 
68
- ```bash
69
- nvm use
70
- # 若未安装 Node 20
71
- nvm install 20 && nvm use 20
72
- ```
134
+ </details>
73
135
 
74
- ### 第二步:安装依赖
136
+ <details>
137
+ <summary><strong>数据装饰</strong> — 8 个 · 大屏与时间展示</summary>
75
138
 
76
- **不要直接运行 `pnpm install`**(若本机 corepack 有问题会报错),请使用:
139
+ <br>
77
140
 
78
- ```bash
79
- npm run setup
80
- ```
141
+ | 组件 | 说明 |
142
+ | ----------------- | --------------- |
143
+ | `CanvasClock` | Canvas 模拟时钟 |
144
+ | `FlipCounter` | 机械翻牌数字 |
145
+ | `Countdown` | 活动倒计时 |
146
+ | `LiquidProgress` | 液体进度环 |
147
+ | `AudioVisualizer` | 音频可视化 |
148
+ | `Speedometer` | 速度仪表盘 |
149
+ | `TimelinePulse` | 时间轴脉冲 |
150
+ | `OrbitalChart` | 轨道占比图 |
81
151
 
82
- 该命令会通过 `npx` 直接调用 pnpm,绕过 corepack。
152
+ </details>
83
153
 
84
- ### 第三步:启动开发
154
+ <details>
155
+ <summary><strong>物理创意</strong> — 7 个 · 物理模拟与视觉实验</summary>
156
+
157
+ <br>
158
+
159
+ | 组件 | 说明 |
160
+ | --------------- | ------------ |
161
+ | `Fireworks` | 烟花燃放 |
162
+ | `ReturnCity` | 回城传送特效 |
163
+ | `NewtonCradle` | 牛顿摆 |
164
+ | `GravityBalls` | 重力球池 |
165
+ | `DnaHelix` | DNA 双螺旋 |
166
+ | `ElectricArc` | 电弧闪电 |
167
+ | `MazeGenerator` | 迷宫生成器 |
168
+
169
+ </details>
170
+
171
+ ---
85
172
 
86
- ```bash
87
- npx --yes pnpm@9 dev
88
- ```
89
-
90
- 访问 `http://localhost:4000` 进入首页,按分类浏览并跳转到对应组件演示(共 49 个组件)。
173
+ ## 特性
91
174
 
92
- ## 脚本
175
+ - **49 个组件**,覆盖背景、文字、交互、营销、数据、物理六大场景
176
+ - **React 19** + **Vite 8** + **TypeScript 5** 现代技术栈
177
+ - **ESM / CJS** 双格式,完整 `.d.ts` 类型
178
+ - **样式自动注入**,无需 `import 'cos-design/dist/index.css'`
179
+ - Canvas 组件**页面隐藏时自动暂停**动画,省电友好
180
+ - **GitHub Actions** 自动 lint、构建、npm 发布
93
181
 
94
- | 命令 | 说明 |
95
- | ------------------------ | ------------------------------- |
96
- | `npm run setup` | 安装依赖(推荐,绕过 corepack) |
97
- | `npx --yes pnpm@9 dev` | 启动本地演示 |
98
- | `npx --yes pnpm@9 build` | 构建组件库 |
99
- | `npx --yes pnpm@9 lint` | 代码检查 |
100
- | `npx --yes pnpm@9 pub` | 构建并发布到 npm |
182
+ ---
101
183
 
102
- ## 修复本机 pnpm(可选)
184
+ ## 本地开发
103
185
 
104
- 若希望直接使用 `pnpm` 命令,在 **Node 20+** 环境下执行:
186
+ > 要求 **Node.js >= 20**(推荐 Node 22,项目含 `.nvmrc`)
105
187
 
106
188
  ```bash
107
- nvm use 20
108
- corepack disable
109
- hash -r
110
- npm install -g pnpm@9
111
- which pnpm # 确认路径不在 corepack 下
112
- pnpm -v
189
+ git clone git@github.com:jiaxiantao/cos-design.git
190
+ cd cos-design
191
+ nvm use
192
+ npm run setup # 安装依赖(绕过 corepack 问题)
193
+ npx --yes pnpm@9 dev # 启动 Playground
113
194
  ```
114
195
 
115
- ## 自动发布(CI/CD)
196
+ 访问 **http://localhost:4000** — 按分类浏览全部 49 个组件,右侧可查看与复制示例代码。
116
197
 
117
- 推送到 `master` 分支后,GitHub Actions 会自动执行 lint、构建,并将**新版本**发布到 [npm](https://www.npmjs.com/package/cos-design)。
198
+ ---
118
199
 
119
- ### 首次配置(仅需一次)
200
+ ## 常用命令
120
201
 
121
- 1. 打开 [npm Access Tokens](https://www.npmjs.com/settings/jiaxiantao/tokens)
122
- 2. 创建 **Granular Access Token**:
123
- - Permissions: Packages → **Read and write**
124
- - 勾选 **Bypass 2FA for publish**(自动化发布必须)
125
- 3. 打开 GitHub 仓库 → **Settings** → **Secrets and variables** → **Actions**
126
- 4. 新建 Secret:`NPM_TOKEN`,值为上一步的 token
202
+ | 命令 | 说明 |
203
+ | ------------------------ | -------------- |
204
+ | `npm run setup` | 安装依赖 |
205
+ | `npx --yes pnpm@9 dev` | 启动本地演示 |
206
+ | `npx --yes pnpm@9 build` | 构建组件库 |
207
+ | `npx --yes pnpm@9 lint` | 代码检查 |
208
+ | `npx --yes pnpm@9 pub` | 构建并发布 npm |
127
209
 
128
- ### 发布新版本
210
+ ---
129
211
 
130
- ```bash
131
- # 1. 更新 package.json 中的 version(如 2.2.0)
132
- # 2. 更新 CHANGELOG.md
133
- # 3. 提交并推送
134
- git add .
135
- git commit -m "chore: release v2.2.0"
136
- git push origin master
137
-
138
- # 4.(可选)打 tag
139
- git tag v2.2.0 && git push origin v2.2.0
212
+ ## 使用注意
213
+
214
+ **Canvas 组件请客户端渲染**(依赖 `window` / `canvas` / `requestAnimationFrame`):
215
+
216
+ ```tsx
217
+ import dynamic from 'next/dynamic';
218
+
219
+ const Fireworks = dynamic(() => import('cos-design').then((m) => m.Fireworks), { ssr: false });
140
220
  ```
141
221
 
142
- 推送后可在 [Actions](https://github.com/jiaxiantao/cos-design/actions) 查看发布进度。若 npm 上已存在相同版本号,会自动跳过发布。
222
+ **控制使用密度** — 一个页面建议「一个强视觉背景 + 若干局部交互」,避免全场动画互相抢戏。
223
+
224
+ ---
143
225
 
144
226
  ## 文档
145
227
 
146
- - [完整介绍与实践指南](./docs/cos-design-intro.md) — 项目背景、架构、组件能力与适用场景
228
+ | 文档 | 内容 |
229
+ | ------------------------------------------------ | -------------------------------- |
230
+ | [v3.0 发布博客](./docs/cos-design-v3-release.md) | 重大升级解读、分类体系、技术实现 |
231
+ | [完整介绍与实践指南](./docs/cos-design-intro.md) | 架构、使用规则、组件详解 |
232
+ | [CHANGELOG](./CHANGELOG.md) | 版本更新记录 |
233
+ | [CONTRIBUTING](./CONTRIBUTING.md) | 参与贡献指南 |
234
+
235
+ ---
236
+
237
+ ## 自动发布
238
+
239
+ 推送到 `master` 后,GitHub Actions 自动 lint、构建,并将新版本发布到 [npm](https://www.npmjs.com/package/cos-design)。
240
+
241
+ 首次配置需在 GitHub Secrets 中设置 `NPM_TOKEN`(需勾选 **Bypass 2FA for publish**)。详见 [npm Access Tokens](https://www.npmjs.com/settings/jiaxiantao/tokens)。
242
+
243
+ ---
147
244
 
148
245
  ## 参与贡献
149
246
 
150
- 欢迎提交 Issue 与 Pull Request,请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。
247
+ 欢迎提交 Issue 与 Pull Request!
248
+
249
+ ---
151
250
 
152
- ## 更新日志
251
+ <div align="center">
153
252
 
154
- 详见 [CHANGELOG.md](./CHANGELOG.md)。
253
+ **如果觉得有用,欢迎 Star ⭐**
155
254
 
156
- ## License
255
+ [MIT](./LICENSE) © [jiaxiantao](https://github.com/jiaxiantao)
157
256
 
158
- [MIT](./LICENSE) © jiaxiantao
257
+ </div>