# G. 前端组件速查

:::tip 概述
公共组件定义在 `ui/src/components/` 目录下。其中 `PageWrapper`、`PageFooter`、`BasicTable`、`BasicForm`、`NumberInput`、`PriceInput`、`pagination`、`icon` 已在 `ui/src/plugins/customComponents.ts` 中**全局注册**，模板里可直接使用；其余组件按需 import。
:::

## 全局注册组件

以下组件由 `setupCustomComponents(app)` 注册，无需 import：

| 组件 | 来源 | 说明 |
|------|------|------|
| `PageWrapper` / `PageFooter` | `components/Page/` | 页面容器 / 页脚 |
| `BasicTable` | `components/Table/` | 数据表格（通过 props 传数据） |
| `BasicForm` | `components/Form/` | 动态表单（配合 `useForm` 的 register） |
| `NumberInput` | `components/numberInput/` | 数字输入 |
| `PriceInput` | `components/numberInput/` | 价格输入 |
| `pagination` | `components/pagination/` | 分页 |
| `icon` | `components/icon/` | 图标 |

## 数据展示

| 组件 | 路径 | 说明 | 引入方式 |
|------|------|------|---------|
| BasicTable | `components/Table/` | 数据表格（含 TableAction 行操作） | 全局注册 |
| PageWrapper | `components/Page/` | 页面容器 | 全局注册 |
| CountTo | `components/CountTo/` | 数字动画 | 按需 import |
| Qrcode | `components/Qrcode/` | 二维码 | 按需 import |
| TableSelect | `components/TableSelect/` | 表格选择器 | 按需 import |

## 数据录入

| 组件 | 路径 | 说明 | 引入方式 |
|------|------|------|---------|
| BasicForm | `components/Form/` | 动态表单（`useForm` hook） | 全局注册 |
| BasicSelect | `components/Select/` | 选择器 | 按需 import |
| BasicUpload | `components/Upload/` | 文件上传 | 按需 import |
| UploadImg / UploadImages | `components/Upload/Image.vue`、`Images.vue` | 图片/多图上传（生成页面 edit.vue 使用） | 按需 import |
| Editor | `components/Editor/` | 富文本编辑器（TinyMCE） | 按需 import |
| Password | `components/Password/` | 密码强度 | 按需 import |
| ChinaArea | `components/ChinaArea/` | 省市区联动 | 按需 import |
| Region | `components/Region/` | 行政区划 | 按需 import |
| Cropper | `components/Cropper/` | 头像裁剪 | 按需 import |
| NumberInput / PriceInput | `components/numberInput/`、`priceInput/` | 数字 / 价格输入 | 全局注册 |

## Excel 与导入导出

| 组件 | 路径 | 说明 |
|------|------|------|
| importFile | `components/importFile/index.vue` | 导入对话框（`api` + `templateCode`，下载模板 + 上传解析一体化） |
| ImpExcel | `components/Excel/` | Excel 导入解析组件 |
| jsonToSheetXlsx / aoaToSheetXlsx | `components/Excel/src/Export2Excel.ts` | Excel 导出（前端生成文件） |
| 导出接口 | `GET /api/{module}/export` | 后端生成文件（`ExcelService`），生成页面统一走此接口 |

## 其他

| 组件 | 路径 | 说明 |
|------|------|------|
| Authority | `components/Authority/` | 权限组件（根据权限显示/隐藏） |
| CheckToken | `components/CheckToken/` | Token 校验组件 |
| Lockscreen | `components/Lockscreen/` | 锁屏组件 |
| Websocket | `components/Websocket/` | WebSocket 组件 |
| Render | `components/Render/` | 函数式渲染组件 |

## 使用示例

### BasicForm（配合 useForm，摘自 `views/tool/example/index.vue`）

```vue
<template>
  <BasicForm @register="register" @submit="handleSubmit" @reset="handleReset" />
</template>

<script setup>
import { useForm } from '@/components/Form/index';
import { schemas } from './querySchemas';

const [register, { getFieldsValue }] = useForm({
  schemas,
  labelWidth: 80,
});
</script>
```

### BasicTable（props 传数据，摘自 `views/tool/example/index.vue`）

```vue
<template>
  <BasicTable
    :columns="columns"
    :request="loadDataTable"
    :row-key="(row) => row.id"
    ref="tableRef"
    :actionColumn="actionColumn"
    @selection-change="onSelectionChange"
  >
    <template #tableTitle>
      <el-button type="primary" @click="handleAdd" v-perm="['sys:example:add']">
        添加案例演示
      </el-button>
    </template>
  </BasicTable>
</template>

<script setup>
import { TableAction } from '@/components/Table';
import { getExamplePage } from '@/api/tool/example';
import { columns } from './columns';

// 分页请求函数（返回 {records, total, current, size, pages}）
const loadDataTable = (params) => getExamplePage(params);
</script>
```

:::info 没有 useTable hook
本项目 `BasicTable` 通过 `:request` 传入分页请求函数，行操作用 `TableAction` 组件，无需 `useTable` 注册模式。
:::

### 行操作列（TableAction）

```typescript
import { TableAction } from '@/components/Table';

const actionColumn = {
  width: 200,
  title: '操作',
  dataIndex: 'action',
  slots: { customRender: 'action' },
};
```

### 导入对话框（importFile）

```vue
<fileUpload
  v-if="importVisible"
  v-model:visible="importVisible"
  api="/api/example/import"
  templateCode="example_import"
  @success="fetchData"
/>
```

（`templateCode` 对应文件模板表 `file_template` 中的模板编码，用于提供 Excel 下载模板。）