npm package: @mxmweb/zui
Description: 一个现代化的 React UI 组件库，提供完整的主题系统和丰富的组件集合。
Author: hanfeng_Zhang
Latest version: 1.4.0

# @mxmweb/zui

一个现代化的 React UI 组件库，提供完整的主题系统和丰富的组件集合。

## 📦 包结构

ZUI 采用模块化设计，包含以下子包：
- **@mxmweb/zui-theme** (v2.1.x) - 主题系统包
- **@mxmweb/zui-elements** (v1.1.x) - 基础元素组件
- **@mxmweb/zui-components** (v1.1.x) - 复杂业务组件
- **@mxmweb/zui-layouts** (v1.1.x) - 布局容器组件
- **@mxmweb/zui-icons** (v1.x) - 图标组件包

## 🚀 快速开始

### 安装

```bash
# 安装主包（推荐）
npm install @mxmweb/zui @mxmweb/zui-theme @mxmweb/zui-elements @mxmweb/zui-components @mxmweb/zui-layouts @mxmweb/zui-icons

```

### 依赖要求

确保你的项目已安装以下依赖：

```json
{
  "dependencies": {
    "react": ">=18.0.0 <20.0.0",
    "react-dom": ">=18.0.0 <20.0.0",
    "styled-components": "^6.0.0"
  }
}
```

**可选依赖**（根据使用的组件）：
```json
{
  "dependencies": {
    "animejs": "^3.0.0",           // 动画组件需要
    "antd": "^5.0.0",              // 表单组件需要
    "lucide-react": "^0.456.0"     // 图标组件需要
  }
}
```

### 基础使用

```tsx
import React from 'react';
import { ThemeProvider, Button, GoogleNavbar } from '@mxmweb/zui';
import '@mxmweb/zui/style.css';

// 自定义主题
const customTheme = {
  colors: {
    primary: '#007bff',
    background: '#ffffff',
    text: '#333333'
  },
  space: {
    radius: '8px',
    padding: '16px'
  }
};

function App() {
  return (
    <ThemeProvider theme={customTheme}>
      <div>
        <GoogleNavbar 
          items={[
            { key: 'home', name: '首页', icon: '🏠' },
            { key: 'about', name: '关于', icon: 'ℹ️' }
          ]}
        />
        <Button mode="primary" label="点击我" />
      </div>
    </ThemeProvider>
  );
}

export default App;
```

## 🎨 主题系统

ZUI 提供强大的主题系统，支持 3 级优先级：

1. **用户 styles** - 最高优先级
2. **useTheme 上下文** - 中等优先级  
3. **默认主题** - 基础优先级

### 主题配置

```tsx
import { ThemeProvider, useTheme } from '@mxmweb/zui';

// 全局主题配置
const globalTheme = {
  theme: {
    colors: {
      primary: '#007bff',
      secondary: '#6c757d',
      success: '#28a745',
      error: '#dc3545',
      background: '#ffffff',
      text: '#333333',
      border: '#dee2e6'
    },
    space: {
      radius: '8px',
      padding: '16px'
    },
    fonts: {
      heading: {
        family: 'PingFang SC, Microsoft YaHei, Arial, sans-serif',
        size: '16px',
        weight: '600'
      },
      body: {
        family: 'PingFang SC, Microsoft YaHei, Arial, sans-serif',
        size: '14px',
        weight: '400'
      }
    }
  },
  mode: 'light' // 或 'dark'
};

// 组件级主题覆盖
function MyComponent() {
  const globalTheme = useTheme();
  
  const customStyles = {
    theme: {
      colors: {
        primary: '#ff6b6b' // 覆盖全局主题
      }
    }
  };

  return (
    <Button 
      mode="primary" 
      label="自定义按钮"
      styles={customStyles} // 最高优先级
    />
  );
}
```

## 📚 组件文档

### 基础元素 (@mxmweb/zui-elements)

#### Button 按钮
```tsx
import { Button } from '@mxmweb/zui';

<Button 
  mode="primary"        // 'primary' | 'default' | 'error' | 'text'
  label="按钮文字"
  icon={<Icon />}      // 可选图标
  disabled={false}     // 禁用状态
  loading={false}      // 加载状态
  onClick={() => {}}   // 点击事件
  styles={customStyles} // 自定义样式
/>
```

#### DropdownMenu 下拉菜单
```tsx
import { DropdownMenu } from '@mxmweb/zui';

<DropdownMenu
  actions={[
    { key: 'edit', label: '编辑', icon: <EditIcon /> },
    { key: 'delete', label: '删除', icon: <DeleteIcon />, type: 'divider' },
    { key: 'more', label: '更多' }
  ]}
  onAction={(key) => console.log(key)}
  direction="bottom"   // 'top' | 'bottom'
  styles={customStyles}
/>
```

### 复杂组件 (@mxmweb/zui-components)

