cos-design 3.0.4 → 3.2.0

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,35 @@ 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.2.0] - 2026-06-23
9
+
10
+ ### Added
11
+
12
+ - 物理创意分类新增 6 个组件:`DoublePendulum`、`PlasmaBall`、`MetaballPool`、`SolarSystem`、`LorenzAttractor`、`RopeChain`
13
+
14
+ ### Fixed
15
+
16
+ - `NewtonCradle` 改为 Canvas 单摆物理模拟,碰撞后动量正确传递至对端小球
17
+
18
+ ### Changed
19
+
20
+ - Playground 顶栏搜索图标放大,统计徽章文字居中
21
+
22
+ ## [3.1.0] - 2026-06-23
23
+
24
+ ### Added
25
+
26
+ - Playground **快速开始** 页面(`#/quickstart`)与仓库根目录 `QUICKSTART.md`
27
+ - 组件页 **实时编辑代码**(`react-live`),修改后预览立即更新
28
+ - 各组件 **配置参数** 表格,由 `pnpm extract-props` 从源码自动生成
29
+ - 顶栏 **GitHub** 图标外链仓库
30
+
31
+ ### Changed
32
+
33
+ - 组件页「编辑代码」打开时自动滚动至编辑器
34
+ - 配置参数展示在页面底部(预览 / 编辑区下方)
35
+ - README 增加快速开始入口与使用注意摘要
36
+
8
37
  ## [3.0.4] - 2026-06-23
9
38
 
10
39
  ### Fixed
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  # cos-design
4
4
 
5
- **49 个 React 视觉特效组件 · 活动页 / 品牌页 / 创意展示开箱即用**
5
+ **55 个 React 视觉特效组件 · 活动页 / 品牌页 / 创意展示开箱即用**
6
6
 
