react-tech-ui 1.0.0 → 1.0.1

package/README.md

@@ -7,9 +7,11 @@
 - 🎨 **科技风格设计** — 深色主题 + 霓虹光效 + 扫描线动画，打造沉浸式科技感
 - 📺 **大屏适配** — 内置 ScreenAdapter 组件，支持等比缩放、宽度缩放、全屏三种适配模式
 - ✨ **丰富动画** — 脉冲发光、扫描线、渐变流动、数字翻牌等多种科技风动画
-- 📦 **开箱即用** — 9 大核心组件，覆盖大屏开发常见场景
+- 📦 **开箱即用** — 20 大核心组件，覆盖大屏开发常见场景
 - 🔧 **TypeScript** — 完整类型定义，开发体验友好
-- 🎯 **按需使用** — CSS 变量驱动主题，轻松自定义颜色和风格
+- 🎯 **按需引入** — 支持 ESM/CJS 双格式，可按组件单独引入
+- 🎭 **7 套预设主题** — 赛博蓝、霓虹绿、极光紫、落日橙、赤焰红、鎏金、暗黑深渊
+- 🌈 **CSS 变量驱动** — 轻松自定义颜色和风格
 
 ## 快速开始
 
@@ -45,6 +47,13 @@ function App() {
 }
 ```
 
+### 按需引入
+
+```tsx
+import { ScreenAdapter } from 'react-tech-ui/ScreenAdapter';
+import 'react-tech-ui/ScreenAdapter/style.css';
+```
+
 ## 本地开发
 
 ### 环境要求
@@ -72,10 +81,13 @@ npm run build:lib
 ```
 
 构建产物：
-- `dist/index.es.js` — ES Module 格式
-- `dist/index.cjs.js` — CommonJS 格式
+- `dist/index/index.js` — ES Module 格式（主入口）
+- `dist/index/index.cjs` — CommonJS 格式（主入口）
+- `dist/index/style.css` — 合并样式文件（包含所有组件样式）
 - `dist/index.d.ts` — TypeScript 类型声明
-- `dist/style.css` — 样式文件
+- `dist/[Component]/index.js` — 单组件 ES Module
+- `dist/[Component]/index.cjs` — 单组件 CommonJS
+- `dist/[Component]/style.css` — 单组件样式
 
 ### 其他命令
 
