@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
代码质量
代码检查（oxlint）
使用 oxlint 进行代码检查（配置来自仓库根目录 oxlint.config.ts）：
pnpm lint # 检查代码
pnpm lint:fix # 自动修复
TypeScript 配置
启用严格模式，确保类型安全：
{
"compilerOptions": {
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true
}
}
贡献指南
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m 'Add some amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 开启 Pull Request
开发规范
- 所有新功能必须包含测试
- 遵循 TypeScript 严格模式
- 使用语义化提交消息
- 确保代码通过 oxlint 检查
- 更新相关文档
许可证
MIT License - 详见 LICENSE 文件。
更新日志
详见 CHANGELOG.md。