npm package: @gavin9527/tl-components
Description: Vue 3 + TypeScript 动态表单和表格组件库，基于 Hook API
Author: gavin9527
Latest version: 1.0.1

# TL Components

Vue 3 + TypeScript 组件库，提供基于 Hook 的动态表单和表格组件。

[![npm version](https://img.shields.io/npm/v/tl-components.svg)](https://www.npmjs.com/package/tl-components)
[![license](https://img.shields.io/npm/l/tl-components.svg)](https://github.com/cca313/component-set/blob/main/LICENSE)

## 🚀 快速开始

### 安装

```bash
npm install tl-components
```

### 开发

```bash
# 安装依赖
npm install

# 启动开发服务器（自动打开 playground）
npm run dev

# 或者显式启动 playground
npm run dev:playground
```

访问 http://localhost:5173/playground/ 查看示例。

### 构建

```bash
# 构建组件库
npm run build

# 或使用别名
npm run build:lib
```

构建产物在 `dist/` 目录：
- `dist/index.js` - UMD 格式的组件库（包含 CSS）

### 预览

```bash
# 预览构建后的 playground
npm run preview
```

## 📁 项目结构

```
form-components/
├── form/                     # 表单模块
│   ├── hook.ts              # useForm hook
│   ├── index.vue            # DynamicForm 组件
│   ├── types.ts             # TypeScript 类型定义
│   ├── componentMap.ts      # 组件注册表
│   └── index.ts             # 模块导出
├── grid/                    # 表格模块
│   ├── hook.ts              # useVxeGrid hook
│   ├── index.vue            # BasicGrid 组件
│   ├── types.ts             # TypeScript 类型定义
│   └── index.ts             # 模块导出
├── playground/              # 开发测试环境
│   ├── pages/               # 示例页面
│   │   ├── Home.vue         # 首页
│   │   ├── FormBasic.vue    # 基础表单示例
│   │   ├── FormAdvanced.vue # 动态表单示例
│   │   ├── GridBasic.vue    # 基础表格示例
│   │   └── GridAdvanced.vue # 高级表格示例
│   ├── components/          # 布局组件
│   │   └── Layout.vue       # 主布局（含导航）
│   ├── router/              # 路由配置
│   │   └── index.ts         # 路由定义
│   ├── App.vue              # 根组件
│   ├── main.ts              # 入口文件
│   └── index.html           # HTML 模板
├── dist/                    # 构建输出
├── index.ts                 # 主入口（库导出）
├── vite.config.ts           # Vite 配置
├── tsconfig.json            # TypeScript 配置
└── package.json             # 项目配置
```

## 🛠️ 技术栈

- **Vue 3.4+** - 渐进式 JavaScript 框架
- **TypeScript 5.4+** - 类型安全
- **Vite 5.3+** - 构建工具
- **Vue Router 4** - 官方路由管理器
- **Element Plus 2.8+** - UI 组件库
- **VXE Table 4.17+** - 表格组件
- **@tanstack/vue-query** - 数据请求管理

## 🎮 Playground 功能

Playground 提供了一个完整的路由系统，包含多个功能演示页面：

### 页面导航

- **首页** (`/home`) - 项目介绍和快速开始
- **表单组件**
  - 基础表单 (`/form/basic`) - 展示各种表单控件的基本用法
  - 动态表单 (`/form/advanced`) - 展示动态渲染、条件显示等高级功能
- **表格组件**
  - 基础表格 (`/grid/basic`) - 展示表格的基本功能（过滤、选择等）
  - 高级表格 (`/grid/advanced`) - 展示动态列、条件显示等高级功能

### 添加新的 Demo 页面

1. 在 `playground/pages/` 创建新的 Vue 组件
2. 在 `playground/router/index.ts` 添加路由配置
3. 重启开发服务器，新页面会自动出现在导航菜单中

```typescript
// playground/router/index.ts
{
  path: '/your-feature',
  name: 'YourFeature',
  component: () => import('../pages/YourFeature.vue'),
  meta: {
    title: '你的功能',
    icon: '🎯',
  },
}
```

## 📦 使用方式

### 安装

```bash
npm install tl-components
```

### 使用 useForm

```typescript
import { useForm } from 'tl-components';

const [Form, { validate, setFieldsValue, setProps }] = useForm({
  gridCols: 2,
  schemas: [
    {
      fieldName: 'name',
      label: '姓名',
      component: 'Input',
      rules: 'required'
    }
  ]
});

// 初始 schemas 必填，component 必填
// setProps 支持 schema patch（component 可省略）
setProps({
  schemas: [
    {
      fieldName: 'name',
      label: '姓名（全名）'
    },
    {
      fieldName: 'age',
      label: '年龄',
      component: 'InputNumber'
    }
  ]
});
```

### 使用 useVxeGrid

```typescript
import { useVxeGrid } from 'tl-components';
import { VxeGrid } from 'vxe-table';

const [Grid, { reload, getCheckboxRecords }] = useVxeGrid({
  columns: [
    { field: 'name', title: '姓名' },
    { field: 'age', title: '年龄' }
  ],
  data: tableData
}, VxeGrid);
```

## 📖 文档

- [AGENTS.md](./AGENTS.md) - AI Agent 开发指南（包含完整 API 文档）
- [LIBRARY_ANALYSIS.md](./LIBRARY_ANALYSIS.md) - 架构分析和改进建议

## 🔧 配置说明

### Vite 配置

开发模式和生产构建使用不同配置：

- **开发模式** (`npm run dev`)：使用 `playground/` 作为开发环境
- **生产构建** (`npm run build`)：构建 UMD 格式的组件库到 `dist/`

### TypeScript 配置

项目使用 TypeScript strict 模式，包含以下模块：
- `form/**/*.ts`, `form/**/*.vue`
- `grid/**/*.ts`, `grid/**/*.vue`
- `playground/**/*.ts`, `playground/**/*.vue`

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT