cloud-web-corejs 1.0.54-dev.76 → 1.0.54-dev.761

package/src/components/formDialog/README.md

@@ -0,0 +1,239 @@
+# $formDialog 表单弹框
+
+JS 调用式表单弹框：传入字段配置即可打开一个可编辑表单，确认后以 Promise 返回表单数据，无需为每个小表单单独编写 `.vue` 弹框组件。
+
+- 组件位置：`src/components/formDialog/`
+- 全局注册：`src/index.js` 中 `Vue.use(FormDialog)`，挂载为 `Vue.prototype.$formDialog`
+- 示例页面：`src/views/support/form-dialog-demo/index.vue`（路由 `/support/form-dialog-demo`，11 个可运行示例）
+
+两种模式：
+
+1. **字段配置模式**（默认）——传 `fields` 数组，由本组件渲染 element 控件；
+2. **xform 整表模式**——传 `formCode`（或 `formJson`），弹框内渲染设计器里配置好的完整 xform 表单，见「xform 整表模式」一节。
+
+## 快速上手
+
+```js
+const data = await this.$formDialog({
+  title: "新增分类",
+  fields: [
+    { prop: "name", label: "名称", required: true },
+    {
+      prop: "type",
+      label: "类型",
+      type: "select",
+      options: [
+        { label: "普通", value: 1 },
+        { label: "重要", value: 2 },
+      ],
+    },
+    { prop: "enabled", label: "启用", type: "switch" },
+    { prop: "remark", label: "备注", type: "textarea" },
+  ],
+});
+// 点确定且校验通过 => data 为表单数据对象
+// 取消 / 右上角关闭 => data 为 null（不使用 reject，无需 catch）
+if (data !== null) {
+  // ...
+}
+```
+
+## 顶层 options
+
+| 参数 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `title` | String | `""` | 弹框标题 |
+| `width` | String | `"600px"` | 弹框宽度 |
+| `labelWidth` | String | `"100px"` | 表单 label 宽度 |
+| `model` | Object | `{}` | 初始值（编辑回显）。未提供的字段按类型补默认值 |
+| `fields` | Array | `[]` | 字段配置，见下 |
+| `rules` | Object | `{}` | 额外的 el-form 校验规则，与字段级 `required`/`rules` 合并 |
+| `readonly` | Boolean | `false` | 只读查看模式：整表单禁用，底部只有"关闭"按钮 |
+| `beforeConfirm` | Function | - | `(data) => Promise`。确认前钩子（常用于调保存接口），reject 则弹框不关闭；执行期间确定按钮 loading 防重复提交 |
+| `formCode` / `formJson` | String / Object | - | 传入即切换为 **xform 整表模式**（`fields` 不再生效），见「xform 整表模式」一节 |
+
+返回值：`Promise`。确认（校验通过、beforeConfirm 成功）resolve 表单数据浅拷贝；取消/关闭 resolve `null`。
+
+## 字段配置（field）
+
+### 通用属性
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `prop` | String | 字段名（必填，作为 model 的 key） |
+| `label` | String | 标签文字 |
+| `type` | String | 控件类型，缺省为 `input`，见下表 |
+| `span` | Number | 栅格宽度（24 为一行一个，默认 24） |
+| `required` | Boolean | 必填（自动生成"XX不能为空"规则） |
+| `rules` | Array/Object | 字段级校验规则 |
+| `placeholder` | String | 占位文案 |
+| `disabled` | Boolean / `(model) => Boolean` | 禁用（支持函数联动） |
+| `visible` | Boolean / `(model) => Boolean` | 显隐（支持函数联动；隐藏时不渲染、不参与校验） |
+| `props` | Object | 透传给底层 element 控件的 props（如 `min`/`max`/`multiple`/`valueFormat` 等，可覆盖默认值） |
+| `render` | `(h, model, field) => VNode` | 自定义渲染逃生口，内置类型覆盖不了时使用（配置了 render 则忽略 type） |
+| `onChange` | `(value, model, field, dialog) => void` | 值变化回调，见「联动」 |
+| `dependsOn` | Array\<String\> | 依赖字段列表，见「联动」 |
+
+### 控件类型（type）
+
+| type | 控件 | 值类型 | 说明 |
+|---|---|---|---|
+| `input`（默认） | el-input | String | |
+| `textarea` | el-input type=textarea | String | 默认 3 行 |
+| `number` | baseInputNumber | Number | 字段级 `scale`（小数位，默认 2，0=整数）、`negative`（允许负数）；`min`/`max` 走 `props` |
+| `select` | el-select | 任意 | 三种数据源见下节 |
+| `date` | el-date-picker | String | value-format 默认 `yyyy-MM-dd` |
+| `datetime` | el-date-picker | String | value-format 默认 `yyyy-MM-dd HH:mm:ss` |
+| `daterange` | el-date-picker | Array | value-format 默认 `yyyy-MM-dd` |
+| `switch` | el-switch | Boolean | |
+| `radio` | el-radio-group | 任意 | 用 `options` |
+| `checkbox` | el-checkbox-group | Array | 用 `options` |
+| `search` | el-input + 搜索图标 | String | 通用搜索框样式（同 xform vabsearch），见「搜索框」 |
+
+## 下拉数据源（select / radio / checkbox 通用）
+
+三选一：
+
+```js
+// 1. 静态值：数组（或函数，见「联动」）
+{ prop: "type", type: "select", options: [{ label: "普通", value: 1 }, "直接字符串也可以"] }
+
+// 2. 词汇：/user/common_attribute/listItems，显示 value、取值 sn（与 xform 约定一致）
+{ prop: "sex", type: "select", dictCode: "SEX", dictData: { ... } }
+
+// 3. 脚本编码："formCode/scriptCode"，先取服务名再请求 /{serviceName}/bd_api/{formCode}/{scriptCode}
+{
+  prop: "org", type: "select",
+  scriptCode: "demoForm/getOptions",
+  scriptData: { ... },        // 请求参数，也支持 (model) => ({...})
+  labelField: "name",         // 默认 "label"
+  valueField: "id",           // 默认 "value"
+  // 或完全自定义解析：
+  // parseOptions: (res) => [{ label, value }],
+}
+```
+
+远程选项加载中 select 显示 loading。脚本模式选项对象上带 `row`（原始行数据）。
+
+## 搜索框（type: "search"）
+
+样式与 xform vabsearch 控件一致：输入框内右侧 `el-icon-search` 图标 + 悬停清除图标。输入框默认禁止手输（值由选择回填），传 `props: { editable: true }` 放开。
+
+点击搜索图标的行为，三选一（优先级从上到下）：
+
+```js
+// 方式1：onSearch 完全自定义（自己开弹框、自己回写 model；model 是响应式的）
+{
+  prop: "customerName", label: "客户", type: "search",
+  onSearch: async (model, field) => { /* ... */ },
+  onClear: (model, field) => { model.customerId = null; model.customerName = null; },
+}
+
+// 方式2：searchComponent —— 打开自定义 Vue 弹框组件（走 utils/componentDialog）
+{
+  prop: "supplierName", label: "供应商", type: "search",
+  searchComponent: {
+    componentPath: "views/xx/pickerDialog.vue", // openComponentDialog 的全部选项均可透传
+    fieldMap: { supplierId: "id", supplierName: "name" },
+  },
+}
+// 组件契约：自带弹框（wrapper 默认 false）、确认时 $emit("confirm", rows)、
+// 关闭时 $emit("update:visiable", false)。参考 demo 的 demoPickerDialog.vue
+
+// 方式3：searchDialog —— 打开 xform 搜索弹框（searchFormDialog，按 formCode 渲染数据表格）
+{
+  prop: "billName", label: "单据", type: "search",
+  searchDialog: {
+    formCode: "xxx",            // 目标表单编码（需已配置搜索弹框）
+    multiple: false,
+    queryParam: { ... },        // 可选查询参数
+    rows: (model) => [...],     // 可选回显已选行，支持函数
+    fieldMap: { billId: "id", billName: "_tt" },
+    // layoutType: "PC",        // 默认 PC
+  },
+}
+```
+
+选中回写规则（方式2/3 共用，优先级从上到下）：
+
+1. `onConfirm(model, rows, field)` —— 完全自定义
+2. `fieldMap: { model字段: 行字段名 | (row, rows) => value }` —— 逐字段映射（函数形式可处理多选拼接）
+3. 默认把首行中与 `prop` 同名（或 `showField` 指定）的字段写回本字段
+
+清除图标触发 `onClear(model, field)`，不传则默认清空本字段；`clearable: false` 隐藏清除。
+
+## 联动
+
+四种机制可组合：
+
+```js
+fields: [
+  {
+    prop: "province", label: "省份", type: "select", options: [...],
+    // 1. onChange：任意字段值变化时触发（含搜索框 fieldMap 回写、render 控件改 model）
+    //    dialog 上可用：dialog.setFieldOptions(prop, options) 手动设选项
+    //                  dialog.reloadFieldOptions(prop) 按最新 model 重拉词汇/脚本选项
+    onChange: (val, model, field, dialog) => { ... },
+  },
+  {
+    prop: "city", label: "城市", type: "select",
+    // 2. dependsOn：依赖字段变化时自动清空自身值；
+    //    若选项来自 dictCode/scriptCode，会按最新 model 自动重新拉取
+    dependsOn: ["province"],
+    // 静态级联：options 支持函数，渲染时实时按 model 求值
+    options: (model) => cityMap[model.province] || [],
+    // 远程级联传参：dictData / scriptData 支持 (model) => ({...})
+  },
+  // 3. 显隐联动：隐藏时不渲染、不参与必填校验
+  { prop: "taxNo", label: "税号", required: true, visible: (model) => model.needInvoice },
+  // 4. 禁用联动
+  { prop: "reason", label: "原因", disabled: (model) => model.level !== 2 },
+]
+```
+
+实现方式为深度监听 model + 快照 diff，链式联动（A 变 → B 清 → B 的 onChange）可用；避免在 onChange 里循环写值。
+
+## xform 整表模式
+
+传 `formCode`（或直接传 `formJson`）即进入整表模式：不再走 `fields` 渲染，而是按 `USER_PREFIX + /formTemplate/getByFormCode` 加载表单模板（与 `views/user/form/vform/render.vue` 同链路），弹框内用 `VFormRender` 渲染完整 xform 表单——业务控件、明细表、脚本事件等设计器能力全部可用。
+
+```js
+const data = await this.$formDialog({
+  formCode: "xxx",              // 表单模板编码（与 formJson 二选一，formJson 直接传模板 JSON 对象）
+  // title: "自定义标题",        // 缺省取表单模板名称
+  // width: "1000px",           // 整表模式默认 1000px
+  model: { name: "初始值" },     // 初始数据，结构与 getFormData 一致（也可用 formData 字段名）
+  // readonly: true,            // 只读：走 xform setReadMode，底部只有"关闭"
+  // optionData: {},            // 透传 VFormRender 的 option-data
+  // globalDsv: {},             // 透传 VFormRender 的 global-dsv
+  onReady: (formRef, dialog) => {
+    // 表单挂载后回调，formRef 即 VFormRender 实例：
+    // formRef.setFieldValue / getWidgetRef / disableForm(...) 等 API 均可用
+  },
+  beforeConfirm: (formData) => this.$http({ ... }),  // 同字段模式，reject 不关闭
+});
+// data 为 xform getFormData 的完整表单数据（含明细表）；取消/关闭仍为 null
+```
+
+说明：
+
+- 确认时走 xform 自身的 `validateForm`（失败自动提示"必填项不能为空"并滚动定位到出错字段），通过后 resolve `getFormData` 的深拷贝。
+- `VFormRender` 为异步组件（独立 chunk），只在首次打开整表模式时加载，不增加主包体积；加载前会自动执行 `loadExtension()` 注册 xform 扩展控件。
+- 弹框规格与 xform 自己的 `dynamicDialogRender` 一致（`dialog-style list-dialog` + `.cont` 容器）。
+- 整表模式下 `fields`/`rules`/联动等字段配置模式的参数不生效——表单结构、校验、联动都在设计器里配置。
+
+## 其他说明
+
+- 每次调用创建独立实例，支持叠开多层弹框（如在 `onSearch` 里再开一层 `$formDialog`，见 demo 示例 7/8）。
+- 弹框规格与项目一致：`append-to-body`、禁点遮罩关闭、可拖拽（`v-el-drag-dialog`）、`dialog-style` 样式类。
+- 实例挂在 `window.$vueRoot` 之下，弹框内可正常使用 `$t2`、`$http`、`$getBaseDicts` 等原型能力。
+- 也可不经 Vue 实例调用：`import FormDialog from "@base/components/formDialog/index.js"; FormDialog.open({...})`。
+- 数字框底层为 `baseInputNumber`（`v-limit-number` 指令限制小数位/负号，支持按键、选区替换与粘贴校验）。
+
+## 与既有设施的分工
+
+| 场景 | 用什么 |
+|---|---|
+| 轻量配置化表单（增改查小弹框） | `$formDialog`（本组件） |
+| 复杂业务表单弹框（已有/需要专用 .vue） | `openComponentDialog`（`src/utils/componentDialog.js`） |
+| 按 xform 表单模板渲染的完整表单 | xform（`VFormRender` / `searchFormDialog`） |

package/src/components/formDialog/index.js

@@ -0,0 +1,35 @@
+const modules = {};
+import vue from "vue";
+import formDialog from "./index.vue";
+
+const FormDialogInstance = vue.extend(formDialog);
+
+/**
+ * JS 调用打开表单弹框。每次调用创建独立实例，支持叠开多层。
+ * 确定（校验通过）resolve 表单数据，取消/关闭 resolve(null)，不使用 reject。
+ */
+function open(options = {}) {
+  const parent
+    = typeof window !== "undefined" && window.$vueRoot ? window.$vueRoot : null;
+  const instanceOptions = {};
+  if (parent) {
+    instanceOptions.parent = parent;
+    if (parent._i18n) {
+      instanceOptions.i18n = parent._i18n;
+    }
+  }
+  const instance = new FormDialogInstance(instanceOptions);
+  instance.$mount();
+  document.body.appendChild(instance.$el);
+  return instance.open(options);
+}
+
+// 定义插件对象
+// vue的install方法，用于定义vue插件
+modules.install = function (Vue) {
+  // 在Vue的原型上添加实例方法，以全局调用
+  Vue.prototype.$formDialog = open;
+};
+modules.open = open;
+
+export default modules;