ylwl-cpscoms 1.1.0 → 1.2.0

package/src/SlPage/README.md

@@ -1,515 +0,0 @@
-# SlPage 组件使用说明
-
-本文基于当前实现文件 `src/components/global/SlPage/index.vue`、`src/components/global/SlTable/index.vue`、`src/components/global/SlForm/index.vue` 整理，适用于本项目现有的 Vue 2 + Element UI 体系。
-
-## 1. 组件定位
-
-`SlPage` 是一个页面级组合组件，用来把以下能力封装到一起：
-
-- 查询表单
-- 表格列表
-- 分页
-- 左右工具按钮插槽
-- 列显隐和列顺序设置
-- 查询参数与表格请求的衔接
-
-从职责上看，它本质上是 `SlForm + SlTable + 列设置` 的统一壳组件，适合大部分“筛选 + 列表”的后台页面。
-
-## 2. 内部结构
-
-`SlPage` 的模板结构可以概括为：
-
-1. 顶部 `slForm`
-2. 查询/重置/展开折叠按钮
-3. 表格头部左右插槽
-4. `slTable`
-5. 列设置抽屉
-
-组件内部关键行为：
-
-- `form` 作为查询表单模型，通过 `v-model` 绑定给 `SlForm`
-- `form` 作为 `params` 继续传给 `SlTable`
-- 点击“搜索”时先校验表单，再把页码切到第 1 页并发起请求
-- 点击“重置”时重置表单并重新请求
-- 列配置会按 `tableApi.toString()` 生成唯一 key，保存在 `localStorage.colConfig`
-
-## 3. 最小用法
-
-```vue
-<template>
-  <SlPage
-    ref="slPage"
-    :table-api="getListApi"
-    :auto-request="true"
-    :table-columns="columns"
-    :filter-form="filterForm"
-    :show-form-item="5"
-    :init-seach-params="initSeachParams"
-    :default-seach-params="defaultSeachParams"
-    :project-from="'ares'"
-    :other-config="otherConfig"
-    @callback="handleCallback"
-    @sortChangeByApi="handleSortChange"
-  >
-    <template slot="tableLeftButtons" slot-scope="{ tablefilterFormData }">
-      <el-button size="small" type="primary" @click="handleCreate">新增</el-button>
-      <el-button size="small" @click="handleExport(tablefilterFormData)">导出</el-button>
-    </template>
-
-    <template slot="operate" slot-scope="{ row }">
-      <el-button type="text" size="mini" @click="handleDetail(row)">详情</el-button>
-    </template>
-  </SlPage>
-</template>
-
-<script>
-import SlPage from '@/components/global/SlPage'
-import { getListApi } from '@/api/xxx'
-
-export default {
-  components: { SlPage },
-  data() {
-    return {
-      getListApi,
-      initSeachParams: {
-        timer: []
-      },
-      defaultSeachParams: {
-        status: 1
-      },
-      otherConfig: {
-        rowKey: 'id',
-        requestBodyCof: {
-          currentPage: 'pageNo',
-          pageSize: 'pageSize'
-        },
-        responderCof: {
-          statusCode: 'code',
-          list: ['data', 'list'],
-          total: ['data', 'total']
-        }
-      },
-      filterForm: [
-        {
-          label: '玩家账号',
-          type: 'input',
-          model: 'account'
-        },
-        {
-          label: '时间',
-          type: 'datePicker',
-          model: 'timer',
-          privateProps: {
-            type: 'daterange',
-            valueFormat: 'yyyy-MM-dd HH:mm:ss'
-          },
-          callback: (val) => ({
-            beginTime: val[0],
-            endTime: val[1],
-            timer: val
-          })
-        }
-      ],
-      columns: [
-        { prop: 'account', label: '玩家账号', minWidth: '140' },
-        { prop: 'amount', label: '金额', minWidth: '120', sortable: true },
-        { prop: 'operate', label: '操作', fixed: 'right', template: 'operate' }
-      ]
-    }
-  },
-  methods: {
-    handleCreate() {},
-    handleDetail(row) {},
-    handleExport(params) {},
-    handleCallback(payload) {},
-    handleSortChange(payload) {}
-  }
-}
-</script>
-```
-
-## 4. Props 说明
-
-| 参数                 | 类型       | 默认值       | 说明                                                         |
-| -------------------- | ---------- | ------------ | ------------------------------------------------------------ |
-| `tableApi`           | `Function` | `() => ({})` | 表格请求方法，`SlTable` 会把分页参数和处理后的查询参数一起传入 |
-| `autoRequest`        | `Boolean`  | `false`      | 组件挂载后是否自动请求一次                                   |
-| `tableColumns`       | `Array`    | `[]`         | 表格列配置                                                   |
-| `filterForm`         | `Array`    | `[]`         | 查询表单配置，实际由 `SlForm` 渲染                           |
-| `showFormItem`       | `Number`   | `3`          | 默认展示的筛选项数量阈值，超出后可展开/折叠                  |
-| `projectFrom`        | `String`   | `'oldCpsb'`  | 请求参数格式化策略，当前主要区分 `'ares'` 和其它值           |
-| `initSeachParams`    | `Object`   | `{}`         | 初始化时写入表单模型的查询参数                               |
-| `defaultSeachParams` | `Object`   | `{}`         | 请求时额外合并的默认参数，不直接显示在表单中                 |
-| `isShowColSetting`   | `Boolean`  | `true`       | 是否显示“列设置”按钮                                         |
-| `notShowPadding`     | `Boolean`  | `false`      | 是否去掉外层 `main` 的 `padding: 20px`                       |
-| `otherConfig`        | `Object`   | 见源码       | 透传给 `SlTable` 的附加配置，如主键、响应结构、请求字段名等  |
-
-补充说明：
-
-- `initSeachParams`、`defaultSeachParams` 在源码里拼写就是 `Seach`，使用时需要按当前命名传参。
-- `SlPage` 会把未声明的属性和事件通过 `v-bind="$attrs"`、`v-on="$listeners"` 继续透传给 `SlTable`。
-- 因此像 `show-summary`、`summary-method`、`row-class-name` 等 `el-table` / `SlTable` 相关能力，都可以直接挂在 `SlPage` 上使用。
-
-## 5. `otherConfig` 说明
-
-最常用的几个配置如下：
-
-```js
-otherConfig: {
-  rowKey: 'id',
-  requestBodyCof: {
-    currentPage: 'pageNo',
-    pageSize: 'pageSize'
-  },
-  responderCof: {
-    statusCode: 'code',
-    list: ['data', 'list'],
-    total: ['data', 'total']
-  },
-  donShowOverflowTooltip: true
-}
-```
-
-字段含义：
-
-- `rowKey`：表格行主键，默认是 `id`
-- `requestBodyCof.currentPage`：请求页码字段名映射
-- `requestBodyCof.pageSize`：请求每页条数字段名映射
-- `responderCof.statusCode`：响应码字段路径
-- `responderCof.list`：列表字段路径
-- `responderCof.total`：总数字段路径
-- `donShowOverflowTooltip`：是否关闭默认溢出提示
-
-## 6. `filterForm` 配置要点
-
-`SlPage` 不直接解析筛选项，而是把 `filterForm` 全量交给 `SlForm`。项目中常见字段包括：
-
-| 字段                                      | 说明                                                       |
-| ----------------------------------------- | ---------------------------------------------------------- |
-| `label`                                   | 表单项名称                                                 |
-| `type`                                    | 控件类型，如 `input`、`select`、`datePicker`、`rangeInput` |
-| `model`                                   | 绑定到 `form` 的字段名                                     |
-| `rules`                                   | Element 表单校验规则                                       |
-| `props` / `privateProps` / `privateAttrs` | 透传给具体控件的属性                                       |
-| `options`                                 | 静态下拉选项                                               |
-| `asycnOptions`                            | 异步获取下拉选项的方法                                     |
-| `callback`                                | 用于把一个控件值拆分成多个请求字段                         |
-| `linkSet`                                 | 联动设置后续筛选项，例如平台联动游戏、游戏联动区服         |
-| `show`                                    | 控制项是否显示                                             |
-
-典型配置：
-
-```js
-{
-  label: '申请时间',
-  type: 'datePicker',
-  model: 'timer',
-  privateProps: {
-    type: 'daterange',
-    valueFormat: 'yyyy-MM-dd HH:mm:ss'
-  },
-  callback: (val) => ({
-    beginTime: val[0],
-    endTime: val[1],
-    timer: val
-  }),
-  rules: [{ required: true, message: '请选择时间', trigger: 'change' }]
-}
-```
-
-## 7. `tableColumns` 配置要点
-
-`tableColumns` 最终由 `SlTable` 渲染。项目里常用字段包括：
-
-| 字段                 | 说明                                   |
-| -------------------- | -------------------------------------- |
-| `prop`               | 列字段名                               |
-| `label`              | 列标题                                 |
-| `width` / `minWidth` | 列宽                                   |
-| `fixed`              | 固定列                                 |
-| `sortable`           | 是否支持排序                           |
-| `isShow`             | 是否显示该列，列设置也依赖该字段       |
-| `isAlwaysShow`       | 控制列是否允许出现在列设置和实际渲染中 |
-| `type`               | 特殊列类型，如 `selection`、`index`    |
-| `template`           | 使用插槽渲染单元格                     |
-| `render`             | 返回 HTML 字符串，通过 `v-html` 渲染   |
-| `tip`                | 行内提示配置                           |
-| `headerTip`          | 表头提示配置                           |
-| `list`               | `operate` 操作列按钮集合               |
-| `isSwitchNumber`     | 接口字段需要转数字时使用               |
-
-操作列示例：
-
-```js
-{
-  prop: 'operate',
-  label: '操作',
-  fixed: 'right',
-  list: [
-    {
-      label: '编辑',
-      click: (row) => {
-        console.log(row)
-      }
-    }
-  ]
-}
-```
-
-插槽列示例：
-
-```js
-{ prop: 'operate', label: '操作', template: 'operate' }
-```
-
-```vue
-<template slot="operate" slot-scope="{ row }">
-  <el-button type="text" size="mini" @click="handleDetail(row)">详情</el-button>
-</template>
-```
-
-## 8. 插槽
-
-### 8.1 页面级插槽
-
-| 插槽名              | 作用域参数                | 说明               |
-| ------------------- | ------------------------- | ------------------ |
-| `tableLeftButtons`  | `{ tablefilterFormData }` | 表格头部左侧按钮区 |
-| `tableRightButtons` | `{ tablefilterFormData }` | 表格头部右侧按钮区 |
-
-其中 `tablefilterFormData` 来自 `SlTable.processedParams`，是已经按项目规则处理后的请求参数，适合直接拿去做导出。
-
-### 8.2 表格列插槽
-
-`SlPage` 会把你在外层定义的具名插槽继续转发给 `SlTable`。常见用法是给列模板提供自定义单元格内容。
-
-当前转发时只透出：
-
-```js
-{ row }
-```
-
-也就是说，外部插槽默认拿不到 `column`、`$index` 等更多上下文。
-
-## 9. 事件
-
-`SlPage` 自身没有额外 `emit` 很多事件，但它会透传 `SlTable` 的事件，因此常用事件仍然可以直接绑定在 `SlPage` 上：
-
-| 事件名               | 说明                                               |
-| -------------------- | -------------------------------------------------- |
-| `callback`           | 请求成功后回调，参数内含接口响应和本次完整请求参数 |
-| `sortChangeByApi`    | 表格排序变化时触发                                 |
-| 其它 `el-table` 事件 | 例如行点击、选择变化等，视 `SlTable` 转发情况使用  |
-
-`callback` 参数结构示例：
-
-```js
-{
-  apiInfo: res,
-  allRequestParams: {
-    currentPage: 1,
-    pageSize: 10,
-    ...processedParams
-  }
-}
-```
-
-## 10. 通过 `ref` 可用的能力
-
-业务页面通常会给组件加 `ref="SlPage"`，这样可以直接访问一些内部能力。
-
-常见读取方式：
-
-```js
-this.$refs.SlPage.form
-this.$refs.SlPage.selectedList
-this.$refs.SlPage.selectedListIds
-```
-
-常见调用方式：
-
-```js
-this.$refs.SlPage.searchTableData()
-this.$refs.SlPage.resetTableData()
-this.$refs.SlPage.getTableData()
-```
-
-如果需要更底层能力，也可以继续访问：
-
-```js
-this.$refs.SlPage.$refs.slForm
-this.$refs.SlPage.$refs.slTable
-```
-
-## 11. 请求参数处理规则
-
-请求最终由 `SlTable.processedParams` 统一加工，规则如下。
-
-### 11.1 通用规则
-
-- 最终请求参数 = `form + defaultSeachParams`
-- 如果筛选项是日期范围，并配置了 `callback`，会把范围拆成多个字段
-
-### 11.2 `projectFrom === 'ares'`
-
-- 多选下拉保留为数组
-- `datePicker` 的 `daterange` 会执行 `callback` 并删除原始 `model`
-- 普通 `datePicker` 和 `rangeInput` 会删除原始 `model`
-
-### 11.3 其它项目来源
-
-- 多选下拉会转成英文逗号拼接字符串
-- `datePicker` 的 `daterange` 会执行 `callback` 并删除原始 `model`
-- 普通 `datePicker` 会删除原始 `model`
-
-## 12. 列设置与持久化
-
-开启 `isShowColSetting` 后，右上角会出现“列设置”按钮。
-
-当前实现行为：
-
-1. 点击后打开抽屉
-2. 允许拖拽排序和显隐控制
-3. 排序结果保存到 `localStorage.colConfig`
-4. 隐藏列结果也保存到 `localStorage.colConfig`
-
-存储结构依赖 `src/store/modules/tableConfig.js`，格式大致如下：
-
-```js
-{
-  [uniqueId]: {
-    sort: ['colA', 'colB'],
-    hide: ['colC']
-  }
-}
-```
-
-其中 `uniqueId` 来自：
-
-```js
-generateUniqueId(this.tableApi.toString())
-```
-
-## 13. 真实项目里的典型场景
-
-当前项目里，`SlPage` 已经被广泛用在：
-
-- 数据查询页
-- 订单列表页
-- 玩家福利页
-- 弹窗内列表页
-- 需要导出功能的报表页
-
-比较典型的接入模式是：
-
-1. 在页面 `data()` 中生成 `columns` 和 `filterForm`
-2. 通过 `initSeachParams` 设置默认筛选条件
-3. 通过 `otherConfig` 对接接口字段命名和响应结构
-4. 通过 `tableRightButtons` 提供导出、新增等操作
-5. 通过 `ref` 获取当前查询条件或已选数据
-
-## 14. 使用建议
-
-- 优先把筛选配置和列配置抽到单独的 `configItem.js`，便于复用和维护
-- 日期范围类字段尽量统一使用 `callback` 输出后端需要的开始/结束字段
-- 如果页面存在导出功能，优先使用 `tablefilterFormData`，因为它已经是处理后的最终请求参数
-- 如果列配置需要持久化，尽量保证 `tableApi` 的函数定义稳定，避免列设置 key 变化
-- 如果业务依赖勾选结果，可以直接读取 `selectedList` 和 `selectedListIds`
-
-## 15. 当前实现可优化点
-
-下面这些是基于当前源码实现观察到的优化方向
-
-### 15.1 组件内部直接改动了传入的 props
-
-`SlPage` 里有多处直接修改 `filterForm`、`tableColumns` 内部对象的行为，例如：
-
-- 给筛选项补 `show`
-- 给列补 `isShow`
-- 直接对 `tableColumns` 做排序
-
-这会带来两个问题：
-
-- 子组件反向影响父组件数据源
-- 同一份配置如果被多个页面/实例复用，状态可能互相污染
-
-更稳妥的方向是改为“克隆后再处理”。
-
-**总结：暂时不动，由于传入的对象，且目前该组件大量使用，故而暂不修改**
-
-
-### 15.2 重置逻辑对复杂字段不够友好
-
-当前重置流程会在 `resetFields()` 之后，再把 `form` 里的每个字段都强制置成空字符串。
-
-对于这些场景会比较别扭：
-
-- 多选下拉原本应该是 `[]`
-- 日期范围原本应该是 `[]`
-- 某些数值型字段原本可能希望回到 `null` 或默认值
-
-也就是说，重置后的数据类型未必和控件期望一致。
-
-/**总结：这块应该是要优化的，某些接口需要传null，有些需要传”“，有些没有值需要不传，难受**/
-
-### 15.3 列配置唯一标识依赖 `tableApi.toString()`
-
-当前列配置持久化 key 依赖函数源码字符串，这种方式有一定脆弱性：
-
-- 同一接口如果函数包装方式变了，历史列配置可能失效
-- 构建压缩、热更新、代理封装后，函数字符串不一定稳定
-
-更稳妥的方向是允许业务显式传一个稳定的 `tableKey`。
-
-**总结：其实可以传一个永不唯一的key，但是不能是变量**
-
-### 15.4 排序逻辑对新增列不够稳
-
-列排序使用：
-
-```js
-this.currentColConfig.sort.indexOf(a.prop) - this.currentColConfig.sort.indexOf(b.prop)
-```
-
-如果新列没有出现在历史排序数组里，`indexOf` 会返回 `-1`，这类列可能被排到最前面，表现不一定符合预期。
-
-**总结：后续维护**
-
-### 15.5 插槽转发上下文偏少
-
-当前 `SlPage -> SlTable` 的插槽转发只给了 `row`：
-
-```js
-v-bind="{ row: scope.row }"
-```
-
-如果业务想在插槽里拿到：
-
-- `**column**`
-- `$index`
-- `processedParams`
-
-现在还不够方便，只能继续改组件。
-
-**总结：后续需要进行无代价修改**
-
-
-### 15.6 参数处理规则在不同项目来源下不完全对称
-
-`processedParams` 对 `ares` 和非 `ares` 的处理存在差异，尤其是 `rangeInput` 的原始字段删除规则并不完全一致。后续如果页面越来越多，建议把参数序列化规则集中抽象，否则容易出现“同样的筛选项在不同页面请求参数不一样”的情况。
-
-**总结：由于系统接口不统一性，只能这么区分对待每个系统接口的特性**
-
-## 16. 小结
-
-如果你的页面是标准的“筛选 + 列表 + 分页 + 导出/操作按钮”结构，优先使用 `SlPage` 会比较省事。
-
-它当前已经具备：
-
-- 表单和表格的一体化封装
-- 参数处理能力
-- 列配置持久化
-- 页面级工具栏插槽
-- 通过 `ref` 直接控制查询
-
-但同时也建议在后续迭代里重点关注“不要直接改 props”“重置行为统一”“列配置 key 稳定化”这几类问题。