#### GoogleNavbar 导航栏
```tsx
import { GoogleNavbar } from '@mxmweb/zui';

<GoogleNavbar
  items={[
    { 
      key: 'home', 
      name: '首页', 
      icon: '🏠',
      activeIcon: '🏡',
      path: '/home',
      badge: 5
    }
  ]}
  activePath="/home"
  open={true}
  onOpenChange={(open) => {}}
  onItemClick={(item) => {}}
  logo={<Logo />}
  styles={customStyles}
/>
```

#### DynamicTable 动态表格
```tsx
import { DynamicTable } from '@mxmweb/zui';

<DynamicTable
  columns={[
    { id: 'name', title: '姓名', type: 'text' },
    { id: 'age', title: '年龄', type: 'number' },
    { id: 'status', title: '状态', type: 'status' }
  ]}
  dataSource={[
    { id: '1', data: [
      { columnId: 'name', value: '张三' },
      { columnId: 'age', value: 25 }
    ]}
  ]}
  allowMultiSelect={true}
  viewBehavior="pagination"
  styles={customStyles}
/>
```

#### Uploader 文件上传
```tsx
import { Uploader } from '@mxmweb/zui';

<Uploader
  multiple={true}
  accept="image/*"
  maxSize={10} // MB
  url="/api/upload"
  autoUpload={true}
  itemForm={[
    { name: 'title', label: '标题', type: 'text' },
    { name: 'description', label: '描述', type: 'textarea' }
  ]}
  eventsEmit={(event, data) => {
    console.log(event, data);
  }}
  styles={customStyles}
/>
```

### 布局容器 (@mxmweb/zui-layouts)

#### DashboardContainer 仪表板容器
```tsx
import { DashboardContainer } from '@mxmweb/zui';

<DashboardContainer
  title="仪表板"
  description="系统概览"
  breadcrumbs={[
    { id: 'home', label: '首页', path: '/' },
    { id: 'dashboard', label: '仪表板' }
  ]}
  dockItems={navItems}
  goBack={() => history.back()}
  eventsEmit={{
    onBreadcrumbClick: (item, index) => {},
    onGoBack: () => {},
    onTitleClick: () => {}
  }}
  styles={customStyles}
>
  <YourContent />
</DashboardContainer>
```

#### DockContainer 全屏容器
```tsx
import { DockContainer } from '@mxmweb/zui';

<DockContainer
  backgroundImage="/bg.jpg"
  backgroundColor="#1a1a1a"
  header={<Header />}
  dockItems={dockItems}
  dockActiveMode="single"
  eventsEmit={{
    onDockItemClick: (item, index) => {},
    onDockActiveChange: (activeId, item) => {}
  }}
  styles={customStyles}
>
  <YourContent />
</DockContainer>
```

## 🔧 高级配置

### 按需导入

```tsx
// 只导入需要的组件
import { Button, DropdownMenu } from '@mxmweb/zui-elements';
import { GoogleNavbar, DynamicTable } from '@mxmweb/zui-components';
import { DashboardContainer } from '@mxmweb/zui-layouts';
import { ThemeProvider } from '@mxmweb/zui-theme';
```

### TypeScript 支持

所有组件都提供完整的 TypeScript 类型定义：

```tsx
import type { 
  ButtonProps, 
  DropdownMenuAction,
  GoggleNavItem,
  DynamicTableColumn,
  Styles,
  AppTheme 
} from '@mxmweb/zui';
```

### 样式覆盖

```tsx
// 全局样式覆盖
const globalStyles = {
  theme: {
    colors: {
      primary: '#your-color'
    }
  }
};

<ThemeProvider theme={globalStyles}>
  <App />
</ThemeProvider>

// 组件级样式覆盖
<Button 
  styles={{
    theme: {
      colors: {
        primary: '#component-specific-color'
      }
    }
  }}
/>
```

## 📋 版本兼容性

| 包名 | 当前版本 | React | Node | 主要特性 |
|------|----------|-------|------|----------|
| @mxmweb/zui | 1.3.4 | >=18 <20 | >=22 | 聚合包 |
| @mxmweb/zui-theme | 2.1.3 | >=18 <20 | >=22 | 主题系统 |
| @mxmweb/zui-elements | 1.1.4 | >=18 <20 | >=22 | 基础组件 |
| @mxmweb/zui-components | 1.1.2 | >=18 <20 | >=22 | 业务组件 |
| @mxmweb/zui-layouts | 1.1.2 | >=18 <20 | >=22 | 布局容器 |

## 🛠️ 开发指南

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/mxmweb/zui.git
cd zui

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建所有包
pnpm build:all

# 发布包
pnpm publish
```

### 贡献指南

1. Fork 仓库
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 支持

- 📧 邮箱：mxm.web.develop@gmail.com
- 🐛 问题反馈：[GitHub Issues](https://github.com/mxmweb/zui/issues)

---

**ZUI** - 让 React 开发更简单、更高效！