react-public-components 1.1.19 → 1.2.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/README.md +189 -313
- package/dist/index.cjs +6889 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.css +4445 -0
- package/dist/index.css.map +1 -1
- package/dist/index.d.cts +1437 -2
- package/dist/index.d.ts +1437 -2
- package/dist/index.js +6864 -13
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,387 +1,263 @@
|
|
|
1
1
|
# react-public-components
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/react-public-components)
|
|
4
|
+
[](https://github.com/xhua007/react-public-components)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
1. **CollapseBox** — 可折叠的内容容器组件
|
|
8
|
-
2. **Splitter** — 可拖拽调整、可折叠的分屏面板组件
|
|
9
|
-
3. **DisabledBox** — 禁用态包装容器组件（带锁图标及拦截事件）
|
|
10
|
-
4. **Masonry** — 瀑布流布局组件（一比一复刻 Ant Design V6 规范）
|
|
11
|
-
5. **BorderBeam** — 边框流光组件
|
|
6
|
+
📦 **企业级现代 React 通用核心组件库**。零沉重 UI 库绑定，开箱即用，提供 61 款真正高频、极客质感的中后台与现代 Web 应用组件。
|
|
12
7
|
|
|
13
8
|
---
|
|
14
9
|
|
|
15
|
-
##
|
|
16
|
-
|
|
17
|
-
### 简介
|
|
18
|
-
|
|
19
|
-
`CollapseBox` 是一个带切换按钮的可折叠容器。支持水平（左右收起）与垂直（上下收起）两种方向，按钮可放置在容器四条边的任意一侧，适合用作侧边栏、详情面板等可隐藏区域。
|
|
10
|
+
## 🌟 特性亮点
|
|
20
11
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
import 'react-public-components/styles.css';
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
### Props
|
|
30
|
-
|
|
31
|
-
| 属性 | 类型 | 默认值 | 说明 |
|
|
32
|
-
| ---------------- | ---------------------------------------- | -------------- | ---------------------------------------------------------------------------------- |
|
|
33
|
-
| `children` | `ReactNode` | - | 容器内部渲染的内容 |
|
|
34
|
-
| `title` | `string` | `'内容区域'` | 标题（当前版本内部隐藏渲染，仅作为占位属性保留） |
|
|
35
|
-
| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | 折叠方向：`horizontal` 沿 X 轴收起，`vertical` 沿 Y 轴收起 |
|
|
36
|
-
| `buttonPosition` | `'right' \| 'left' \| 'top' \| 'bottom'` | `'right'` | 切换按钮位置。`horizontal` 时建议 `left`/`right`，`vertical` 时建议 `top`/`bottom` |
|
|
37
|
-
| `defaultWidth` | `number \| string` | `600` | 容器宽度（支持像素数字如 `500` 或百分比字符串如 `'50%'`） |
|
|
38
|
-
| `defaultHeight` | `number \| string` | `300` | 容器高度（支持像素数字如 `300` 或百分比字符串如 `'50%'`） |
|
|
39
|
-
| `contentPadding` | `string` | `'16px'` | 内容区内边距 |
|
|
40
|
-
| `headerHeight` | `number` | `16` | 头部预留高度，用于计算内容区最大高度 |
|
|
41
|
-
| `className` | `string` | - | 根节点自定义类名 |
|
|
42
|
-
|
|
43
|
-
### 基础用法
|
|
44
|
-
|
|
45
|
-
```tsx
|
|
46
|
-
import { CollapseBox } from 'react-public-components';
|
|
47
|
-
|
|
48
|
-
export default function Demo() {
|
|
49
|
-
return (
|
|
50
|
-
<CollapseBox
|
|
51
|
-
direction="horizontal"
|
|
52
|
-
buttonPosition="right"
|
|
53
|
-
defaultWidth="50%"
|
|
54
|
-
defaultHeight={400}
|
|
55
|
-
>
|
|
56
|
-
<p>这里是折叠容器中的内容。</p>
|
|
57
|
-
</CollapseBox>
|
|
58
|
-
);
|
|
59
|
-
}
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
### 垂直方向示例
|
|
63
|
-
|
|
64
|
-
```tsx
|
|
65
|
-
<CollapseBox direction="vertical" buttonPosition="bottom" defaultHeight={300}>
|
|
66
|
-
<p>上下方向折叠的内容。</p>
|
|
67
|
-
</CollapseBox>
|
|
68
|
-
```
|
|
12
|
+
- 💎 **精炼通用**：涵盖中后台与 SaaS 产品的通用、布局导航、数据录入、数据展示、反馈 5 大类别共 61 款高频组件。
|
|
13
|
+
- ⚡ **轻量零依赖**：不强制依赖 Ant Design 等庞大第三方 UI 库，体积小巧，按需引入。
|
|
14
|
+
- 🛡️ **工业级防御**：核心安全组件（如 `Watermark`）采用原生 DOM 脱离 VDOM 注入防篡改架构，支持毫秒自愈与防审查元素删除。
|
|
15
|
+
- 🎨 **极客质感**：现代设计语言，自带平滑微动效、毛玻璃（Glassmorphism）、硬件加速流光与暗色模式适配。
|
|
16
|
+
- 📦 **开箱即用**：原生支持 TypeScript 类型定义、ESM、CommonJS 与样式自动构建。
|
|
69
17
|
|
|
70
18
|
---
|
|
71
19
|
|
|
72
|
-
##
|
|
73
|
-
|
|
74
|
-
### 简介
|
|
75
|
-
|
|
76
|
-
`Splitter` 是一个支持拖拽调整大小、可折叠、可重置的分屏面板组件，灵感来自 Ant Design 的 Splitter，但提供了更精细的折叠按钮交互。支持 `horizontal`（左右分屏）与 `vertical`（上下分屏）两种方向。
|
|
77
|
-
|
|
78
|
-
### 引入方式
|
|
20
|
+
## 快速安装
|
|
79
21
|
|
|
80
|
-
```
|
|
81
|
-
|
|
22
|
+
```bash
|
|
23
|
+
npm install react-public-components
|
|
24
|
+
# 或使用 pnpm
|
|
25
|
+
pnpm add react-public-components
|
|
26
|
+
# 或使用 yarn
|
|
27
|
+
yarn add react-public-components
|
|
82
28
|
```
|
|
83
29
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
| 属性 | 类型 | 默认值 | 说明 |
|
|
87
|
-
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------- |
|
|
88
|
-
| `children` | `ReactNode`（建议传入 `Splitter.Panel`） | - | 面板集合，建议 2 个及以上 |
|
|
89
|
-
| `className` | `string` | - | 根节点自定义类名 |
|
|
90
|
-
| `classNames` | `Partial<Record<SemanticDOM, string>> \| ((info: { props }) => Partial<Record<SemanticDOM, string>>)` | - | 自定义组件内部各语义化结构（`root` / `panel` / `dragger`）的类名，支持对象或函数 |
|
|
91
|
-
| `style` | `CSSProperties` | - | 根节点自定义 CSS 样式 |
|
|
92
|
-
| `styles` | `Partial<Record<SemanticDOM, CSSProperties>> \| ((info: { props }) => Partial<Record<SemanticDOM, CSSProperties>>)` | - | 自定义组件内部各语义化结构（`root` / `panel` / `dragger`）的 CSS 样式，支持对象或函数 |
|
|
93
|
-
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 分屏方向（优先级高于 `vertical`） |
|
|
94
|
-
| `vertical` | `boolean` | `false` | 是否垂直分屏（兼容写法） |
|
|
95
|
-
| `lazy` | `boolean` | `false` | 是否在拖拽结束时才更新视图（提升性能） |
|
|
96
|
-
| `onResizeStart` | `(sizes: number[]) => void` | - | 拖拽开始回调 |
|
|
97
|
-
| `onResize` | `(sizes: number[]) => void` | - | 拖拽过程中尺寸变化回调 |
|
|
98
|
-
| `onResizeEnd` | `(sizes: number[]) => void` | - | 拖拽/折叠/重置结束回调 |
|
|
99
|
-
| `onCollapse` | `(collapsed: boolean[], sizes: number[]) => void` | - | 面板展开或折叠状态发生变化时的回调 |
|
|
100
|
-
| `onDraggerDoubleClick` | `(index: number) => void` | - | 双击拖拽条回调 |
|
|
101
|
-
| `draggerIcon` | `ReactNode` | - | 自定义拖拽手柄指示图标节点 |
|
|
102
|
-
| `destroyOnHidden` | `boolean` | `false` | 折叠/隐藏时是否销毁所有面板内容节点 |
|
|
103
|
-
|
|
104
|
-
### Splitter.Panel Props
|
|
105
|
-
|
|
106
|
-
| 属性 | 类型 | 默认值 | 说明 |
|
|
107
|
-
| ----------------- | ---------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
|
|
108
|
-
| `children` | `ReactNode` | - | 面板内容 |
|
|
109
|
-
| `className` | `string` | - | 面板自定义类名 |
|
|
110
|
-
| `size` | `number \| '${number}%'` | - | 受控尺寸 |
|
|
111
|
-
| `defaultSize` | `number \| '${number}%'` | - | 初始尺寸（未设置时按剩余空间平均分配） |
|
|
112
|
-
| `min` | `number \| '${number}%'` | `0` | 最小尺寸 |
|
|
113
|
-
| `max` | `number \| '${number}%'` | - | 最大尺寸 |
|
|
114
|
-
| `collapsible` | `boolean \| { start?: boolean; end?: boolean; showCollapsibleIcon?: boolean \| 'auto' }` | `false` | 是否允许折叠面板。支持配置指定折叠方向（`start`/`end`）及图标显示策略（`showCollapsibleIcon`） |
|
|
115
|
-
| `destroyOnHidden` | `boolean` | - | 折叠/隐藏时是否销毁当前面板内容节点（可覆盖 Splitter 根属性） |
|
|
116
|
-
| `resizable` | `boolean` | `true` | 是否允许拖拽调整（两侧任一为 `false` 都会禁用对应分隔条） |
|
|
117
|
-
| `style` | `CSSProperties` | - | 面板自定义样式 |
|
|
118
|
-
|
|
119
|
-
### 基础用法
|
|
30
|
+
在项目入口文件中引入全局样式：
|
|
120
31
|
|
|
121
32
|
```tsx
|
|
122
|
-
import
|
|
123
|
-
|
|
124
|
-
export default function Demo() {
|
|
125
|
-
return (
|
|
126
|
-
<Splitter style={{ height: 400 }}>
|
|
127
|
-
<Splitter.Panel defaultSize="40%" min="20%">
|
|
128
|
-
<p>左侧面板</p>
|
|
129
|
-
</Splitter.Panel>
|
|
130
|
-
<Splitter.Panel>
|
|
131
|
-
<p>右侧面板</p>
|
|
132
|
-
</Splitter.Panel>
|
|
133
|
-
</Splitter>
|
|
134
|
-
);
|
|
135
|
-
}
|
|
33
|
+
import 'react-public-components/styles.css';
|
|
136
34
|
```
|
|
137
35
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
```tsx
|
|
141
|
-
<Splitter orientation="vertical" onResizeEnd={(sizes) => console.log('最终尺寸:', sizes)}>
|
|
142
|
-
<Splitter.Panel defaultSize="30%" collapsible min="10%">
|
|
143
|
-
<p>上方面板（可折叠）</p>
|
|
144
|
-
</Splitter.Panel>
|
|
145
|
-
<Splitter.Panel collapsible>
|
|
146
|
-
<p>下方面板（可折叠）</p>
|
|
147
|
-
</Splitter.Panel>
|
|
148
|
-
</Splitter>
|
|
149
|
-
```
|
|
36
|
+
---
|
|
150
37
|
|
|
151
|
-
|
|
38
|
+
## 🧩 组件全览（61 款核心高频组件）
|
|
152
39
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
40
|
+
### 1. 通用 General (8 款)
|
|
41
|
+
| 组件名 | 中文名称 | 特性与场景说明 |
|
|
42
|
+
| :--- | :--- | :--- |
|
|
43
|
+
| **`CodeSnippet`** | 代码预览块 | 极客代码展示块，支持暗色主题、一键复制与多行展开收起。 |
|
|
44
|
+
| **`Watermark`** | 安全水印 | DOM 防篡改盲水印，脱离 VDOM 具备毫秒级自愈与防审查元素删除能力。 |
|
|
45
|
+
| **`QrCodeCard`** | 二维码卡片 | 优雅企业级二维码展示卡片，支持 Logo 嵌入、状态覆盖（加载/过期刷新）与一键下载。 |
|
|
46
|
+
| **`GuidedTour`** | 新手引导 | 新手引导步进器，带智能镂空高亮遮罩、步骤弹窗与状态持久化。 |
|
|
47
|
+
| **`FilePreviewer`** | 文件预览 | 多格式文件与媒体统一弹窗预览器，支持图片、音视频、PDF、代码与一键下载。 |
|
|
48
|
+
| **`Fullscreen`** | 全屏容器 | 支持局部元素原生全屏与网页内最大化置顶切换，支持快捷悬浮按钮与 Render Props。 |
|
|
49
|
+
| **`CopyButton`** | 复制按钮 | 增强型剪贴板复制组件，支持 Tooltip 状态反馈、输入框后缀吸附与异步文本。 |
|
|
50
|
+
| **`ContextMenu`** | 右键快捷菜单 | 自定义右键上下文菜单，支持多级嵌套、分割线、禁用态与快捷键提示。 |
|
|
158
51
|
|
|
159
|
-
|
|
52
|
+
---
|
|
160
53
|
|
|
161
|
-
|
|
162
|
-
|
|
54
|
+
### 2. 布局与导航 Layout & Nav (9 款)
|
|
55
|
+
| 组件名 | 中文名称 | 特性与场景说明 |
|
|
56
|
+
| :--- | :--- | :--- |
|
|
57
|
+
| **`CascadeDrawer`** | 级联下钻抽屉 | 多层级无限下钻抽屉容器，带顶部面包屑返回导航与平滑推拉动效。 |
|
|
58
|
+
| **`KanbanBoard`** | 任务看板 | 轻量任务看板与泳道管理，基于原生 HTML5 Drag & Drop 跨列平滑拖拽。 |
|
|
59
|
+
| **`DragSortList`** | 拖拽排序列表 | 纯原生轻量拖拽重排序列表，支持平滑占位与阴影反馈。 |
|
|
60
|
+
| **`Marquee`** | 无缝跑马灯 | 基于硬件加速的无缝平滑滚动 Logo 墙与广播通知条，支持悬停暂停与边缘渐变。 |
|
|
61
|
+
| **`ScrollTracker`** | 滚动与吸顶 | 阅读进度条（ScrollTracker）与智能吸顶容器（StickyHeader，带毛玻璃与阴影）。 |
|
|
62
|
+
| **`InfiniteScrollList`** | 无限滚动列表 | 触底自动触发异步加载的无限滚动列表容器，内置加载骨架与到底提示。 |
|
|
63
|
+
| **`CollapseBox`** | 折叠容器 | 支持水平与垂直方向折叠的弹性容器组件，支持自定义按钮位置与默认尺寸。 |
|
|
64
|
+
| **`Splitter`** | 分隔面板 | 支持多面板拖拽调整尺寸、折叠与双击重置的可定制分隔面板组件。 |
|
|
65
|
+
| **`Masonry`** | 瀑布流 | 基于列优先的高性能响应式瀑布流布局组件，遵循 AntD 规范。 |
|
|
163
66
|
|
|
164
67
|
---
|
|
165
68
|
|
|
166
|
-
|
|
69
|
+
### 3. 数据录入 Data Entry (15 款)
|
|
70
|
+
| 组件名 | 中文名称 | 特性与场景说明 |
|
|
71
|
+
| :--- | :--- | :--- |
|
|
72
|
+
| **`DualRangeSlider`** | 双滑块区间选择器 | 双向双滑块区间选择器，支持数值/价格跨度筛选与防交叉穿透。 |
|
|
73
|
+
| **`FilterChips`** | 已选筛选胶囊栏 | 多维已选筛选项胶囊汇总栏，支持单项删除与一键清空全部。 |
|
|
74
|
+
| **`FileDropZone`** | 拖拽上传容器 | 现代极客拖拽上传虚线容器，支持流光呼吸高亮与剪贴板截图粘贴。 |
|
|
75
|
+
| **`TreeTransfer`** | 树形穿梭框 | 树形层级穿梭框，左侧目录树级联勾选与右侧平铺已选列表。 |
|
|
76
|
+
| **`NumberStepper`** | 平滑数字步进器 | 长按连续加减数字步进器，支持步长控制与上下限保护。 |
|
|
77
|
+
| **`KeyValEditor`** | 键值对编辑器 | 动态增删 API Headers 与环境变量配置项，支持密码掩码与单行禁用。 |
|
|
78
|
+
| **`QuickDateRange`** | 快捷日期筛选 | 今日/近7天/本月等预设日期胶囊标签与自定义日期范围双向联动。 |
|
|
79
|
+
| **`TreeFilterPanel`** | 树形平铺筛选 | 多级分类平铺联动筛选器，支持多选、快捷全部、分类汇总与一键清空。 |
|
|
80
|
+
| **`NumericRangeInput`** | 数值区间输入 | 价格与数值区间范围输入框，自带双向联动校验与快捷区间预设标签。 |
|
|
81
|
+
| **`CronPicker`** | Cron 选择器 | 定时任务 Cron 表达式可视化生成器，支持按天/周/月多周期配置与中文人话翻译。 |
|
|
82
|
+
| **`TagInput`** | 标签输入器 | 自由标签输入组件，支持回车/逗号打标签、退格删除、双击编辑与正则校验。 |
|
|
83
|
+
| **`PasswordStrength`** | 密码强度检测 | 多维度密码复杂度实时评分与 4 段彩色进度条可视化指示器。 |
|
|
84
|
+
| **`ImageCropper`** | 图片裁剪 | 轻量原生 Canvas 图片裁剪器，支持拖拽、滚轮缩放、90° 旋转、圆形头像裁剪与 Modal 弹窗。 |
|
|
85
|
+
| **`DebounceSelect`** | 防抖下拉框 | 防抖异步搜索选择器，内置时序竞态保护、单选/多选 Tags 模式与加载态。 |
|
|
86
|
+
| **`ColorPicker`** | 颜色选择器 | 支持 HEX、HSB、RGB 及渐变色模式的高级颜色选择与调色板组件。 |
|
|
167
87
|
|
|
168
|
-
|
|
88
|
+
---
|
|
169
89
|
|
|
170
|
-
|
|
90
|
+
### 4. 数据展示 Display (26 款)
|
|
91
|
+
| 组件名 | 中文名称 | 特性与场景说明 |
|
|
92
|
+
| :--- | :--- | :--- |
|
|
93
|
+
| **`JsonDiffViewer`** | JSON 差异比对器 | JSON 结构体增删改差异彩色高亮探查，支持新旧值对照。 |
|
|
94
|
+
| **`JsonTree`** | JSON 树状探查器 | 树状无限折叠展开的 JSON 探查器，支持数据类型高亮与路径探查。 |
|
|
95
|
+
| **`MiniSparkline`** | 单行微趋势折线图 | 指标卡与表格专用的极简微折线走势图，纯 SVG 贝塞尔曲线平滑绘制。 |
|
|
96
|
+
| **`SegmentedProgress`** | 分段多色进度条 | 单条轨道并列展示多色分段比例，支持存储空间占比与图例。 |
|
|
97
|
+
| **`TrendIndicator`** | KPI 趋势升降胶囊 | 微型 KPI 指标变动升降胶囊，自动根据正负值判断涨跌并支持红绿反转。 |
|
|
98
|
+
| **`PhotoViewer`** | 相册画廊查看器 | 全功能多图画廊查看器，支持左右键盘按键切图与缩略图底栏联动。 |
|
|
99
|
+
| **`StatusTimeline`** | 审批流时间轴 | 高级审批流与动态耗时时间轴，包含节点状态徽标、经办人与流转耗时。 |
|
|
100
|
+
| **`GradientText`** | 流光渐变文字 | 现代 SaaS 霓虹横向流光渐变文字，支持背景平滑滚动动画。 |
|
|
101
|
+
| **`VideoPlayer`** | 视频播放器 | 轻量现代化视频播放器，暗黑毛玻璃控制条、快进快退 10s、0.75x~2.0x 倍速与画中画。 |
|
|
102
|
+
| **`PdfViewer`** | PDF 在线阅读器 | 轻量 Web PDF 阅读器，支持缩放 Zoom、90° 顺时针旋转与一键下载。 |
|
|
103
|
+
| **`BadgeRibbon`** | 斜角丝带角标 | 卡片左上/右上 45° 倾斜缎带徽章，支持 HOT/PRO 推荐与渐变色。 |
|
|
104
|
+
| **`ShimmerSkeleton`** | 流光骨架屏 | 高质感渐变流光掠过骨架屏，支持卡片、列表、头像与多行文本。 |
|
|
105
|
+
| **`FlipCard`** | 3D 翻转卡片 | 3D 正反面翻转卡片，鼠标悬停或点击触发 180° 平滑翻转展示详情。 |
|
|
106
|
+
| **`VirtualList`** | 虚拟列表 | 零依赖轻量虚拟滚动列表，万级海量数据 60FPS 极速渲染不卡顿。 |
|
|
107
|
+
| **`MetricCard`** | KPI 指标卡 | Dashboard 看板指标卡片，集成 CountUp 数字跳动、环比升降趋势与微折线 Sparkline。 |
|
|
108
|
+
| **`ActivityLog`** | 操作审计日志 | 中后台业务操作与审批流动态时间轴，支持操作人头像、相对时间与变动详情折叠。 |
|
|
109
|
+
| **`AudioPlayer`** | 音频播放条 | 轻量客服录音与语音回放条，支持 Seek 拖拽、倍速切换与一键下载。 |
|
|
110
|
+
| **`TiltCard`** | 3D 倾斜卡片 | 鼠标悬停 3D 景深物理倾斜与流光高光跟随卡片。 |
|
|
111
|
+
| **`SpotlightCard`** | 聚光灯卡片 | 鼠标光晕聚光灯实时追踪跟随卡片，具备前沿极客科技感与暗色模式。 |
|
|
112
|
+
| **`SensitiveMask`** | 敏感脱敏 | 手机号/身份证/银行卡/邮箱等敏感数据脱敏展示，支持点击眼睛解密与复制。 |
|
|
113
|
+
| **`DiffViewer`** | 差异比对 | 轻量文本与代码行级差异比对器，支持分栏 Split 与行内 Unified 模式。 |
|
|
114
|
+
| **`JsonEditor`** | JSON 查看与编辑 | 轻量免外部依赖的 JSON 语法高亮查看与编辑器，支持格式化、单行压缩与错误定位。 |
|
|
115
|
+
| **`CountUp`** | 数字滚动 | 基于高质量缓动算法的平滑数字跳动动画组件，支持前缀后缀与命令式 Ref 控制。 |
|
|
116
|
+
| **`TextEllipsis`** | 文本省略 | 支持单行/多行文本截断、展开/收起切换、溢出智能 Tooltip 与一键复制。 |
|
|
117
|
+
| **`BorderBeam`** | 边框流光 | 为卡片或容器边框添加流动高亮与自定义渐变动画的特效组件。 |
|
|
118
|
+
| **`DisabledBox`** | 禁用遮罩 | 为子级元素或复杂区域提供统一的禁用态透明遮罩与防交互保护。 |
|
|
171
119
|
|
|
172
|
-
|
|
120
|
+
---
|
|
173
121
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
122
|
+
### 5. 反馈 Feedback (3 款)
|
|
123
|
+
| 组件名 | 中文名称 | 特性与场景说明 |
|
|
124
|
+
| :--- | :--- | :--- |
|
|
125
|
+
| **`AnnouncementBar`** | 广播通知横幅 | 页面顶部吸顶渐变广播横幅，支持可配置关闭与持久化记忆。 |
|
|
126
|
+
| **`HoverCard`** | 悬浮资料卡 | Twitter / GitHub 风格悬浮信息卡片，防误触延迟与视口防溢出。 |
|
|
127
|
+
| **`EnvBadge`** | 环境防误触角标 | 醒目的环境状态标识胶囊，点击查看构建版本详情并支持多环境跳转。 |
|
|
177
128
|
|
|
178
|
-
|
|
129
|
+
---
|
|
179
130
|
|
|
180
|
-
|
|
181
|
-
| ----------- | ------------------- | -------- | ------------------------------------------------------ |
|
|
182
|
-
| `children` | `ReactNode` | - | 容器包裹的主体内容 |
|
|
183
|
-
| `title` | `ReactNode` | - | 标题或替代内容（当未传入 `children` 时生效） |
|
|
184
|
-
| `disabled` | `boolean` | `false` | 是否禁用，禁用时显示锁图标、文字呈现灰色且拦截点击事件 |
|
|
185
|
-
| `iconAlign` | `'left' \| 'right'` | `'left'` | 锁图标的对齐位置 |
|
|
131
|
+
## 💻 典型用法示例
|
|
186
132
|
|
|
187
|
-
###
|
|
133
|
+
### 1. Watermark 防篡改水印
|
|
188
134
|
|
|
189
135
|
```tsx
|
|
190
|
-
import {
|
|
191
|
-
|
|
192
|
-
export default function
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
136
|
+
import { Watermark } from 'react-public-components';
|
|
137
|
+
|
|
138
|
+
export default function App() {
|
|
139
|
+
return (
|
|
140
|
+
<Watermark
|
|
141
|
+
content={['内部机密 严禁外传', 'alex.chen 2026-08-18']}
|
|
142
|
+
color="rgba(0, 0, 0, 0.10)"
|
|
143
|
+
antiTamper
|
|
144
|
+
>
|
|
145
|
+
<div style={{ padding: 32, height: 400 }}>
|
|
146
|
+
<h2>核心财务分析报告</h2>
|
|
147
|
+
<p>即便在控制台尝试删除 DOM 或在 Styles 面板取消勾选属性，水印也会毫秒自愈复原。</p>
|
|
148
|
+
</div>
|
|
149
|
+
</Watermark>
|
|
150
|
+
);
|
|
198
151
|
}
|
|
199
152
|
```
|
|
200
153
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
## 四、Masonry 瀑布流组件
|
|
204
|
-
|
|
205
|
-
### 简介
|
|
206
|
-
|
|
207
|
-
`Masonry` 是一个符合 Ant Design V6 规范的瀑布流布局组件。支持固定或响应式列数配置（`columns`）、水平垂直间距配置（`gutter`）、持续监听子项尺寸变化（`fresh`）、自定义语义化结构样式/类名（`styles`/`classNames`）以及列排序回调（`onLayoutChange`）。
|
|
208
|
-
|
|
209
|
-
### 引入方式
|
|
154
|
+
### 2. Splitter 分隔面板
|
|
210
155
|
|
|
211
156
|
```tsx
|
|
212
|
-
import {
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
### Masonry Props
|
|
216
|
-
|
|
217
|
-
| 参数 | 说明 | 类型 | 默认值 |
|
|
218
|
-
| ---------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------- |
|
|
219
|
-
| `classNames` | 自定义内部语义化结构 class，支持对象或函数 | `Record<'root' \| 'item', string> \| ((info: { props }) => Record<'root' \| 'item', string>)` | `-` |
|
|
220
|
-
| `columns` | 列数，固定数字或响应式配置 | `number \| { xs?: number; sm?: number; md?: number; lg?: number; xl?: number; xxl?: number }` | `3` |
|
|
221
|
-
| `fresh` | 是否持续监听子项尺寸变化 | `boolean` | `false` |
|
|
222
|
-
| `gutter` | 间距，固定数字、响应式配置或水平垂直间距配置 | `Gap \| [Gap, Gap]` | `0` |
|
|
223
|
-
| `items` | 瀑布流数据项 | `MasonryItem[]` | `-` |
|
|
224
|
-
| `itemRender` | 自定义数据项渲染函数 | `(item: MasonryItem) => ReactNode` | `-` |
|
|
225
|
-
| `styles` | 语义化结构 style，支持对象和函数形式 | `Record<'root' \| 'item', CSSProperties> \| ((info: { props }) => Record<'root' \| 'item', CSSProperties>)` | `-` |
|
|
226
|
-
| `onLayoutChange` | 列排序计算完成回调 | `(layout: { key: React.Key; column: number }[]) => void` | `-` |
|
|
227
|
-
|
|
228
|
-
### MasonryItem 属性
|
|
229
|
-
|
|
230
|
-
| 参数 | 说明 | 类型 | 默认值 |
|
|
231
|
-
| ---------- | ------------------------------------------------ | ------------------ | ------ |
|
|
232
|
-
| `children` | 自定义展示内容，相对 `itemRender` 具有更高优先级 | `ReactNode` | `-` |
|
|
233
|
-
| `column` | 自定义指定放置列（0-indexed） | `number` | `-` |
|
|
234
|
-
| `data` | 自定义存储数据 | `T` | `-` |
|
|
235
|
-
| `height` | 高度（手指定时优先使用） | `number` | `-` |
|
|
236
|
-
| `key` | 唯一标识 | `string \| number` | `-` |
|
|
237
|
-
|
|
238
|
-
### 基础用法
|
|
157
|
+
import { Splitter } from 'react-public-components';
|
|
239
158
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
{ key: '2', height: 180, children: <div>卡片 2</div> },
|
|
252
|
-
{ key: '3', height: 150, children: <div>卡片 3</div> },
|
|
253
|
-
]}
|
|
254
|
-
/>
|
|
255
|
-
);
|
|
159
|
+
export default function App() {
|
|
160
|
+
return (
|
|
161
|
+
<Splitter style={{ height: 400 }}>
|
|
162
|
+
<Splitter.Panel defaultSize="30%" min="15%" collapsible>
|
|
163
|
+
<div style={{ padding: 16 }}>左侧导航树</div>
|
|
164
|
+
</Splitter.Panel>
|
|
165
|
+
<Splitter.Panel>
|
|
166
|
+
<div style={{ padding: 16 }}>主体工作区内容</div>
|
|
167
|
+
</Splitter.Panel>
|
|
168
|
+
</Splitter>
|
|
169
|
+
);
|
|
256
170
|
}
|
|
257
171
|
```
|
|
258
172
|
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
## 五、BorderBeam 边框流光组件
|
|
262
|
-
|
|
263
|
-
### 简介
|
|
264
|
-
|
|
265
|
-
`BorderBeam` 是一个给任意容器边框添加持续流动高亮效果的组件。使用现代 CSS Mask 遮罩与 CSS Motion Path 动画，支持单色与多点渐变色配置、多条流光均匀分布、流光尺寸与线宽调节，以及贴合自定义宿主容器。
|
|
266
|
-
|
|
267
|
-
### 引入方式
|
|
268
|
-
|
|
269
|
-
```tsx
|
|
270
|
-
import { BorderBeam } from 'react-public-components';
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
### API
|
|
274
|
-
|
|
275
|
-
| 参数 | 说明 | 类型 | 默认值 | 版本 | 全局配置 |
|
|
276
|
-
| ----------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------ | ----- | -------- |
|
|
277
|
-
| `children` | 装饰内容 | `ReactNode` | `-` | 6.4.0 | × |
|
|
278
|
-
| `color` | 流光颜色配置，支持单色字符串或渐变停靠点数组。`percent` 使用 `0 ~ 100` 的输入区间，组件会在内部为尾部透明过渡预留空间 | `string \| { color: string; percent: number }[]` | `-` | 6.4.0 | × |
|
|
279
|
-
| `count` | 流光数量 | `number` | `1` | 6.6.0 | × |
|
|
280
|
-
| `duration` | 流光完成一圈动画的时间，单位秒 | `number` | `6` | 6.5.0 | × |
|
|
281
|
-
| `lineWidth` | 流光线宽，数字类型按像素处理 | `number \| string` | `1px` | 6.5.0 | × |
|
|
282
|
-
| `outset` | 流光层相对容器边缘的外扩距离，遇到裁剪容器时可设为 `0` | `number \| string` | `-` | 6.4.0 | × |
|
|
283
|
-
| `size` | 流光可见段的尺寸，数字类型按像素处理 | `number \| string` | `100` | 6.5.0 | × |
|
|
284
|
-
|
|
285
|
-
### 基础用法
|
|
173
|
+
### 3. CodeSnippet 极客代码块
|
|
286
174
|
|
|
287
175
|
```tsx
|
|
288
|
-
import {
|
|
289
|
-
|
|
290
|
-
export default function
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
);
|
|
176
|
+
import { CodeSnippet } from 'react-public-components';
|
|
177
|
+
|
|
178
|
+
export default function App() {
|
|
179
|
+
return (
|
|
180
|
+
<CodeSnippet
|
|
181
|
+
language="typescript"
|
|
182
|
+
code={`const greeting: string = "Hello, react-public-components!";\nconsole.log(greeting);`}
|
|
183
|
+
showLineNumbers
|
|
184
|
+
/>
|
|
185
|
+
);
|
|
299
186
|
}
|
|
300
187
|
```
|
|
301
188
|
|
|
302
189
|
---
|
|
303
190
|
|
|
304
|
-
##
|
|
191
|
+
## 🛠️ 本地开发与预览
|
|
305
192
|
|
|
306
|
-
|
|
307
|
-
.
|
|
308
|
-
├── CollapseBox/
|
|
309
|
-
│ ├── index.tsx
|
|
310
|
-
│ └── index.less
|
|
311
|
-
├── Splitter/
|
|
312
|
-
│ └── index.tsx
|
|
313
|
-
├── DisabledBox/
|
|
314
|
-
│ ├── index.tsx
|
|
315
|
-
│ └── index.less
|
|
316
|
-
├── Masonry/
|
|
317
|
-
│ ├── index.tsx
|
|
318
|
-
│ └── index.less
|
|
319
|
-
└── BorderBeam/
|
|
320
|
-
├── index.tsx
|
|
321
|
-
└── index.less
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
---
|
|
325
|
-
|
|
326
|
-
## 七、发布到 npm
|
|
193
|
+
克隆本仓库并在本地启动全功能交互 Demo 预览站点：
|
|
327
194
|
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
195
|
+
```bash
|
|
196
|
+
# 安装依赖
|
|
197
|
+
npm install
|
|
331
198
|
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
199
|
+
# 启动本地开发与组件预览站点（基于 Vite）
|
|
200
|
+
npm run dev
|
|
201
|
+
```
|
|
335
202
|
|
|
336
|
-
|
|
203
|
+
浏览器打开 `http://localhost:5173` 即可浏览全部 61 款组件的实时效果、代码与参数调节面板。
|
|
337
204
|
|
|
338
|
-
|
|
339
|
-
npm whoami
|
|
340
|
-
```
|
|
205
|
+
---
|
|
341
206
|
|
|
342
|
-
|
|
343
|
-
```bash
|
|
344
|
-
# 查看当前镜像源
|
|
345
|
-
npm config get registry
|
|
207
|
+
## 📦 标准化发布流程 (Release Workflow)
|
|
346
208
|
|
|
347
|
-
|
|
348
|
-
npm config set registry https://registry.npmjs.org/
|
|
349
|
-
```
|
|
209
|
+
本项目已配置 `"prepublishOnly": "npm run build"` 自动化钩子，每次执行 `npm publish` 时会自动先执行全量类型与产物打包构建。
|
|
350
210
|
|
|
351
|
-
###
|
|
211
|
+
### 1. 前置准备与环境检查
|
|
212
|
+
```bash
|
|
213
|
+
# 检查当前 npm 源是否为官方镜像源（若不是需切换）
|
|
214
|
+
npm config get registry
|
|
215
|
+
# 切换为 npm 官方源（发布必须使用官方源）
|
|
216
|
+
npm config set registry https://registry.npmjs.org/
|
|
352
217
|
|
|
353
|
-
|
|
218
|
+
# 登录 npm 账号（会自动唤起网页完成 2FA / Web 授权）
|
|
219
|
+
npm login --auth-type=web
|
|
220
|
+
```
|
|
354
221
|
|
|
222
|
+
### 2. 更新版本号 (遵循 SemVer 规范)
|
|
355
223
|
```bash
|
|
356
|
-
#
|
|
224
|
+
# 小修复与优化（Patch）：1.2.0 -> 1.2.1
|
|
357
225
|
npm version patch
|
|
358
226
|
|
|
359
|
-
#
|
|
227
|
+
# 新功能与组件迭代（Minor）：1.2.0 -> 1.3.0
|
|
360
228
|
npm version minor
|
|
361
229
|
|
|
362
|
-
#
|
|
230
|
+
# 架构破坏性更新（Major）：1.2.0 -> 2.0.0
|
|
363
231
|
npm version major
|
|
364
232
|
```
|
|
365
233
|
|
|
366
|
-
### 3.
|
|
234
|
+
### 3. 构建与本地验证
|
|
235
|
+
```bash
|
|
236
|
+
# 验证组件库核心打包（生成 dist/ 产物）
|
|
237
|
+
npm run build
|
|
367
238
|
|
|
368
|
-
|
|
239
|
+
# 验证 Demo 演示站编译
|
|
240
|
+
npm run build:demo
|
|
241
|
+
```
|
|
369
242
|
|
|
243
|
+
### 4. 提交代码与推送到 GitHub
|
|
370
244
|
```bash
|
|
371
|
-
|
|
372
|
-
|
|
245
|
+
git add .
|
|
246
|
+
git commit -m "chore(release): bump version to x.x.x"
|
|
247
|
+
git push
|
|
248
|
+
```
|
|
373
249
|
|
|
374
|
-
|
|
375
|
-
|
|
250
|
+
### 5. 正式发布到 npm
|
|
251
|
+
```bash
|
|
252
|
+
# 执行发布（自动触发 prepublishOnly 构建）
|
|
253
|
+
npm publish --access public
|
|
376
254
|
|
|
377
|
-
#
|
|
378
|
-
npm
|
|
255
|
+
# 验证发布状态
|
|
256
|
+
npm view react-public-components version
|
|
379
257
|
```
|
|
380
258
|
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
> npm publish --access public
|
|
387
|
-
> ```
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
## 📄 开源许可
|
|
262
|
+
|
|
263
|
+
[MIT License](LICENSE)
|