7
7
  [![CI](https://github.com/jiaxiantao/cos-design/actions/workflows/ci.yml/badge.svg)](https://github.com/jiaxiantao/cos-design/actions/workflows/ci.yml)
8
8
  [![npm version](https://img.shields.io/npm/v/cos-design.svg)](https://www.npmjs.com/package/cos-design)
@@ -10,7 +10,7 @@
10
10
  [![React](https://img.shields.io/badge/React-19-61dafb)](https://react.dev/)
11
11
  [![TypeScript](https://img.shields.io/badge/TypeScript-5-3178c6)](https://www.typescriptlang.org/)
12
12
 
13
- [在线预览](https://jiaxiantao.github.io/cos-design/) · [v3.0 发布博客](./website-content/cos-design-v3-release.md) · [完整指南](./website-content/cos-design-intro.md) · [更新日志](./CHANGELOG.md)
13
+ [在线预览](https://jiaxiantao.github.io/cos-design/) · [快速开始](./QUICKSTART.md) · [v3.0 发布博客](./website-content/cos-design-v3-release.md) · [完整指南](./website-content/cos-design-intro.md) · [更新日志](./CHANGELOG.md)
14
14
 
15
15
  </div>
16
16
 
@@ -29,16 +29,22 @@
29
29
  | 数据大屏 | 翻牌器、仪表盘、液体进度环 |
30
30
  | 创意作品集 | 牛顿摆、DNA 螺旋、迷宫生成 |
31
31
 
32
- > 15 个组件太单薄,49 个刚好组成一套完整的「视觉工具箱」。
32
+ > 15 个组件太单薄,55 个刚好组成一套完整的「视觉工具箱」。
33
33
 
34
34
  ---
35
35
 
36
- ## 30 秒上手
36
+ ## 快速开始
37
+
38
+ > 完整说明见 **[QUICKSTART.md](./QUICKSTART.md)** · Playground 内访问 **#/quickstart**
39
+
40
+ ### 安装
37
41
 
38
42
  ```bash
39
43
  pnpm add cos-design
40
44
  ```
41
45
 
46
+ ### 最简示例
47
+
42
48
  ```tsx
43
49
  import { Fireworks, ScrambleText, ScratchCard } from 'cos-design';
44
50
 
@@ -55,9 +61,19 @@ export default function Page() {
55
61
 
56
62
  无需手动引入 CSS,样式自动注入。完整 TypeScript 类型开箱即用。
57
63
 
64
+ ### 使用注意(摘要)
65
+
66
+ | 注意点 | 说明 |
67
+ | -------- | --------------------------------------------------------------- |
68
+ | **SSR** | Canvas 组件需在 Next.js 等框架中 `dynamic(..., { ssr: false })` |
69
+ | **尺寸** | Canvas 组件需明确 `width` / `height`,父容器也应有可见高度 |
70
+ | **密度** | 建议每页「一个强背景 + 若干局部交互」,避免多 Canvas 抢性能 |
71
+ | **权限** | `AudioVisualizer` 开启麦克风时需 HTTPS 与用户授权 |
72
+ | **省电** | 标签页隐藏时,多数 Canvas 动画自动暂停 |
73
+
58
74
  ---
59
75
 
60
- ## 组件一览(49 个 · 6 大分类)
76
+ ## 组件一览(55 个 · 6 大分类)
61
77
 
62
78
  <details open>
63
79
  <summary><strong>背景动效</strong> — 9 个 · 动态场景与粒子背景</summary>
@@ -152,19 +168,25 @@ export default function Page() {
152
168
  </details>
153
169
 
154
170
  <details>
155
- <summary><strong>物理创意</strong> — 7 个 · 物理模拟与视觉实验</summary>
171
+ <summary><strong>物理创意</strong> — 13 个 · 物理模拟与视觉实验</summary>
156
172
 
157
173
  <br>
158
174
 
159
- | 组件 | 说明 |
160
- | --------------- | ------------ |
161
- | `Fireworks` | 烟花燃放 |
162
- | `ReturnCity` | 回城传送特效 |
163
- | `NewtonCradle` | 牛顿摆 |
164
- | `GravityBalls` | 重力球池 |
165
- | `DnaHelix` | DNA 双螺旋 |
166
- | `ElectricArc` | 电弧闪电 |
167
- | `MazeGenerator` | 迷宫生成器 |
175
+ | 组件 | 说明 |
176
+ | ----------------- | ------------ |
177
+ | `Fireworks` | 烟花燃放 |
178
+ | `ReturnCity` | 回城传送特效 |
179
+ | `NewtonCradle` | 牛顿摆 |
180
+ | `GravityBalls` | 重力球池 |
181
+ | `DnaHelix` | DNA 双螺旋 |
182
+ | `ElectricArc` | 电弧闪电 |
183
+ | `MazeGenerator` | 迷宫生成器 |
184
+ | `DoublePendulum` | 双摆混沌轨迹 |
185
+ | `PlasmaBall` | 等离子静电球 |
186
+ | `MetaballPool` | 液态融合球 |
187
+ | `SolarSystem` | 太阳系公转 |
188
+ | `LorenzAttractor` | 洛伦兹吸引子 |
189
+ | `RopeChain` | 绳索链条摆动 |
168
190
 
169
191
  </details>
170
192
 
@@ -172,7 +194,7 @@ export default function Page() {
172
194
 
173
195
  ## 特性
174
196
 
175
- - **49 个组件**,覆盖背景、文字、交互、营销、数据、物理六大场景
197
+ - **55 个组件**,覆盖背景、文字、交互、营销、数据、物理六大场景
176
198
  - **React 19** + **Vite 8** + **TypeScript 5** 现代技术栈
177
199
  - **ESM / CJS** 双格式,完整 `.d.ts` 类型
178
200
  - **样式自动注入**,无需 `import 'cos-design/dist/index.css'`
@@ -193,7 +215,7 @@ npm run setup # 安装依赖(绕过 corepack 问题)
193
215
  npx --yes pnpm@9 dev # 启动 Playground
194
216
  ```
195
217
 
196
- 访问 **http://localhost:4000** — 按分类浏览全部 49 个组件,右侧可查看与复制示例代码。
218
+ 访问 **http://localhost:4000** — 按分类浏览全部 55 个组件,右侧可查看与复制示例代码。
197
219
 
198
220
  ---
199
221
 
@@ -211,6 +233,8 @@ npx --yes pnpm@9 dev # 启动 Playground
211
233
 
212
234
  ## 使用注意
213
235
 
236
+ 详见 [QUICKSTART.md](./QUICKSTART.md)。以下为高频场景摘要:
237
+
214
238
  **Canvas 组件请客户端渲染**(依赖 `window` / `canvas` / `requestAnimationFrame`):
215
239
 
216
240
  ```tsx
@@ -227,6 +251,7 @@ const Fireworks = dynamic(() => import('cos-design').then((m) => m.Fireworks), {
227
251
 
228
252
  | 文档 | 内容 |
229
253
  | ----------------------------------------------------------- | -------------------------------- |
254
+ | [快速开始](./QUICKSTART.md) | 安装、用法、注意事项与常见问题 |
230
255
  | [v3.0 发布博客](./website-content/cos-design-v3-release.md) | 重大升级解读、分类体系、技术实现 |
231
256
  | [完整介绍与实践指南](./website-content/cos-design-intro.md) | 架构、使用规则、组件详解 |
232
257
  | [CHANGELOG](./CHANGELOG.md) | 版本更新记录 |
@@ -0,0 +1,10 @@
1
+ import { default as React } from 'react';
2
+ export interface DoublePendulumProps {
3
+ width?: number;
4
+ height?: number;
5
+ trailLength?: number;
6
+ color?: string;
7
+ color2?: string;
8
+ }
9
+ declare const DoublePendulum: React.FC<DoublePendulumProps>;
10
+ export default DoublePendulum;
@@ -26,6 +26,8 @@ export { default as CursorTrail } from './cursorTrail';
26
26
  export type { CursorTrailProps } from './cursorTrail';
27
27
  export { default as DiceRoll } from './diceRoll';
28
28
  export type { DiceRollProps } from './diceRoll';
29
+ export { default as DoublePendulum } from './doublePendulum';
30
+ export type { DoublePendulumProps } from './doublePendulum';
29
31
  export { default as Fireworks } from './fireworks';
30
32
  export type { FireworksHandle, FireworksProps } from './fireworks';
31
33
  export { default as FlipCounter } from './flipCounter';
@@ -40,11 +42,15 @@ export { default as HolographicCard } from './holographicCard';
40
42
  export type { HolographicCardProps } from './holographicCard';
41
43
  export { default as LiquidProgress } from './liquidProgress';
42
44
  export type { LiquidProgressProps } from './liquidProgress';
45
+ export { default as LorenzAttractor } from './lorenzAttractor';
46
+ export type { LorenzAttractorProps } from './lorenzAttractor';
43
47
  export { default as LiquidGlass } from './liquidGlass';
44
48
  export type { LiquidGlassProps } from './liquidGlass';
45
49
  export { default as MagneticButton } from './magneticButton';
46
50
  export type { MagneticButtonProps } from './magneticButton';
47
51
  export { default as MatrixRain } from './matrixRain';
52
+ export { default as MetaballPool } from './metaballPool';
53
+ export type { MetaballPoolProps } from './metaballPool';
48
54
  export { default as MazeGenerator } from './mazeGenerator';
49
55
  export type { MazeGeneratorProps } from './mazeGenerator';
50
56
  export type { MatrixRainProps } from './matrixRain';
@@ -57,7 +63,11 @@ export type { NeonTextProps } from './neonText';
57
63
  export { default as OrbitalChart } from './orbitalChart';
58
64
  export type { OrbitalChartItem, OrbitalChartProps } from './orbitalChart';
59
65
  export { default as ParticleNetwork } from './particleNetwork';
66
+ export { default as PlasmaBall } from './plasmaBall';
67
+ export type { PlasmaBallProps } from './plasmaBall';
60
68
  export { default as SmokeFog } from './smokeFog';
69
+ export { default as SolarSystem } from './solarSystem';
70
+ export type { SolarSystemProps } from './solarSystem';
61
71
  export type { SmokeFogProps } from './smokeFog';
62
72
  export { default as Snowfall } from './snowfall';
63
73
  export type { SnowfallProps } from './snowfall';
@@ -71,6 +81,8 @@ export type { RadarScanProps } from './radarScan';
71
81
  export { default as RedPacketRain } from './redPacketRain';
72
82
  export type { RedPacketRainProps } from './redPacketRain';
73
83
  export { default as ReturnCity } from './returnCity';
84
+ export { default as RopeChain } from './ropeChain';
85
+ export type { RopeChainProps } from './ropeChain';
74
86
  export { default as Speedometer } from './speedometer';
75
87
  export type { SpeedometerProps } from './speedometer';
76
88
  export { default as TimelinePulse } from './timelinePulse';
@@ -0,0 +1,10 @@
1
+ import { default as React } from 'react';
2
+ export interface LorenzAttractorProps {
3
+ width?: number;
4
+ height?: number;
5
+ speed?: number;
6
+ color?: string;
7
+ pointCount?: number;
8
+ }
9
+ declare const LorenzAttractor: React.FC<LorenzAttractorProps>;
10
+ export default LorenzAttractor;
@@ -0,0 +1,9 @@
1
+ import { default as React } from 'react';
2
+ export interface MetaballPoolProps {
3
+ width?: number;
4
+ height?: number;
5
+ ballCount?: number;
6
+ color?: string;
7
+ }
8
+ declare const MetaballPool: React.FC<MetaballPoolProps>;
9
+ export default MetaballPool;
@@ -2,6 +2,8 @@ import { default as React } from 'react';
2
2
  export interface NewtonCradleProps {
3
3
  ballCount?: number;
4
4
  color?: string;
5
+ width?: number;
6
+ height?: number;
5
7
  }
6
8
  declare const NewtonCradle: React.FC<NewtonCradleProps>;
7
9
  export default NewtonCradle;
@@ -0,0 +1,9 @@
1
+ import { default as React } from 'react';
2
+ export interface PlasmaBallProps {
3
+ width?: number;
4
+ height?: number;
5
+ color?: string;
6
+ arcCount?: number;
7
+ }
8
+ declare const PlasmaBall: React.FC<PlasmaBallProps>;
9
+ export default PlasmaBall;
@@ -0,0 +1,10 @@
1
+ import { default as React } from 'react';
2
+ export interface RopeChainProps {
3
+ width?: number;
4
+ height?: number;
5
+ segments?: number;
6
+ color?: string;
7
+ gravity?: number;
8
+ }
9
+ declare const RopeChain: React.FC<RopeChainProps>;
10
+ export default RopeChain;
@@ -0,0 +1,9 @@
1
+ import { default as React } from 'react';
2
+ export interface SolarSystemProps {
3
+ width?: number;
4
+ height?: number;
5
+ speed?: number;
6
+ showOrbits?: boolean;
7
+ }
8
+ declare const SolarSystem: React.FC<SolarSystemProps>;
9
+ export default SolarSystem;