# Gushen 前端组件规则

本工程依赖：

- `@gushen/gushen-common-components`
- `@gushen/gushen-form-render`

当前目标工程未安装 `@gushen/gushen-work-flow`。如果需求涉及工作流组件（如 `flow-container`、`flow-ea-buttons`、`flow-commit`），先确认依赖、注册方式和运行时子应用边界，不要直接生成组件用法。

使用组件前，优先读取组件源码：`node_modules/@gushen/gushen-common-components/src/packages/components`。

## 全局注册

`src/core/initMain.ts` 已执行：

```ts
import GsComponents from '@gushen/gushen-common-components'
instance.use(GsComponents)
```

因此 `gs-*` 公共组件可直接在模板中使用。当前本地全局组件仅包含 `GsIconDialog`、`GsIcon`、`SvgIcon`、`UploadImg`，注册位置为 `src/components/global-register.ts`。

常见公共组件分类：

- 表格：`GsTable`、`GsCustomizeTable`、`GsVxeTable`、`GsSuperTable`
- 查询/输入：`GsSearchBar`、`GsInput`、`GsSelect`、`GsRadio`、`GsSwitch`
- 选择器：`GsSelectTreeTable`、`GsPersonnelSelector`、`GsDepartmentSelector`、`GsPageSelect`、`GsDialogSelector`
- 上传/导入导出：`GsUpload`、`GsAttachmentList`、`UploadImg`、`GsImportData`、`GsExportData`
- 弹层/布局：`GsDialog`、`GsDrawer`、`GsCard`、`GsGridLayout`

## `GsCustomizeTable` / `gs-table`

源码路径：`node_modules/@gushen/gushen-common-components/src/packages/components/GsCustomizeTable`。

### 推荐用途

- 后端分页列表页。
- 需要列设置、表头查询、刷新、导入导出、关键字搜索的业务列表。
- 页面模板统一从 `page-template-index.md` 选择；本规则只说明组件 API 和约束。

### 核心配置

组件级常用 props：

- `gridConfig`：核心表格配置，和源码 `defaultConfig()` 合并。
- `queryParams`：请求参数，常见结构为 `{ params: { pageIndex, pageRows, params: {} }, queryUrl }`。
- `fixedParams`：固定参数，搜索重置时保留。
- `tableParams`：表头搜索附加参数。
- `method`：请求方法，默认 `post`。
- `tableHeight` / `maxHeight`：高度控制。
- `reserveSelection`：跨页保留勾选，需配合 `rowKey`。
- `readonly`：只读禁用交互。
- `isParamsOutSearch`：为 true 时抛出 `paramsOutSearch`，由父组件接管请求。
- `reqBeforeHandler` / `resDataHandler`：请求前和响应数据处理钩子。

常用顶层配置来自 `common/defaultConfig.js`：

- `columns`：列配置。
- `queryUrl`：远程查询接口。
- `selectable`：是否显示勾选列。
- `showIndex`：是否显示序号列。
- `slotArr`：需要自定义插槽渲染的列字段。
- `needPagination` / `paged`：是否分页。
- `hideSearchBtn`：是否隐藏表头查询切换。
- `showSetting`：是否显示列设置。
- `showRefresh`：是否显示刷新按钮。
- `importable` / `exportable`：是否启用导入导出。
- `enableCustomizeFilter`：是否启用高级筛选。
- `isVirtualList`：是否启用虚拟滚动。
- `localstorageName`：列设置缓存 key。
- `rowKey`：跨页勾选、虚拟列表建议设置，默认常用 `id`。
- `showKeyWordSearch`：是否显示关键字搜索。
- `isScrollRequest`：是否启用滚动加载。

列默认配置来自 `common/columnDefaultConfig.js`：

- `prop`、`label`、`width`、`align`、`headerAlign`、`fixed`。
- `isShow`、`hidden`、`hiddenFlag` 控制显示。
- `sortable` 默认 `true`。
- `showOverflowTooltip` 默认 `true`。
- `dataType` 默认 `string`。
- `dictCode` 可配合字典数据做显示转换。
- `list` 可提供下拉选项。
- `component`、`componentAttr`、`list` 可用于表头搜索控件。
- `sortableType: 'all'` 表示远程排序。
- `hideSearh` 用于禁用表头搜索（源码拼写如此）。

### 插槽

