rw-admin-ui 1.0.0

package/packages/basic-form/basic-form-dataflow.md

@@ -0,0 +1,136 @@
+# packages/basic-form 数据流向逻辑图
+
+## 一、组件层结构
+
+- `index.js`
+  - 默认导出：`ElBasicForm`（`src/basic-form.vue`）
+- `src/basic-form.vue`
+  - 外层包装组件：根据 `sections` 选择渲染 `ElBasicFormPlain` 或 `ElBasicFormSections`
+- `src/basic-form-plain.vue`
+  - 普通模式（非分组）：循环渲染 `effectiveSchemas`，逐项交由 `ElBasicFormItem` 渲染
+- `src/basic-form-sections.vue`
+  - 分组模式（sections）：模板负责渲染 `schemas` 的树形/矩阵结构，并在叶子节点复用 `ElBasicFormItem`
+
+## 二、数据输入与模型流向
+
+- 外部调用方传入
+  - `model`（可选）
+  - `schemas`
+  - `rules`
+  - `fieldMapToTime`
+  - `baseColProps`
+  - `mergeDynamicData` 等
+- 在 `src/mixins/basic-form-view.js` 中：
+  - `props`：统一定义表单对外 props（`basicFormViewProps`）
+  - `data`
+    - `internalModel`：未传 `model` 时使用的本地表单数据
+    - `internalSchemas`：运行时可变的 schema 列表（用于动态增删改）
+    - `formRules`：当前校验规则（由 `rules` watch 同步）
+    - `advancedOpen`：高级项展开状态
+  - `computed.formModel`
+    - `formModel = model || internalModel`
+
+## 三、schemas 流向
+
+- 外部传入 `schemas`
+  - 进入 `src/mixins/basic-form-runtime-factory.js` 的 `watch.schemas`
+  - 通过运行时策略 `flattenSchemas(schemas)` 抽取“字段 schema”列表并生成初始值映射
+    - 普通模式：`flattenSchemas` 为“直接返回数组（并做 Array 保护）”
+    - sections 模式：`flattenSchemas` 为 `flattenSchemasWithSections(schemas)`
+  - 若未提供外部 `model`：
+    - 用 `$set/$delete` 将初始值映射增量同步到 `internalModel`
+
+- `effectiveSchemas`（computed）
+  - 源数据 `base = internalSchemas（优先） || props.schemas`
+  - 通过运行时策略 `normalizeSchemas(base)` 得到“渲染用 schema 列表”
+    - 普通模式：`normalizeSchemas` 为“直接返回数组（并做 Array 保护）”
+    - sections 模式：`normalizeSchemas` 为 `normalizeSchemasWithSections(base)`（当前实现仅做 Array 保护并原样返回）
+  - 对渲染用 schema 进行统一处理
+    - 执行 `show/ifShow`（支持函数与布尔）过滤
+    - 合并 `colProps = { ...baseColProps, ...schemaItem.colProps }`
+    - 归一化 `disabled`（schema.disabled 优先，否则读取 `componentProps.disabled`）
+    - 若开启高级收起：截取前 `max(alwaysShowLines, autoAdvancedLine)` 项
+
+## 四、sections 模式下的“字段抽取”
+
+- 文件：`normalize-schemas-with-sections.js`
+- 输入：树形 `schemas`（含 `sections`）
+- `normalizeSchemasWithSections(src)`
+  - 仅做最小类型保护：`src` 非数组时返回 `[]`；当前版本不改动结构
+- `flattenSchemasWithSections(src)`
+  - 用显式 `stack` 迭代遍历（支持 `sections`、支持二维数组矩阵结构）
+  - 仅抽取叶子节点（必须有 `field`）
+  - 按 `field` 去重，返回“字段 schema”扁平列表（供初始化与重置使用）
+
+## 五、渲染流向
+
+- `src/basic-form.vue`
+  - 根据 `sections` 选择内层组件
+    - `sections=false` → `src/basic-form-plain.vue`
+    - `sections=true` → `src/basic-form-sections.vue`
+
+- `src/basic-form-plain.vue`
+  - `el-form :model="formModel" :rules="formRules"`
+  - `v-for="schema in effectiveSchemas"` → `ElBasicFormItem`
+  - `BasicFormAction` 触发 `submit/reset/toggleAdvanced`
+
+- `src/basic-form-sections.vue`
+  - 顶层循环 `effectiveSchemas`
+    - 若 `schema.sections` 存在：按“分组节点”渲染 `el-divider + el-row`，递归展开子 sections（模板层级展开）
+    - 否则：按“字段节点”交由 `ElBasicFormItem` 渲染
+  - 对叶子字段节点：通过 `buildSectionItemSchema` 合并/继承 `labelWidth/required/colProps/labelStyle` 后再交给 `ElBasicFormItem`
+
+- `basic-form-item.vue`
+  - 根据 `schema` 决定渲染分支：
+    - 有 `renderColContent` / `colSlot` → 自定义列内容
+    - `component === 'Divider'` → 渲染 `el-divider`
+    - 否则 → 普通字段
+  - 普通字段分支：
+    - 外层：`el-col`（使用 `schema.colProps`）
+    - 内层：`el-form-item`，属性来自 `itemProps`
+    - 表单组件：
+      - `<component :is="componentTag(schema.component)" v-model="formModel[schema.field]" />`
+      - `finalComponentProps` 传入组件 props
+      - 事件通过 `finalListeners(schema)` 绑定
+
+## 六、提交与重置数据流
+
+- 提交 `submit`
+  - 触发路径：
+    - `BasicFormAction` → `submit()`（由 `basic-form-runtime-factory.js` 提供）
+  - 处理逻辑（运行时统一）：
+    - 若存在 `submitFunc`：先执行（支持 Promise），成功后继续
+    - 否则：先 `el-form.validate` 校验
+    - 生成 `payload = mergePayload(mapFieldToTime(formModel))`
+    - `$emit('submit', payload)`
+- 重置 `reset`
+  - 触发路径：
+    - `BasicFormAction` → `reset()`（由 `basic-form-runtime-factory.js` 提供）
+  - 处理逻辑（运行时统一）：
+    - 若存在 `resetFunc`：先执行（支持 Promise），成功后继续
+    - `el-form.resetFields()` 重置校验与值
+    - 通过 `flattenSchemas(schemas)` 重新计算每个字段的默认值并覆盖 `internalModel`
+    - `$emit('reset', mergePayload(mapFieldToTime(formModel)))`
+
+## 七、代码依赖关系（简图）
+
+- `packages/basic-form/index.js`
+  - → `src/basic-form.vue`
+    - → `src/basic-form-plain.vue`
+      - → `src/mixins/basic-form-view.js`
+      - → `src/mixins/basic-form-runtime.js`
+        - → `src/mixins/basic-form-runtime-factory.js`
+          - → `rowinself-ui/src/utils/date-util`
+      - → `src/basic-form-item.vue` → `src/mixins/basic-form-item.js` → `src/mixins/basic-form-runtime-factory.js`
+      - → `src/basic-form-action.vue`
+    - → `src/basic-form-sections.vue`
+      - → `src/mixins/basic-form-view.js`
+      - → `src/mixins/basic-form-runtime-sections.js`
+        - → `src/mixins/normalize-schemas-with-sections.js`
+        - → `src/mixins/basic-form-runtime-factory.js`
+      - → `src/components/render-vnode.js`
+
+## 八、对外方法集（@register）
+
+- `src/mixins/basic-form-view.js` 在 `mounted` 时触发 `$emit('register', api)`
+- `api` 来源：优先使用运行时 `computedFormActionType`（由 `basic-form-runtime-factory.js` 统一生成）

package/packages/basic-form/index.js

@@ -0,0 +1,12 @@
+// 导出主组件：ElBasicForm
+import ElBasicForm from './src/basic-form.vue';
+
+/* istanbul ignore next */
+// 提供按需注册的 install 方法，供 Vue.use() 使用
+ElBasicForm.install = function(Vue) {
+  // 以组件名进行全局注册
+  Vue.component(ElBasicForm.name, ElBasicForm);
+};
+
+// 默认导出组件，支持 ES 模块导入
+export default ElBasicForm;

package/packages/basic-form/src/basic-form-action.vue

@@ -0,0 +1,71 @@
+<template>
+  <!--
+    操作区容器：统一承载提交/重置/高级展开/自定义按钮
+    - actionColOptions 直接透传给 el-col
+    - 回调通过 onSubmit/onReset/onToggleAdvanced 由父级运行时提供
+  -->
+  <el-col v-bind="actionColOptions" class="el-form-item__action">
+    <!-- 提交按钮：可通过 showSubmitButton 控制显隐，并透传按钮属性 -->
+    <el-button v-if="showSubmitButton" v-bind="submitButtonOptions" @click="handleSubmit">{{ submitButtonText }}</el-button>
+    <!-- 重置按钮：可通过 showResetButton 控制显隐，并透传按钮属性 -->
+    <el-button v-if="showResetButton" v-bind="resetButtonOptions" @click="handleReset">{{ resetButtonText }}</el-button>
+    <!-- 自定义按钮组：由 schema 外部传入 actionButton 数组驱动渲染 -->
+    <template v-if="actionButton && actionButton.length">
+      <el-button
+        v-for="(customButton, idx) in actionButton"
+        :key="customButton && (customButton.key || customButton.text || idx)"
+        v-bind="customButton"
+        @click="customButton.click({tableAction})"
+      >
+        {{ customButton.text }}
+      </el-button>
+    </template>
+    <!-- 高级展开/收起按钮：仅做状态切换，具体收起逻辑由运行时 effectiveSchemas 控制 -->
+    <el-button v-if="showAdvancedButton" type="text" @click="handleToggle">{{ advancedOpen ? '收起' : '展开' }}</el-button>
+    <!-- 额外动作插槽：供业务侧插入自定义内容 -->
+    <slot name="action"></slot>
+  </el-col>
+</template>
+<script>
+export default {
+  name: 'ElBasicFormAction',
+  props: {
+    // 操作区 el-col 的布局属性，如 { span: 24, offset: 0 }
+    actionColOptions: Object,
+    // 是否展示高级展开按钮
+    showAdvancedButton: Boolean,
+    // 当前是否处于展开状态
+    advancedOpen: Boolean,
+    // 是否展示提交按钮
+    showSubmitButton: Boolean,
+    // 是否展示重置按钮
+    showResetButton: Boolean,
+    // 透传给提交按钮（el-button）的属性
+    submitButtonOptions: Object,
+    // 透传给重置按钮（el-button）的属性
+    resetButtonOptions: Object,
+    // 提交按钮文本
+    submitButtonText: String,
+    // 重置按钮文本
+    resetButtonText: String,
+    // 自定义按钮配置数组（每项可包含 el-button props + click 回调）
+    actionButton: [Array, null],
+    // 表格方法集上下文（透传给自定义按钮 click）
+    tableAction: Object,
+    // 提交回调（由父组件运行时提供）
+    onSubmit: Function,
+    // 重置回调（由父组件运行时提供）
+    onReset: Function,
+    // 展开/收起回调（由父组件运行时提供）
+    onToggleAdvanced: Function
+  },
+  methods: {
+    // 触发提交
+    handleSubmit() { if (typeof this.onSubmit === 'function') this.onSubmit(); },
+    // 触发重置
+    handleReset() { if (typeof this.onReset === 'function') this.onReset(); },
+    // 切换高级展开状态
+    handleToggle() { if (typeof this.onToggleAdvanced === 'function') this.onToggleAdvanced(); }
+  }
+};
+</script>

package/packages/basic-form/src/basic-form-item.vue

@@ -0,0 +1,179 @@
+<template>
+  <!-- 列内容插槽：若提供 renderColContent/colSlot，则在列级别渲染自定义内容 -->
+  <el-col v-if="schema && (schema.renderColContent || schema.colSlot)" v-bind="schema.colProps || { span: 24 }">
+    <RenderVNode v-if="schema.renderColContent" :render-fn="() => schema.renderColContent(itemCtx)" />
+    <slot v-else :name="schema.colSlot" v-bind="itemCtx" ></slot>
+  </el-col>
+  <!-- 分割线组件：占满一行，并在标签右侧显示可选的帮助信息 -->
+  <el-col v-else-if="schema && schema.component === 'Divider'" v-bind="schema.colProps || { span: 24 }">
+    <el-divider>
+      {{ schema.label }}
+      <span v-if="helpMessageText" style="margin-left:8px;color:#909399;">{{ helpMessageText }}</span>
+    </el-divider>
+  </el-col>
+  <!-- 常规表单项：统一包裹在 el-col 中，默认 span:24 -->
+  <el-col v-else v-bind="(schema && schema.colProps) ? schema.colProps : { span: 24 }">
+    <!-- 表单项容器：根据 itemProps 驱动标签、校验、宽度等配置 -->
+    <el-form-item v-bind="itemProps">
+      <!-- 自定义标签：支持主标签与副标签 -->
+      <template v-if="schema.subLabel" slot="label">
+        <span>{{ schema.label }}</span>
+        <span style="margin-left:8px;color:#909399;">{{ schema.subLabel }}</span>
+      </template>
+      <!-- 优先：解析具名插槽对应的渲染函数，使用 RenderVNode 渲染 -->
+      <RenderVNode v-if="schema.slot && resolveSlotRender(schema)" :render-fn="resolveSlotRender(schema)" />
+      <!-- 其次：直接渲染具名插槽，透传 model 与 field -->
+      <slot v-else-if="schema.slot" :name="schema.slot" :model="formModel" :field="schema.field" ></slot>
+      <!-- 其三：使用 schema.render(h,ctx) 渲染自定义内容 -->
+      <RenderVNode v-else-if="schema.render" :render-fn="(h) => schema.render(itemCtx)" />
+      <!-- 默认：按 componentTag 生成具体组件，v-model 双向绑定到 formModel[field] -->
+      <component 
+        v-else 
+        :is="componentTag(schema.component)" 
+        v-model="modelValue" 
+        v-bind="finalComponentProps"
+        :disabled="computeDisabled(schema)" 
+        v-on="finalListeners(schema)">
+        <!-- 组件内部插槽：根据 options/自定义生成 default/suffix 等插槽 -->
+        <!-- 遍历 schema 中的 renderComponentContent，动态生成具名插槽 -->
+        <!-- 注意：使用 :slot 语法以兼容旧版工具链或特定的 Vue 2 环境 -->
+        <template v-for="(slotRender, slotName) in renderComponentContent(schema)" :slot="slotName">
+          <RenderVNode 
+            v-if="typeof slotRender === 'function'" 
+            :key="`${slotName}-fn`"
+            :render-fn="(h) => slotRender(itemCtx)" 
+          />
+          <span v-else :key="`${slotName}-text`">{{ slotRender }}</span>
+        </template>
+      </component>
+      <!-- 帮助信息提示：展示在表单项底部，可配置样式 -->
+      <div v-if="helpMessageText" class="el-form-item__extra" :style="helpStyle">{{ helpMessageText }}</div>
+    </el-form-item>
+  </el-col>
+  <!-- 说明：以上渲染分支顺序保证了最大灵活性：列级插槽 > Divider > 常规组件 -->
+</template>
+<script>
+import RenderVNode from './components/render-vnode';
+import BasicFormItemMixin from './mixins/basic-form-item';
+
+export default {
+  name: 'ElBasicFormItem',
+  components: { RenderVNode },
+  mixins: [BasicFormItemMixin],
+  props: {
+    // 单个表单项的配置 Schema
+    schema: Object,
+    // 来自父表单的响应式模型对象
+    formModel: Object,
+    // 是否为常见输入组件自动设置 placeholder
+    globalAutoSetPlaceHolder: Boolean,
+    // 规则消息是否拼接标签文本
+    globalRulesMessageJoinLabel: Boolean,
+    // 统一的组件尺寸
+    globalSize: String,
+    // 统一的禁用态（优先生效）
+    globalDisabled: Boolean,
+    // 自动设置支持组件的 clearable
+    globalAutoSetClearable: Boolean,
+    tableAction: Object,
+    formActionType: Object
+  },
+  computed: {
+    /**
+     * 生成 `el-form-item` 的属性对象
+     * - 动态 required/rules 计算
+     * - labelWidth 统一格式
+     * @returns {Object} - 符合 ElementUI `el-form-item` 的 props
+     */
+    itemProps() {
+      const schema = this.schema || {};
+      const required = this.evalMaybeFn(schema.required);
+      const rulesSource = Array.isArray(schema.dynamicRules)
+        ? schema.dynamicRules
+        : (typeof schema.dynamicRules === 'function' ? schema.dynamicRules(this.itemCtx) : (schema.rules || []));
+      const joinLabel = this.globalRulesMessageJoinLabel || !!schema.rulesMessageJoinLabel;
+      const label = schema.label || '';
+      const rules = joinLabel
+        ? (rulesSource || []).map(rule => ({ ...rule, message: rule && rule.message ? `${label}${rule.message}` : rule.message }))
+        : (rulesSource || []);
+      const elFormItemProps = {
+        label: schema.label,
+        prop: schema.field,
+        rules,
+        labelWidth: schema.disabledLabelWidth ? null : this.normalizeItemLabelWidth(schema.labelWidth),
+        labelStyle: schema.labelStyle,
+        required,
+        inlineMessage: schema.inlineMessage,
+        showMessage: schema.showMessage,
+        size: schema.size,
+        error: schema.error,
+        validateStatus: schema.validateStatus,
+        for: (() => {
+          const component = schema.component;
+          const isRange = component === 'RangePicker' || (component === 'DatePicker' && ((schema.componentProps && ['daterange', 'datetimerange'].includes(schema.componentProps.type))));
+          return isRange ? null : (schema.for || schema.field);
+        })()
+      };
+      if (schema.itemProps && typeof schema.itemProps === 'object') Object.assign(elFormItemProps, schema.itemProps);
+      return elFormItemProps;
+    },
+    /**
+     * 合并出最终传入组件的 props，并清理事件键（事件通过 `v-on` 绑定）
+     * @returns {Object}
+     */
+    finalComponentProps() {
+      const schema = this.schema || {};
+      const mergedProps = this.getComponentPropsMerged(schema);
+      const extractedListeners = this.extractEventListeners(mergedProps);
+      Object.keys(extractedListeners).forEach((listenerKey) => { if (listenerKey in mergedProps) delete mergedProps[listenerKey]; });
+      return mergedProps;
+    },
+    /**
+     * 规范化帮助信息文本
+     * @returns {string}
+     */
+    helpMessageText() {
+      const schema = this.schema || {};
+      const helpMessage = schema.helpMessage;
+      if (!helpMessage) return '';
+      if (Array.isArray(helpMessage)) return helpMessage.join(' ');
+      return String(helpMessage);
+    },
+    /**
+     * 帮助信息样式生成
+     * @returns {Object}
+     */
+    helpStyle() {
+      const helpComponentProps = (this.schema && this.schema.helpComponentProps) || {};
+      const style = {};
+      if (helpComponentProps.maxWidth) style.maxWidth = helpComponentProps.maxWidth;
+      if (helpComponentProps.color) style.color = helpComponentProps.color;
+      if (helpComponentProps.fontSize) style.fontSize = helpComponentProps.fontSize;
+      return style;
+    },
+    /**
+     * 提供给 `render/slot` 的上下文对象
+     * @returns {{ model: Object, field: string, schema: Object, h: Function }}
+     */
+    itemCtx() {
+      const schema = this.schema || {};
+      return { model: this.formModel, field: schema.field, schema: schema, h: this.$createElement };
+    },
+    /**
+     * 代理 v-model 绑定值：
+     * - 处理 undefined 情况：部分组件（如 ElSelect）required: true 且不支持 undefined，
+     *   此处统一回退到 null（通常被视为无值且满足 Object 类型检查）。
+     */
+    modelValue: {
+      get() {
+        const val = this.formModel[this.schema.field];
+        return val === undefined ? null : val;
+      },
+      set(val) {
+        this.$set(this.formModel, this.schema.field, val);
+      }
+    }
+  },
+  methods: {}
+};
+</script>

