npm package: @smart-ai/components
Description: 一个基于 Vue 3 + Element Plus 的智能组件库，提供配置驱动的表格和弹窗组件，快速构建 CRUD 页面。
Latest version: 1.1.1

# @smart-ai/components 组件库

一个基于 Vue 3 + Element Plus 的智能组件库，提供配置驱动的表格和弹窗组件，快速构建 CRUD 页面。

## 📦 安装

```bash
npm install @smart-ai/components
# 或
pnpm add @smart-ai/components
# 或
yarn add @smart-ai/components
```

## 🔧 依赖要求

组件库依赖以下包，请确保项目中已安装：

- `vue` >= 3.5.0
- `element-plus` >= 2.13.0
- `axios` >= 1.13.0
- `@element-plus/icons-vue` >= 2.3.2

## 🚀 快速开始

### 步骤 1：全局注册组件

```typescript
// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

import App from './App.vue'
import SmartAiComponents from '@smart-ai/components'
import '@smart-ai/components/dist/style.css'

const app = createApp(App)

// 注册 Element Plus（必需）
app.use(ElementPlus)

// 注册 SmartAiComponents
app.use(SmartAiComponents, {
  // 可选：配置请求钩子
  request: {
    getHeaders: () => ({
      token: 'your-token-here',
    }),
  },
  // 可选：配置表格全局选项
  table: {
    theme: 'default', // 'default' | 'spider' | 'webbas'
  },
})

app.mount('#app')
```

### 步骤 2：使用组件

#### SmartAiTable - 智能表格

```vue
<script setup lang="ts">
import { SmartAiTable } from '@smart-ai/components'
import type { SmartAiTableOptionsItf } from '@smart-ai/components'

const tableOptions: SmartAiTableOptionsItf = {
  forms: {
    props: { labelWidth: '80px' },
    children: [
      { field: 'name', label: '姓名', type: 'input' },
      {
        field: 'status',
        label: '状态',
        type: 'select',
        options: [
          { label: '启用', value: 1 },
          { label: '禁用', value: 0 },
        ],
      },
    ],
  },
  tables: {
    request: {
      url: '/api/users',
      method: 'post',
    },
    columns: [
      { prop: 'id', label: 'ID' },
      { prop: 'name', label: '姓名' },
      { prop: 'email', label: '邮箱' },
    ],
  },
}
</script>

<template>
  <SmartAiTable :options="tableOptions" />
</template>
```

#### SmartAiDialog - 智能弹窗

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { SmartAiDialog } from '@smart-ai/components'
import type { SmartAiDialogOptionsItf } from '@smart-ai/components'

const dialogVisible = ref(false)

const dialogOptions: SmartAiDialogOptionsItf = {
  title: '确认对话框',
  width: '500px',
  footerButtons: [
    {
      key: 'cancel',
      label: '取消',
      type: 'default',
      click: (done) => {
        dialogVisible.value = false
        done()
      },
    },
    {
      key: 'confirm',
      label: '确定',
      type: 'primary',
      click: () => {
        console.log('确认')
        dialogVisible.value = false
      },
    },
  ],
}
</script>

<template>
  <div>
    <el-button @click="dialogVisible = true">打开弹窗</el-button>
    <SmartAiDialog v-model="dialogVisible" :options="dialogOptions">
      <p>弹窗内容</p>
    </SmartAiDialog>
  </div>
