TL Components

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

🚀 快速开始

安装

npm install tl-components

开发

# 安装依赖
npm install

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

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

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

构建

# 构建组件库
npm run build

# 或使用别名
npm run build:lib

构建产物在 dist/ 目录：

• dist/index.js - UMD 格式的组件库（包含 CSS）

预览

# 预览构建后的 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. 重启开发服务器，新页面会自动出现在导航菜单中

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

📦 使用方式

安装

npm install tl-components

使用 useForm

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

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 - AI Agent 开发指南（包含完整 API 文档）
• 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