package/packages/basic-form/src/basic-form-plain.vue

@@ -0,0 +1,82 @@
+<template>
+  <!--
+    普通模式表单：
+    - 逐条渲染 effectiveSchemas（一维数组）
+    - 表单能力来自 basic-form-view/basic-form-runtime 两个 mixin
+    - 回车提交由 handleEnterSubmit 统一拦截
+  -->
+  <el-form
+    ref="formRef"
+    :class="['el-basic-form']"
+    :model="formModel"
+    :rules="formRules"
+    :label-position="labelAlign || labelPosition"
+    :label-width="normalizedLabelWidth"
+    :inline="inline"
+    :size="size"
+    :disabled="disabled"
+    @keydown.native.enter.prevent="handleEnterSubmit"
+  >
+    <!--
+      行容器：
+      - gutter 控制列间距
+      - baseRowStyle 允许外部覆盖整行样式
+      - labelAlign 用于生成 label 对齐的 class
+    -->
+    <el-row :gutter="14" :style="baseRowStyle" :class="`el-basic-form__label-${labelAlign}`">
+      <!--
+        表单项渲染：
+        - schema 驱动组件类型/校验/联动
+        - 全局开关（placeholder/clearable/rulesMessageJoinLabel）以 global 前缀传入
+      -->
+      <ElBasicFormItem
+        v-for="(schema, idx) in effectiveSchemas"
+        :key="schema && schema.field ? schema.field : idx"
+        :schema="schema"
+        :form-model="formModel"
+        :global-auto-set-place-holder="computedAutoSetPlaceHolder"
+        :global-auto-set-clearable="computedAutoSetClearable"
+        :global-rules-message-join-label="computedRulesMessageJoinLabel"
+        :global-size="size"
+        :global-disabled="disabled"
+        :table-action="tableAction"
+        :form-action-type="computedFormActionType"
+      />
+      <!--
+        操作区：
+        - 提交/重置/高级展开/自定义按钮
+        - 具体行为由 runtime mixin 的 submit/reset/toggleAdvanced 提供
+      -->
+      <BasicFormAction
+        v-if="showActionButtonGroup"
+        :action-col-options="computedActionColOptions"
+        :show-submit-button="computedShowSubmitButton"
+        :show-reset-button="computedShowResetButton"
+        :submit-button-options="computedSubmitButtonOptions"
+        :reset-button-options="computedResetButtonOptions"
+        :submit-button-text="computedSubmitButtonText"
+        :reset-button-text="computedResetButtonText"
+        :action-button="computedActionCustomButtons"
+        :show-advanced-button="computedShowAdvancedButton"
+        :advanced-open="advancedOpen"
+        :table-action="tableAction"
+        :on-submit="submit"
+        :on-reset="reset"
+        :on-toggle-advanced="toggleAdvanced"
+      >
+        <template slot="action"><slot name="action" ></slot></template>
+      </BasicFormAction>
+    </el-row>
+  </el-form>
+</template>
+<script>
+import basicFormView from './mixins/basic-form-view';
+import basicFormRuntime from './mixins/basic-form-runtime';
+
+export default {
+  // 普通模式：schemas 为一维数组
+  name: 'ElBasicFormPlain',
+  // 复用视图层能力 + 普通模式运行时
+  mixins: [basicFormView, basicFormRuntime]
+};
+</script>