@kdesigner/components

基于 AMIS UI 6.11 的现代化组件库，采用组件和 renderer 分层架构设计。

特性

• 🎨 基于 AMIS UI 6.11 - 充分利用 AMIS 的设计系统和功能基础
• 🏗️ 分层架构 - 组件层与 renderer 层解耦，提高灵活性
• 📦 TypeScript 支持 - 完整的类型定义和类型安全
• 🧪 完整测试覆盖 - 单元测试、集成测试、端到端测试
• 🔧 现代化构建 - Vite + TypeScript + ESM/CommonJS 双格式输出
• ♿ 可访问性支持 - 符合 WCAG 标准，支持键盘导航和屏幕阅读器
• 🌍 国际化支持 - 内置多语言支持机制

安装

基础安装

# 使用 pnpm（推荐）
pnpm add @kdesigner/components

# 使用 npm
npm install @kdesigner/components

# 使用 yarn
yarn add @kdesigner/components

必需依赖 (Peer Dependencies)

本组件库基于 AMIS UI 构建，需要安装以下必需依赖：

# 安装必需的 peer dependencies
pnpm add amis-ui@^6.11.0 react@^18.2.0 react-dom@^18.2.0

# 或使用 npm
npm install amis-ui@^6.11.0 react@^18.2.0 react-dom@^18.2.0

# 或使用 yarn
yarn add amis-ui@^6.11.0 react@^18.2.0 react-dom@^18.2.0

重要说明：

• amis-ui 是必需依赖，组件库基于此构建
• react 和 react-dom 版本需要保持一致
• 如果缺少这些依赖，安装后会自动提示安装指导

依赖检查

安装后会自动检查 peer dependencies，如有缺失会提供安装指导。

📚 文档

• 完整文档 - 查看所有文档
• Scripts 使用指南 - npm scripts 使用说明
• 自动化导出系统 - 自动化导出系统使用指南
• Tree Shaking 指南 - 按需引入和 Tree Shaking 配置

安装完成后，可以运行以下命令检查依赖是否正确安装：

# 检查 peer dependencies
pnpm run check-peer-deps

# 或在项目中使用
npx @kdesigner/components check-peer-deps

快速开始

import React from 'react'
import { Upload } from '@kdesigner/components'
import '@kdesigner/components/dist/style.css'

function App() {
  const handleChange = info => {
    console.log('文件上传状态变化:', info)
  }

  return (
    <div>
      <Upload
        action='/api/upload'
        onChange={handleChange}
        accept='image/*'
        maxCount={5}
      >
        <button>点击上传</button>
      </Upload>
    </div>
  )
}

export default App

组件列表

当前可用组件

• Upload - 文件上传组件（开发中）
  • 支持多种上传方式（拖拽、点击选择、粘贴）
  • 文件类型和大小限制
  • 上传进度显示和错误处理
  • 自定义上传逻辑支持

计划中的组件

• Button - 按钮组件
• Input - 输入框组件
• Select - 选择器组件
• Form - 表单组件
• Modal - 模态框组件
• Table - 表格组件

架构设计

分层架构

┌─────────────────────────────────────┐
│           Renderer 层               │
│        (其他包中实现)                │
├─────────────────────────────────────┤
│           组件层 (本包)              │
│     纯组件实现，不包含 renderer      │
├─────────────────────────────────────┤
│           AMIS 基础层               │
│      基于 AMIS UI 6.11 构建         │
└─────────────────────────────────────┘

目录结构

src/
├── components/          # 组件目录
│   ├── Upload/          # Upload 组件
│   └── index.ts         # 组件统一导出
├── hooks/               # 全局自定义 hooks
├── utils/               # 全局工具函数
├── types/               # 全局类型定义
├── styles/              # 全局样式
│   ├── variables.scss   # SCSS 变量
│   ├── mixins.scss      # SCSS 混入
│   └── index.scss       # 样式入口
├── core/                # 核心功能
└── index.ts             # 库入口文件

开发

环境要求

• Node.js >= 18.0.0
• pnpm >= 8.15.0
• TypeScript >= 5.3.0

开发命令

# 安装依赖
pnpm install

# 开发模式（监听文件变化）
pnpm dev

# 构建
pnpm build

# 运行测试
pnpm test

# 运行测试（监听模式）
pnpm test:watch

# 测试覆盖率
pnpm test:coverage

# 代码检查
pnpm lint

# 代码检查并修复
pnpm lint:fix

# 代码格式化
pnpm format

# 检查代码格式
pnpm format:check

# 类型检查
pnpm type-check

# 质量检查（包含 lint + type-check + test）
pnpm quality-check

# 验证构建产物
pnpm verify:build

# 验证导出配置
pnpm verify:exports

# 验证类型定义
pnpm verify:types

# 检查构建完整性
pnpm check:integrity

# 检查 peer dependencies
pnpm check:peer-deps

测试

组件库使用 Vitest 作为测试框架，配合 @testing-library/react 进行组件测试。

# 运行所有测试
pnpm test

# 运行特定测试文件
pnpm test Upload.test.tsx

# 生成测试覆盖率报告
pnpm test:coverage

测试覆盖率要求：

• 整体覆盖率：≥ 90%
• 语句覆盖率：≥ 90%
• 分支覆盖率：≥ 85%
• 函数覆盖率：≥ 90%

构建产物

构建后将生成以下文件：

dist/
├── index.esm.js          # ES 模块版本
├── index.esm.js.map      # ES 模块 source map
├── index.cjs.js          # CommonJS 版本
├── index.cjs.js.map      # CommonJS source map
├── index.d.ts            # TypeScript 类型定义
├── style.css             # 样式文件
└── style.css.map         # 样式 source map

代码质量

ESLint 配置

使用 @kdesigner/eslint-config (auto 包) 进行智能代码检查：

// eslint.config.js
import autoConfig from '@kdesigner/eslint-config'

export default [
  ...autoConfig
  // 项目特定规则
]

TypeScript 配置

启用严格模式，确保类型安全：

{
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}

贡献指南

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启 Pull Request

开发规范

• 所有新功能必须包含测试
• 遵循 TypeScript 严格模式
• 使用语义化提交消息
• 确保代码通过 ESLint 检查
• 更新相关文档

许可证

MIT License - 详见 LICENSE 文件。

更新日志

详见 CHANGELOG.md。

支持

• 📖 文档
• 🐛 问题反馈
• 💬 讨论区
• 📧 邮件支持