@demo/ui-components

一个现代化的 React UI 组件库，使用 TypeScript 构建，提供响应式设计和主题支持。

✨ 特性

• 🎨 现代设计: 简洁美观的设计风格
• 📱 响应式: 完美适配各种屏幕尺寸
• 🌙 主题支持: 内置明暗主题切换
• 🔧 TypeScript: 完整的类型定义
• 🎯 易于使用: 简单直观的 API 设计
• ♿ 无障碍性: 遵循 WCAG 无障碍标准
• 🧪 测试覆盖: 完整的单元测试
• 📦 按需加载: 支持 Tree Shaking

📦 安装

npm install @demo/ui-components
# 或
yarn add @demo/ui-components
# 或
pnpm add @demo/ui-components

🚀 快速开始

import React from 'react';
import { Button, Card, CardBody, useTheme } from '@demo/ui-components';
import '@demo/ui-components/dist/index.css';

function App() {
  const { theme, toggleTheme } = useTheme();
  
  return (
    <div className={`app theme-${theme}`}>
      <Card>
        <CardBody>
          <h1>欢迎使用 UI Components</h1>
          <p>这是一个现代化的 React 组件库</p>
          <Button onClick={toggleTheme}>
            切换到 {theme === 'light' ? '暗色' : '亮色'} 主题
          </Button>
        </CardBody>
      </Card>
    </div>
  );
}

export default App;

📚 组件文档

基础组件

• Button 按钮 - 基础按钮组件
• Input 输入框 - 表单输入组件
• Card 卡片 - 内容容器组件

Hooks

• useTheme - 主题管理 Hook
• useResponsive - 响应式设计 Hook

🎨 主题系统

组件库内置了完整的主题系统，支持明暗主题切换：

import { useTheme } from '@demo/ui-components';

function ThemeToggle() {
  const { theme, toggleTheme, setTheme } = useTheme();
  
  return (
    <div>
      <button onClick={toggleTheme}>切换主题</button>
      <button onClick={() => setTheme('system')}>跟随系统</button>
    </div>
  );
}

自定义主题

通过 CSS 变量自定义主题：

:root {
  --primary-color: #007bff;
  --secondary-color: #6c757d;
  --success-color: #28a745;
  --danger-color: #dc3545;
  --warning-color: #ffc107;
  --info-color: #17a2b8;
  
  --background-color: #ffffff;
  --surface-color: #f8f9fa;
  --text-color: #333333;
  --text-secondary-color: #666666;
  
  --border-color: #e0e0e0;
  --border-radius: 4px;
  --shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

[data-theme="dark"] {
  --background-color: #1a1a1a;
  --surface-color: #2d2d2d;
  --text-color: #ffffff;
  --text-secondary-color: #cccccc;
  --border-color: #404040;
}

📱 响应式设计

使用 useResponsive Hook 实现响应式设计：

import { useResponsive } from '@demo/ui-components';

function ResponsiveComponent() {
  const { breakpoint, md, lg } = useResponsive();
  
  return (
    <div>
      <p>当前断点: {breakpoint}</p>
      {md && <p>中等屏幕及以上</p>}
      {lg && <p>大屏幕及以上</p>}
    </div>
  );
}

断点定义

| 断点 | 尺寸 | 设备类型 | |------|------|----------| | xs | < 576px | 手机 | | sm | ≥ 576px | 大手机 | | md | ≥ 768px | 平板 | | lg | ≥ 992px | 桌面 | | xl | ≥ 1200px | 大桌面 |

🧪 开发

环境要求

• Node.js >= 16
• React >= 16.8.0
• TypeScript >= 4.0

本地开发

# 克隆项目
git clone https://github.com/yourusername/ui-components.git
cd ui-components

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 运行测试
npm test

# 构建项目
npm run build

项目结构

src/
├── components/          # 组件目录
│   ├── Button/         # 按钮组件
│   ├── Card/           # 卡片组件
│   └── Input/          # 输入框组件
├── hooks/              # 自定义 Hooks
│   ├── useTheme.tsx    # 主题管理
│   └── useResponsive.ts # 响应式设计
├── styles/             # 样式文件
│   ├── variables.css   # CSS 变量
│   └── base.css        # 基础样式
├── types/              # 类型定义
└── utils/              # 工具函数

📋 API 参考

组件 Props

所有组件都支持以下通用 Props：

| 属性 | 类型 | 默认值 | 说明 | |------|------|--------|------| | className | string | - | 自定义 CSS 类名 | | style | CSSProperties | - | 自定义样式 | | children | ReactNode | - | 子元素 |

主题相关

interface ThemeContextValue {
  theme: 'light' | 'dark' | 'system';
  actualTheme: 'light' | 'dark';
  systemTheme: 'light' | 'dark';
  isDark: boolean;
  isLight: boolean;
  toggleTheme: () => void;
  setTheme: (theme: 'light' | 'dark' | 'system') => void;
}

响应式相关

interface ResponsiveValue {
  breakpoint: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
  width: number;
  height: number;
  xs: boolean;
  sm: boolean;
  md: boolean;
  lg: boolean;
  xl: boolean;
}

🤝 贡献

我们欢迎所有形式的贡献！请阅读 贡献指南 了解详情。

开发流程

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

代码规范

• 使用 ESLint 和 Prettier 保持代码风格一致
• 编写单元测试覆盖新功能
• 遵循 Conventional Commits 规范
• 为新组件编写文档和示例

📄 许可证

本项目基于 MIT 许可证开源。

🙏 致谢

感谢所有为这个项目做出贡献的开发者！

📞 支持

如果你在使用过程中遇到问题，可以通过以下方式获取帮助：

• 📖 查看 文档
• 🐛 提交 Issue
• 💬 参与 讨论
• 📧 发送邮件至 [email protected]

🔗 相关链接

• 在线文档
• Storybook 示例
• 更新日志
• 路线图