package/src/SlPage/SlPage.stories.js

@@ -1,125 +0,0 @@
-import SlPage from './index.vue'
-
-export default {
-  title: 'Components/SlPage',
-  component: SlPage,
-  parameters: {
-    docs: {
-      description: {
-        component: '列表页面模板组件，组合了搜索表单（SlForm）+ 表格（SlTable）的完整 CRUD 页面模板。提供搜索、重置、展开/折叠、列设置等功能。'
-      }
-    }
-  }
-}
-
-const codeBlock = (code) => `
-  <div style="margin-top:24px;border-top:1px solid #eee;padding-top:16px">
-    <p style="font-size:14px;font-weight:600;color:#666;margin-bottom:8px;">使用代码：</p>
-    <pre style="background:#f5f5f5;padding:16px;border-radius:4px;overflow-x:auto;font-size:13px;line-height:1.6;white-space:pre-wrap;word-break:break-all"><code>${escapeHtml(code.trim())}</code></pre>
-  </div>`
-
-function escapeHtml(str) {
-  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-}
-
-// mock 数据
-const mockData = [
-  { id: 1, name: '张三', age: 28, dept: '研发部', status: 1, createTime: '2024-01-15' },
-  { id: 2, name: '李四', age: 32, dept: '产品部', status: 0, createTime: '2024-02-20' },
-  { id: 3, name: '王五', age: 25, dept: '设计部', status: 1, createTime: '2024-03-10' },
-  { id: 4, name: '赵六', age: 30, dept: '研发部', status: 1, createTime: '2024-04-05' },
-  { id: 5, name: '孙七', age: 27, dept: '运营部', status: 0, createTime: '2024-05-18' },
-  { id: 6, name: '周八', age: 35, dept: '产品部', status: 1, createTime: '2024-06-22' },
-  { id: 7, name: '吴九', age: 29, dept: '设计部', status: 0, createTime: '2024-07-30' }
-]
-
-function mockApi(params) {
-  const { currentPage, pageSize, userName, status } = params
-  let list = [...mockData]
-  if (userName) list = list.filter(item => item.name.includes(userName))
-  if (status !== '' && status !== undefined) list = list.filter(item => item.status === status)
-  const start = (currentPage - 1) * pageSize
-  return Promise.resolve({
-    code: 1,
-    data: { list: list.slice(start, start + pageSize), total: list.length }
-  })
-}
-
-// ---- 基础用法 ----
-function statusRender(_ref) {
-  var row = _ref.row
-  var map = {
-    1: '<span style="color:#67c23a;background:#f0f9eb;padding:2px 8px;border-radius:3px;font-size:12px">启用</span>',
-    0: '<span style="color:#f56c6c;background:#fef0f0;padding:2px 8px;border-radius:3px;font-size:12px">禁用</span>'
-  }
-  return map[row.status] || '-'
-}
-
-var tableColumns = [
-  { type: 'selection' },
-  { prop: 'id', label: 'ID', width: '80' },
-  { prop: 'name', label: '姓名' },
-  { prop: 'age', label: '年龄', sortable: true },
-  { prop: 'dept', label: '部门' },
-  { prop: 'status', label: '状态', render: statusRender },
-  { prop: 'createTime', label: '创建时间', width: '140' },
-  { prop: 'operate', label: '操作', width: '150', list: function() { return [
-    { label: '编辑', click: () => {} },
-    { label: '删除', type: 'danger', click: () => {} }
-  ]}}
-]
-
-const filterForm = [
-  { label: '用户名', type: 'input', model: 'userName', privateAttrs: { placeholder: '请输入用户名' } },
-  { label: '状态', type: 'select', model: 'status', options: [
-    { label: '启用', value: 1 }, { label: '禁用', value: 0 }
-  ], props: { placeholder: '请选择状态' } },
-  { label: '创建时间', type: 'datePicker', model: 'createTime', privateProps: { type: 'daterange', valueFormat: 'yyyy-MM-dd' } }
-]
-
-const defaultCode = `<!-- 使用方式 -->
-<sl-page ref="page" :table-api="fetchList"
-  :table-columns="columns"
-  :filter-form="searchFields"
-  :show-form-item="3"
-  :auto-request="true">
-  <template slot="tableLeftButtons" slot-scope="scope">
-    <el-button type="primary" size="small">新增</el-button>
-  </template>
-</sl-page>
-
-<!-- columns 中自定义列渲染 -->
-{
-  prop: 'status',
-  label: '状态',
-  render: function(_ref) {
-    var row = _ref.row
-    return '<span>...</span>'
-  }
-}`
-
-export const Default = () => ({
-  components: { SlPage },
-  data() {
-    return {
-      tableApi: mockApi,
-      tableColumns: tableColumns,
-      filterForm: filterForm
-    }
-  },
-  template: `
-    <div>
-      <sl-page ref="page" :table-api="tableApi" :table-columns="tableColumns" :filter-form="filterForm" :show-form-item="3" :auto-request="true">
-        <template slot="tableLeftButtons" slot-scope="scope">
-          <el-button type="primary" size="small">新增</el-button>
-          <el-button type="danger" size="small" plain>批量删除</el-button>
-        </template>
-        <template slot="tableRightButtons" slot-scope="scope">
-          <el-button size="small" icon="el-icon-download">导出</el-button>
-        </template>
-      </sl-page>
-      ${codeBlock(defaultCode)}
-    </div>`
-})
-
-Default.storyName = '完整列表页'