</template>
```

## 📚 核心组件

### SmartAiTable

高度可配置化的表格组件，集成了查询表单、工具栏、数据表格和分页功能。

**主要特性：**
- 📝 配置驱动，快速生成表格页面
- 🔍 集成查询表单，支持多种表单类型
- 🛠️ 灵活配置工具栏按钮
- 📊 支持单选、多选、排序、多级表头
- 📄 内置分页处理
- 🎨 支持自定义渲染和插槽扩展

**📖 [查看完整文档](./docs/smart-ai-table.md)**

### SmartAiDialog

高度可配置化的弹窗组件，支持自定义按钮、尺寸预设、拖拽等功能。

**主要特性：**
- 🎯 配置驱动的弹窗按钮
- 📏 支持多种尺寸预设
- 🖱️ 支持拖拽功能
- 🎨 支持自定义内容和样式

**📖 [查看完整文档](./docs/smart-ai-dialog.md)**

## 🪝 Hooks

### useSelectOptions

用于管理下拉框选项的 Hook，支持静态选项、缓存选项、接口请求选项，以及联动下拉框功能。

**功能特性：**
- 支持多种数据来源（静态、缓存、接口请求）
- 支持多选模式及值的自动转换
- 支持联动下拉框（依赖其他字段值）
- 支持竞态请求处理
- 支持动态禁用和 placeholder

**使用示例：**

```typescript
import { useSelectOptions } from '@smart-ai/components'
import type { UseSelectOptionsProps, UseSelectOptionsEmit } from '@smart-ai/components'

const props = defineProps<UseSelectOptionsProps>()
const emit = defineEmits<UseSelectOptionsEmit>()

const {
  loading,
  finalOptions,
  internalValue,
  isDisabled,
  dynamicPlaceholder,
  handleUpdate,
  refreshOptions,
} = useSelectOptions(props, emit)
```

## ⚙️ 全局配置

### 请求钩子配置

```typescript
app.use(SmartAiComponents, {
  request: {
    // 自定义请求头
    getHeaders: () => ({
      Authorization: `Bearer ${token}`,
    }),
    
    // 请求参数转换
    transformRequest: (config) => {
      // 修改请求参数
      return config
    },
    
    // 响应数据转换
    transformResponse: (response) => {
      // 处理响应数据
      return response.data
    },
  },
})
```

### 表格全局配置

```typescript
app.use(SmartAiComponents, {
  table: {
    // 表格主题
    theme: 'default', // 'default' | 'spider' | 'webbas'
    
    // 全局分页配置
    pagination: {
      show: true,
      props: {
        background: true,
        pageSizes: [10, 20, 30, 40, 50],
        pageSize: 20,
      },
    },
  },
})
```

**💡 提示：** 配置优先级：组件配置 > 全局配置 > 默认配置

## 📖 类型定义

组件库提供完整的 TypeScript 类型定义：

```typescript
// 组件
import { SmartAiTable, SmartAiDialog } from '@smart-ai/components'

// 配置类型
import type {
  SmartAiTableOptionsItf,
  SmartAiDialogOptionsItf,
  SmartAiComponentsOptions,
} from '@smart-ai/components'

// Hooks 类型
import type {
  UseSelectOptionsProps,
  UseSelectOptionsEmit,
} from '@smart-ai/components'
```

## 🔗 相关文档

- 📘 [SmartAiTable 完整文档](./docs/smart-ai-table.md)
- 📘 [SmartAiDialog 完整文档](./docs/smart-ai-dialog.md)
- 🔗 [Element Plus 文档](https://element-plus.org/)

## ⚠️ 注意事项

1. **Element Plus 必需**：组件库依赖 Element Plus，使用前请确保已安装并注册
2. **样式引入**：使用组件时请确保引入样式文件 `@smart-ai/components/dist/style.css`
3. **请求钩子**：全局配置的请求钩子会影响所有使用组件库内部请求的地方
4. **TypeScript 支持**：组件库提供完整的 TypeScript 类型定义，建议在 TypeScript 项目中使用
5. **Vue 版本**：需要 Vue 3.5.0 或更高版本

## 📝 更新日志

### v1.7.0

- 新增表格全局配置：支持在全局注册时配置表格主题和分页属性
- 新增表格主题支持：支持 `'default'`、`'spider'`、`'webbas'` 三种主题
- 分页配置优化：`background` 默认值改为 `true`

### v1.0.0

- 初始版本发布
- 支持全局配置请求钩子
- 支持 SmartAiTable 和 SmartAiDialog 组件
- 完整的 TypeScript 类型定义

## 📄 许可证

MIT