# @kdesigner/components 中文文档

规范地址：https://npmcn.com/package/%40kdesigner/components/

版本：0\.0\.1
npm 元数据更新时间：2026-11-01T13:16:20.449Z
中文译文更新时间：2026-11-01T15:18:11.821Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40kdesigner/components
原文对照：https://npmcn.com/package/%40kdesigner/components/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：159 kB，43 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：react ^18\.2\.0，react-dom ^18\.2\.0，classnames ^2\.5\.1
- 首次发布：2025-08-24T11:29:23.219Z
- 最新版本发布：2026-11-01T13:16:20.253Z
- 已发布版本数：6（近 12 个月 3 个）

## 中文简介

KDesigner通用组件库，支持React和Vue

## 安装

```sh
npm install @kdesigner/components
```

也可以使用：`pnpm add @kdesigner/components`、`yarn add @kdesigner/components`、`bun add @kdesigner/components`

## README

# @kdesigner/components

![License](https://img.shields.io/badge/license-MIT-blue.svg) ![TypeScript](https://img.shields.io/badge/typescript-%5E5.9.2-blue.svg) ![React](https://img.shields.io/badge/React-18.x-61DAFB.svg)

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

## 特性

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

## 安装

### 基础安装

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

# 使用 npm
npm install @kdesigner/components

# 使用 yarn
yarn add @kdesigner/components
```

### 必需依赖 (Peer Dependencies)

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

```bash
# 安装必需的 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，如有缺失会提供安装指导。

## 📚 文档

-   [完整文档](https://npmcn.com/package/%40kdesigner/components/docs/README.md) - 查看所有文档
-   [Scripts 使用指南](https://npmcn.com/package/%40kdesigner/components/docs/SCRIPTS.md) - npm scripts 使用说明
-   [自动化导出系统](https://npmcn.com/package/%40kdesigner/components/docs/AUTO_EXPORTS.md) - 自动化导出系统使用指南
-   [Tree Shaking 指南](https://npmcn.com/package/%40kdesigner/components/docs/TREE_SHAKING.md) - 按需引入和 Tree Shaking 配置

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

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

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

## 快速开始

```tsx
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

### 开发命令

```bash
# 安装依赖
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 进行组件测试。

```bash
# 运行所有测试
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`）：

```bash
pnpm lint        # 检查代码
pnpm lint:fix    # 自动修复
```

### TypeScript 配置

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

```json
{
  "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 严格模式
-   使用语义化提交消息
-   确保代码通过 oxlint 检查
-   更新相关文档

## 许可证

MIT License - 详见 [LICENSE](https://npmcn.com/package/LICENSE) 文件。

## 更新日志

详见 [CHANGELOG.md](https://npmcn.com/package/%40kdesigner/components/CHANGELOG.md)。

## 支持

-   📖 [文档](https://kdesigner.dev/components)
-   🐛 [问题反馈](https://github.com/kdesigner/kdesigner/issues)
-   💬 [讨论区](https://github.com/kdesigner/kdesigner/discussions)
-   📧 [邮件支持](mailto:support@kdesigner.dev)

## 常见问题

### @kdesigner/components 是什么？

KDesigner通用组件库，支持React和Vue

### 如何安装 @kdesigner/components？

在项目目录运行 npm install @kdesigner/components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0）、react-dom（^18\.2\.0）、classnames（^2\.5\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @kdesigner/components 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @kdesigner/components 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @kdesigner/components 可以商用吗？

@kdesigner/components 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @kdesigner/components 还在维护吗？

最新版本 0\.0\.1 发布于 2026/11/01（1 天前）；至今共发布 6 个版本，其中过去 12 个月发布了 3 个；首次发布于 2025/08/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。