- `#table-title`：表格标题。
- `#btn`：表格头部左侧按钮。
- `#btn-r`：头部浮动按钮区域。
- `#expand`：展开行。
- `#pager`：自定义分页区域。
- 字段插槽：字段名必须加入 `slotArr`，例如 `slotArr: ['readStatus', 'action']` 后可写 `#readStatus`、`#action`。

### 事件

常用事件：

- `@inited`：表格初始化完成，返回表格实例。
- `@updateTableData`：表格数据更新。
- `@update:tableTotal`：总数更新。
- `@requestError`：请求异常。
- `@pageChange`、`@sizeChange`：分页变化。
- `@row-click`：行点击。
- `@select-all`：全选变化。
- `@sort-change`：排序变化。
- `@header-dragend`：列宽拖拽结束。
- `@needSearchChange`：表头查询开关变化。
- `@paramsOutSearch`：外部接管查询参数。
- `@import-success`、`@exportSuccess`：导入导出成功。

### 实例方法

通过 `ref` 可调用：

- `refresh(hasLoading, isClearSelection = true)`：刷新数据。
- `getData(...)`：按当前配置查询。
- `outSearch(isKeepPage?, noLike?, hasLoading?, index?)`：外部搜索条件变化后触发查询。
- `tableSearch(isKeepPage?, index?)`：表头查询。
- `getSelection()`：获取勾选行。
- `setRowSelection(row, flag, key?)`：切换指定行选中。
- `getCurrentParams()`：获取当前请求参数。
- `resetTable()` / `init()` / `doTableLayout()`：重置、初始化、重排布局。
- `setFirstRow()`：选中首行并触发 `getfirstdata`。

### 生成代码约束

- 普通值展示优先使用列配置和 `dictCode`，不要为了纯文本显示滥用插槽。
- 需要 `el-tag`、按钮、链接、富文本等复杂渲染时，字段必须加入 `slotArr`。
- 操作列使用 `prop: 'action'`、`fixed: 'right'`，并加入 `slotArr`。
- 表头查询字段使用 `component`、`componentAttr`、`list`；字典字段优先配置 `dictCode`。
- 每个列表页设置唯一 `localstorageName`，避免列设置缓存串页。
- 外部查询条件变化后更新 `queryParams.params.params`，再调用 `tableRef.value?.outSearch(false)`；普通刷新调用 `tableRef.value?.refresh(true)`。
- 勾选场景必须设置 `rowKey`。

## `GsTable`

源码路径：`node_modules/@gushen/gushen-common-components/src/packages/components/GsTable/index.vue`。

- 适合简单本地或远程表格。
- `columns` 控制列，`options`/工具配置控制搜索、刷新、列设置、选择列、序号列、加减行。
- `#header` 放头部按钮，`#cell` 用于可编辑或自定义单元格。
- 旧代码中 `<gs-table :columns="columns" :options="options" :remote="remoteData">` 是可参考写法。

## `GsSearchBar`

源码路径：`node_modules/@gushen/gushen-common-components/src/packages/components/GsSearchBar/index.vue`。

- `searchConfig.items` 描述查询项，字段名使用 `field`。
- `fixedParams` 会合并进查询参数。
- `btnPosition` 支持 `top` / `bottom`。
- 查询项 `type` 直接映射 Element Plus 组件，如 `el-input`、`el-select`、`el-cascader`。
- `el-select` 的选项使用 `options: [{ label, value }]`。
- `#prepend`、`#append` 可插入按钮。
- 事件：`@search="handleSearch"`、`@reset="handleReset"`、`@expand="handleExpand"`。
- 可通过实例方法 `setFormItemValue(field, value)` 设置查询字段。

## 上传与图片

- 本地全局 `UploadImg` 来自 `src/components/UploadImg/index.vue`。
- 公共组件库也提供 `GsUpload`、`UploadImg`，使用前对照源码确认事件和字段。
- 文件上传 API 参考 `src/api/attachment.ts` 和 `src/components/GsUpload`。

## 动态表单

- 依赖 `@gushen/gushen-form-render` 已安装。
- 动态表单组件来自 `@gushen/gushen-form-render`，常用注册名是 `FormRender` / `<form-render>`；不存在 `GsForm` 业务组件。
- 当前 `src/core/initMain.ts` 中插件注册是注释状态；新增 `<FormRender />` 前，先确认是否需要解除注释：
  - `import GushenFormRender from '@gushen/gushen-form-render'`
  - `import '@gushen/gushen-form-render/lib/gushen-form-render.css'`
  - `instance.use(GushenFormRender)`
- 现有动态表单入口：`src/views/dynamic-form/index.vue`。