@@ -340,6 +352,396 @@ const columns = [
 
 ---
 
+### Modal — 模态对话框
+
+科技风格模态框，支持 3 种变体，ESC 键关闭。
+
+```tsx
+<Modal
+  open={visible}
+  onClose={() => setVisible(false)}
+  title="系统提示"
+  variant="neon"
+  footer={<TechButton variant="primary" onClick={handleConfirm}>确认</TechButton>}
+>
+  <p>确定要执行此操作吗？</p>
+</Modal>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| open | 是否显示 | `boolean` | - |
+| onClose | 关闭回调 | `() => void` | - |
+| title | 标题 | `ReactNode` | - |
+| footer | 底部内容 | `ReactNode` | - |
+| width | 宽度(px) | `number` | `520` |
+| variant | 样式变体 | `'default' \| 'neon' \| 'scan'` | `'default'` |
+| maskClosable | 点击遮罩关闭 | `boolean` | `true` |
+| closable | 显示关闭按钮 | `boolean` | `true` |
+| animate | 入场动画 | `boolean` | `true` |
+
+---
+
+### Drawer — 抽屉
+
+从屏幕边缘滑出的面板，支持四个方向。
+
+```tsx
+<Drawer
+  open={visible}
+  onClose={() => setVisible(false)}
+  title="详情面板"
+  placement="right"
+  variant="neon"
+  width={400}
+>
+  <p>抽屉内容</p>
+</Drawer>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| open | 是否显示 | `boolean` | - |
+| onClose | 关闭回调 | `() => void` | - |
+| title | 标题 | `ReactNode` | - |
+| footer | 底部内容 | `ReactNode` | - |
+| width | 宽度/高度 | `number \| string` | `400` |
+| placement | 弹出方向 | `'left' \| 'right' \| 'top' \| 'bottom'` | `'right'` |
+| variant | 样式变体 | `'default' \| 'neon' \| 'scan'` | `'default'` |
+| maskClosable | 点击遮罩关闭 | `boolean` | `true` |
+| closable | 显示关闭按钮 | `boolean` | `true` |
+
+---
+
+### Toast — 轻提示
+
+全局提示组件，支持 5 种类型，命令式调用。
+
+```tsx
+import { Toast } from 'react-tech-ui';
+
+// 在 App 根组件中挂载容器
+function App() {
+  return (
+    <>
+      <YourRoutes />
+      <Toast.Container />
+    </>
+  );
+}
+
+// 在任意地方调用
+Toast.success('操作成功');
+Toast.error('操作失败');
+Toast.warning('请注意风险');
+Toast.info('系统提示');
+Toast.loading('加载中...');
+Toast.close(id);
+```
+
+| 方法 | 说明 | 参数 |
+|------|------|------|
+| `Toast.info(content, config?)` | 信息提示 | `ReactNode, ToastConfig?` |
+| `Toast.success(content, config?)` | 成功提示 | `ReactNode, ToastConfig?` |
+| `Toast.warning(content, config?)` | 警告提示 | `ReactNode, ToastConfig?` |
+| `Toast.error(content, config?)` | 错误提示 | `ReactNode, ToastConfig?` |
+| `Toast.loading(content, config?)` | 加载提示（不自动关闭） | `ReactNode, ToastConfig?` |
+| `Toast.custom(config)` | 自定义提示 | `ToastConfig` |
+| `Toast.close(id)` | 关闭指定提示 | `string` |
+
+**ToastConfig：**
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| content | 提示内容 | `ReactNode` | - |
+| type | 类型 | `'info' \| 'success' \| 'warning' \| 'error' \| 'loading'` | `'info'` |
+| duration | 自动关闭时间(ms)，0 不关闭 | `number` | `3000` |
+| closable | 显示关闭按钮 | `boolean` | `false` |
+| icon | 自定义图标 | `ReactNode` | - |
+
+---
+
+### Popconfirm — 气泡确认框
+
+点击元素弹出确认气泡，支持 4 个方向。
+
+```tsx
+<Popconfirm
+  title="确认删除"
+  content="删除后数据将无法恢复"
+  onConfirm={handleDelete}
+  onCancel={() => {}}
+  placement="top"
+>
+  <TechButton variant="outline">删除</TechButton>
+</Popconfirm>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| content | 确认内容 | `ReactNode` | - |
+| title | 标题 | `ReactNode` | - |
+| onConfirm | 确认回调 | `() => void` | - |
+| onCancel | 取消回调 | `() => void` | - |
+| confirmText | 确认按钮文字 | `string` | `'确认'` |
+| cancelText | 取消按钮文字 | `string` | `'取消'` |
+| placement | 弹出方向 | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` |
+| variant | 样式变体 | `'default' \| 'neon' \| 'scan'` | `'default'` |
+| trigger | 触发方式 | `'click' \| 'hover'` | `'click'` |
+| disabled | 是否禁用 | `boolean` | `false` |
+
+---
+
+### FlowLight — 流光背景
+
+4 种流光动画背景效果，可叠加内容。
+
+```tsx
+<FlowLight variant="aurora" speed={1.5} intensity="high">
+  <div style={{ padding: 40 }}>叠加在流光上的内容</div>
+</FlowLight>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| variant | 流光变体 | `'aurora' \| 'grid' \| 'particle' \| 'wave'` | `'aurora'` |
+| color | 流光颜色 | `string` | `--tech-primary` |
+| speed | 动画速度 | `number` | `1` |
+| opacity | 透明度 | `number` | `0.6` |
+| intensity | 强度 | `'low' \| 'medium' \| 'high'` | `'medium'` |
+
+**变体说明：**
+- `aurora`：极光效果，多层渐变流动
+- `grid`：网格效果
+- `particle`：粒子效果
+- `wave`：波浪效果
+
+---
+
+### ThemeProvider — 主题提供者
+
+7 套预设主题，支持运行时切换，通过 CSS 变量全局生效。
+
+```tsx
+import { ThemeProvider, useTheme } from 'react-tech-ui';
+
+function App() {
+  return (
+    <ThemeProvider defaultTheme="cyber-blue">
+      <YourContent />
+    </ThemeProvider>
+  );
+}
+
+// 在子组件中切换主题
+function ThemeSwitcher() {
+  const { themeName, setTheme, presetThemes, themeLabels } = useTheme();
+
+  return (
+    <select value={themeName} onChange={(e) => setTheme(e.target.value)}>
+      {Object.entries(themeLabels).map(([key, label]) => (
+        <option key={key} value={key}>{label}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| defaultTheme | 默认主题名 | `string` | `'cyber-blue'` |
+| children | 子元素 | `ReactNode` | - |
+
+**预设主题：**
+
+| 主题名 | 中文名 | 主色调 |
+|--------|--------|--------|
+| `cyber-blue` | 赛博蓝 | `#00d4ff` |
+| `neon-green` | 霓虹绿 | `#0affb0` |
+| `aurora-purple` | 极光紫 | `#a855f7` |
+| `sunset-orange` | 落日橙 | `#ff6b35` |
+| `crimson-red` | 赤焰红 | `#ff4757` |
+| `gold-luxury` | 鎏金 | `#fbbf24` |
+| `dark-abyss` | 暗黑深渊 | `#64748b` |
+
+**useTheme() 返回值：**
+
+| 属性 | 说明 | 类型 |
+|------|------|------|
+| themeName | 当前主题名 | `string` |
+| themeVars | 当前主题变量 | `PartialTechThemeVars` |
+| setTheme | 切换主题 | `(name: string, vars?: PartialTechThemeVars) => void` |
+| presetThemes | 所有预设主题 | `Record<string, PartialTechThemeVars>` |
+| themeLabels | 主题中文名映射 | `Record<string, string>` |
+
+---
+
+### Skeleton — 骨架屏
+
+数据加载时的占位骨架，支持 4 种变体和 loading 状态控制。
+
+```tsx
+<Skeleton variant="text" rows={3} loading={isLoading}>
+  <DataCard title="数据" value={data} />
+</Skeleton>
+
+<Skeleton variant="circle" width={48} />
+<Skeleton variant="card" />
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| variant | 骨架变体 | `'text' \| 'rect' \| 'circle' \| 'card'` | `'text'` |
+| width | 宽度 | `number \| string` | - |
+| height | 高度 | `number \| string` | - |
+| rows | 行数（text 模式） | `number` | `1` |
+| rowsGap | 行间距(px) | `number` | `12` |
+| animate | 闪烁动画 | `boolean` | `true` |
+| loading | 加载状态，false 时显示 children | `boolean` | - |
+
+---
+
+### QRCode — 二维码
+
+科技风格二维码，支持扫描线动画和中心图标。
+
+```tsx
+<QRCode
+  value="https://example.com"
+  size={200}
+  variant="neon"
+  title="扫码访问"
+  description="请使用手机扫描"
+/>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| value | 二维码内容 | `string` | - |
+| size | 尺寸(px) | `number` | `200` |
+| variant | 样式变体 | `'default' \| 'neon' \| 'scan'` | `'default'` |
+| color | 前景色 | `string` | `--tech-primary` |
+| bgColor | 背景色 | `string` | `--tech-bg-medium` |
+| level | 容错等级 | `'L' \| 'M' \| 'Q' \| 'H'` | `'M'` |
+| includeMargin | 是否包含边距 | `boolean` | `false` |
+| icon | 中心图标 URL | `string` | - |
+| iconSize | 中心图标尺寸(px) | `number` | `40` |
+| title | 标题 | `ReactNode` | - |
+| description | 描述 | `ReactNode` | - |
+
+---
+
+### Icon — 图标
+
+内置 80+ 科技风格 SVG 图标，支持发光和旋转效果。
+
+```tsx
+import { Icon } from 'react-tech-ui';
+
+<Icon name="home" size={24} />
+<Icon name="setting" variant="neon" />
+<Icon name="loading" spin />
+<Icon name="arrow-right" color="#0affb0" />
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| name | 图标名称 | `IconName` | - |
+| size | 尺寸 | `number \| string` | `20` |
+| color | 颜色 | `string` | `--tech-primary` |
+| variant | 样式变体 | `'default' \| 'neon' \| 'glow'` | `'default'` |
+| spin | 旋转动画 | `boolean` | `false` |
+| onClick | 点击回调 | `MouseEventHandler` | - |
+
+**图标名称分类：**
+
+| 分类 | 图标 |
+|------|------|
+| 导航 | `home`, `menu`, `compass`, `location`, `target`, `scan` |
+| 用户 | `user`, `team`, `lock`, `unlock` |
+| 操作 | `add`, `minus`, `close`, `check`, `edit`, `delete`, `copy`, `paste`, `search`, `filter`, `sort`, `refresh`, `sync`, `swap`, `share`, `link` |
+| 方向 | `arrow-up`, `arrow-down`, `arrow-left`, `arrow-right`, `chevron-up`, `chevron-down`, `chevron-left`, `chevron-right`, `expand`, `collapse`, `fullscreen`, `fullscreen-exit` |
+| 状态 | `info`, `question`, `warning`, `error`, `success`, `loading`, `notification` |
+| 数据 | `chart`, `dashboard`, `data`, `database` |
+| 设备 | `server`, `cloud`, `network`, `shield`, `terminal`, `code`, `bug`, `api` |
+| 媒体 | `camera`, `image`, `file`, `folder`, `play`, `pause`, `stop`, `forward` |
+| 通信 | `message`, `email`, `phone` |
+| 时间 | `calendar`, `clock`, `timer`, `history` |
+| 文件 | `download`, `upload`, `export`, `import` |
+| 其他 | `sun`, `moon`, `star`, `flash`, `power`, `signal`, `wifi`, `bluetooth`, `more`, `ellipsis`, `drag`, `eye`, `eye-off` |
+
+---
+
+### Masonry — 瀑布流布局
+
+科技风格瀑布流布局，自动按高度分配列。
+
+```tsx
+const items = [
+  { id: 1, height: 200, title: '卡片1' },
+  { id: 2, height: 300, title: '卡片2' },
+  { id: 3, height: 150, title: '卡片3' },
+];
+
+<Masonry
+  items={items}
+  columns={3}
+  gap={12}
+  variant="neon"
+  renderItem={(item) => <div>{item.title}</div>}
+/>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| items | 数据源 | `MasonryItem[]` | - |
+| columns | 列数 | `number` | `3` |
+| gap | 间距(px) | `number` | `12` |
+| columnWidth | 列宽 | `number \| string` | - |
+| variant | 样式变体 | `'default' \| 'neon' \| 'scan' \| 'glass'` | `'default'` |
+| renderItem | 渲染项函数 | `(item: T, index: number) => ReactNode` | - |
+| keyExtractor | 自定义 key | `(item: T, index: number) => string \| number` | - |
+
+**MasonryItem：**
+
+| 属性 | 说明 | 类型 | 必填 |
+|------|------|------|------|
+| id | 唯一标识 | `string \| number` | 是 |
+| height | 项高度(px) | `number` | 否，默认 `200` |
+
+---
+
+### FloatingButton — 浮动按钮
+
+可拖拽的浮动操作按钮，支持边缘吸附。
+
+```tsx
+<FloatingButton
+  icon={<Icon name="setting" size={20} />}
+  variant="neon"
+  draggable
+  edgeSnap
+  onClick={() => console.log('clicked')}
+>
+  设置
+</FloatingButton>
+```
+
+| 属性 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| icon | 图标 | `ReactNode` | - |
+| children | 文字标签 | `ReactNode` | - |
+| variant | 样式变体 | `'default' \| 'neon' \| 'glow' \| 'glass'` | `'default'` |
+| size | 尺寸(px) | `number` | `48` |
+| draggable | 是否可拖拽 | `boolean` | `false` |
+| initialPosition | 初始位置 | `{ x?: number, y?: number }` | 右下角 |
+| edgeSnap | 边缘吸附 | `boolean` | `true` |
+| snapThreshold | 吸附距离(px) | `number` | `60` |
+| onClick | 点击回调 | `(e: MouseEvent) => void` | - |
+| onDragEnd | 拖拽结束回调 | `(position: { x: number, y: number }) => void` | - |
+
+---
+
 ## 主题定制
 
 组件库使用 CSS 变量驱动主题，可通过覆盖变量自定义风格：
@@ -358,7 +760,17 @@ const columns = [
 }
 ```
 
-也可在 JavaScript 中获取主题对象：
+也可使用 ThemeProvider 运行时切换主题：
+
+```tsx
+import { ThemeProvider, useTheme } from 'react-tech-ui';
+
+<ThemeProvider defaultTheme="aurora-purple">
+  <App />
+</ThemeProvider>
+```
+
+或在 JavaScript 中获取主题对象：
 
 ```tsx
 import { techTheme } from 'react-tech-ui';
@@ -385,12 +797,23 @@ src/
 │   ├── ScrollTable/          # 滚动表格
 │   ├── StatusIndicator/      # 状态指示器
 │   ├── DecorationLine/       # 装饰线条
-│   └── TechButton/           # 科技按钮
+│   ├── TechButton/           # 科技按钮
+│   ├── Modal/                # 模态对话框
+│   ├── Drawer/               # 抽屉
+│   ├── Toast/                # 轻提示
+│   ├── Popconfirm/           # 气泡确认框
+│   ├── FlowLight/            # 流光背景
+│   ├── ThemeProvider/        # 主题提供者
+│   ├── Skeleton/             # 骨架屏
+│   ├── QRCode/               # 二维码
+│   ├── Icon/                 # 图标
+│   ├── Masonry/              # 瀑布流布局
+│   └── FloatingButton/       # 浮动按钮
 └── index.ts                  # 统一导出入口
 
 demo/
 ├── main.tsx                  # Demo 入口
-└── App.tsx                   # 大屏演示页面
+└── pages/                    # 各组件演示页面
 ```
 
 ## 技术栈
@@ -400,6 +823,52 @@ demo/
 - Vite 5
 - CSS Variables（主题系统）
 
+## 发布到 npm
+
+### 首次发布
+
+```bash
+# 1. 构建组件库
+npm run build:lib
+
+# 2. 登录 npm（首次需要）
+npm login
+
+# 3. 发布
+npm publish
+```
+
+### 更新版本发布
+
+```bash
+# 1. 更新版本号
+npm version patch    # 1.0.0 → 1.0.1（修 bug）
+npm version minor    # 1.0.0 → 1.1.0（新功能）
+npm version major    # 1.0.0 → 2.0.0（破坏性变更）
+
+# 2. 构建
+npm run build:lib
+
+# 3. 发布
+npm publish
+```
+
+> ⚠️ 注意：每次发布版本号必须比上次高，npm 不允许重复发布同一版本号。
+
+### 开启双因素认证（2FA）时的发布方式
+
+如果 npm 账号开启了 2FA，需要使用以下方式之一：
+
+**方式一：OTP 验证码**
+```bash
+npm publish --otp=你的6位验证码
+```
+
+**方式二：Granular Access Token**
+1. 在 npm 网站创建 Granular Access Token，勾选 **Allow publishing with 2FA bypass**
+2. 设置 Token：`npm config set //registry.npmjs.org/:_authToken 你的Token`
+3. 执行：`npm publish`
+
 ## 参与贡献
 
 1. Fork 本仓库

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-tech-ui",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "科技风格React UI组件库，支持大屏页面使用",
   "main": "dist/index/index.cjs",
   "module": "dist/index/index.js",