@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) - 图标组件包

🚀 快速开始

安装

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

依赖要求

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

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

可选依赖（根据使用的组件）：

{
  "dependencies": {
    "animejs": "^3.0.0",           // 动画组件需要
    "antd": "^5.0.0",              // 表单组件需要
    "lucide-react": "^0.456.0"     // 图标组件需要
  }
}

基础使用

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. 默认主题 - 基础优先级

主题配置

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 按钮

import { Button } from '@mxmweb/zui';

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

DropdownMenu 下拉菜单

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 导航栏

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 动态表格

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 文件上传

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 仪表板容器

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 全屏容器

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>

🔧 高级配置

按需导入

// 只导入需要的组件
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 类型定义：

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

样式覆盖

// 全局样式覆盖
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 | 布局容器 |

🛠️ 开发指南

本地开发

# 克隆仓库
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 文件

🤝 支持

• 📧 邮箱：[email protected]
• 🐛 问题反馈：GitHub Issues

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