@dckj-npm/dc-material 0.1.377 → 0.1.379

package/es/components/custom-form/CUSTOM_FORM_OPERATION_MANUAL.md

@@ -0,0 +1,284 @@
+# CustomForm 操作使用手册（宴请预订）
+
+适用范围：
+- 组件目录：lowcode-react-material/src/components/custom-form
+- 对照页面配置：lowcode-react-material/src/components/custom-form/schema.json
+
+目标：
+- 按照现有 schema.json 的业务口径，使用 CustomForm 还原“宴请预订表单”
+- 你可以按本文逐项配置并逐项测试
+
+---
+
+## 1. 对照关系（schema.json -> CustomForm）
+
+### 1.1 旧 schema 的关键业务点
+
+1. 字段状态（state）
+- banquet_date
+- banquet_time
+- guest_count
+- package_name
+- package_name_text
+- package_price
+- user_name
+- user_mobile
+- memo
+- order_desc
+- order_status（默认值：待处理）
+
+2. 数据源
+- 套餐列表查询：node_ocmk24smc2g
+  - POST /source/api/dynamicFormTableRecord/page/1203689394066821120
+- 提交预订：node_ocmk24smc3g
+  - POST /source/api/dynamicFormTableRecord/1203690686210248704/
+
+3. 旧逻辑方法
+- onPackageNameChange：根据套餐 id 回填 package_price、package_name_text
+- onSubmitClick：拼接 order_desc，组装 itemList，调用提交数据源
+
+### 1.2 在 CustomForm 中的对应能力
+
+1. 字段状态维护
+- 由 CustomForm 内部统一管理，不再手写多个 onXxxChange
+
+2. 套餐联动
+- 用 fieldLinkage 替代 onPackageNameChange
+- 通过 dataSource + fillFields 一次回填多个字段
+
+3. 订单描述拼接
+- 用 computedFields 替代手动拼接 order_desc
+
+4. 提交参数组装
+- 用 submitMapping 替代 onSubmitClick 中手动 itemList
+
+5. 提交动作
+- 提交按钮绑定数据源（对应 node_ocmk24smc3g）
+
+---
+
+## 2. 宴请预订表单配置清单（按顺序）
+
+以下步骤在低代码设计器中，对 CustomForm 组件进行配置。
+
+### 步骤 1：放置 CustomForm
+
+1. 拖入 CustomForm 到页面
+2. 推荐布局：
+- columns：2
+- labelAlign：left
+- fullWidth：true
+
+### 步骤 2：配置表单项 formItems
+
+按下面字段建立表单项：
+
+1. 宴请日期
+- field：banquet_date
+- label：宴请日期
+- required：true
+- componentType：DatePicker 或 Input（若要与旧 schema 完全一致可选 Input）
+
+2. 宴请时间
+- field：banquet_time
+- label：宴请时间
+- required：true
+- componentType：Input
+
+3. 宴请人数
+- field：guest_count
+- label：宴请人数
+- required：true
+- componentType：NumberPicker（或 Input）
+
+4. 套餐名称
+- field：package_name
+- label：套餐名称
+- required：true
+- componentType：Select
+- optionsBind：绑定套餐列表数据，value=套餐id，label=套餐名
+
+5. 套餐名称文本（可不展示）
+- field：package_name_text
+- label：套餐名称文本
+- componentType：Input
+- formItemProps.invisible：true（若你希望隐藏）
+
+6. 套餐价格
+- field：package_price
+- label：套餐价格
+- componentType：Input
+- componentProps.readOnly：true
+
+7. 预订人名称
+- field：user_name
+- label：预订人名称
+- required：true
+- componentType：Input
+
+8. 预订人联系方式
+- field：user_mobile
+- label：预订人联系方式
+- required：true
+- componentType：Input
+
+9. 备注
+- field：memo
+- label：备注
+- componentType：TextArea
+- columnSpan：2
+
+### 步骤 3：配置字段初始化 initialValues
+
+建议添加：
+- field：order_status
+- valueType：fixed
+- value：待处理
+
+### 步骤 4：配置计算字段 computedFields
+
+添加一条：
+- targetField：order_desc
+- template：{package_name_text},{package_price},预订日期时间：{banquet_date} {banquet_time},宴请人数：{guest_count}人
+
+### 步骤 5：配置字段联动 fieldLinkage
+
+使用数据源模式，添加一条规则：
+- watchField：package_name
+- linkageMode：dataSource
+- dataSource：绑定套餐列表数据源（与 optionsBind 同源）
+- matchKey：id
+- fillFields：
+  - package_price -> package_price
+  - package_name_text -> package_name
+
+说明：
+- 旧 schema 中 package_name 存的是套餐 id，因此 matchKey 要和数据源主键一致（常见为 id）
+
+### 步骤 6：配置提交映射 submitMapping
+
+1. targetField：itemList
+2. items 按下列顺序添加：
+- columnName=banquet_time，template={banquet_date} {banquet_time}
+- columnName=guest_count，field=guest_count
+- columnName=package_name，field=package_name
+- columnName=package_name_text，field=package_name_text
+- columnName=package_price，field=package_price
+- columnName=user_name，field=user_name
+- columnName=user_mobile，field=user_mobile
+- columnName=memo，field=memo
+- columnName=order_desc，field=order_desc
+- columnName=order_status，field=order_status
+
+### 步骤 7：配置操作按钮 operations
+
+建议保留两按钮：
+
+1. 提交按钮
+- text：提交预订
+- action：submit
+- type：primary
+- submitValidate：true
+- dataSource：绑定提交接口（原 schema 的 node_ocmk24smc3g）
+
+2. 重置按钮
+- text：重置
+- action：reset
+- type：normal
+
+---
+
+## 3. 测试流程（可直接照测）
+
+### 用例 1：套餐数据加载
+
+步骤：
+1. 进入页面
+2. 打开“套餐名称”下拉
+
+期望：
+- 能看到套餐选项
+- 每个选项展示套餐名，提交值为套餐 id
+
+### 用例 2：套餐联动回填
+
+步骤：
+1. 选择任意套餐
+
+期望：
+- package_price 自动回填
+- package_name_text 自动回填
+
+### 用例 3：计算字段生成
+
+步骤：
+1. 填写 banquet_date、banquet_time、guest_count
+2. 选择套餐并完成联动
+
+期望：
+- order_desc 自动生成
+- 格式为：套餐名称文本,套餐价格,预订日期时间：日期 时间,宴请人数：X人
+
+### 用例 4：必填校验
+
+步骤：
+1. 不填必填项直接点“提交预订”
+
+期望：
+- 不触发提交接口
+- 展示对应字段错误提示
+
+### 用例 5：提交参数结构
+
+步骤：
+1. 完整填写表单后点击“提交预订”
+2. 在网络面板或接口日志查看请求体
+
+期望：
+- 请求中包含 itemList 数组
+- itemList 中 columnName/columnValue 与 submitMapping 配置一致
+- 包含 order_desc 和 order_status
+
+### 用例 6：重置按钮
+
+步骤：
+1. 先填写多个字段
+2. 点击“重置”
+
+期望：
+- 可编辑字段被清空
+- 若配置了 order_status 的初始值，可按设计预期保留或恢复
+
+---
+
+## 4. 快速排错
+
+1. 选套餐后价格不回填
+- 检查 fieldLinkage.matchKey 是否和数据源主键一致
+- 检查 optionsBind 的 value 是否就是该主键
+
+2. 提交后没有 itemList
+- 检查 submitMapping.targetField 是否为 itemList
+- 检查 items 是否至少有一条有效映射
+
+3. order_desc 为空
+- 检查 computedFields 的模板字段名是否与 formItems.field 完全一致
+
+4. 提交按钮没调接口
+- 检查 operations 中 submit 按钮是否绑定了 dataSource
+- 检查 submitValidate 打开时是否存在校验失败
+
+---
+
+## 5. 推荐对照检查表
+
+每次提测前可按下列核对：
+
+1. 表单项字段名与 submitMapping 字段名完全一致
+2. 套餐下拉 optionsBind 和 fieldLinkage.dataSource 同源
+3. matchKey 与 optionsBind 的 value 字段一致
+4. order_status 有初始值 待处理
+5. 提交按钮绑定正确数据源（提交接口）
+6. 必填项都设置了 required
+
+完成以上 6 项，基本可覆盖 schema.json 中宴请预订主流程。

package/es/components/custom-form/custom-form.d.ts

@@ -1,26 +1,188 @@
+/**
+ * CustomForm v0.5
+ * 阶段一新增能力：
+ *   - onChange(field, value, allValues)  统一字段变化事件，消灭所有 onXxxChange 样板函数
+ *   - initialValues                       属性面板直接配置字段初始值，无需在页面 state 手写
+ *   - computedFields                      声明式模板字符串计算衍生字段，提交时自动合并
+ * 阶段二新增能力：
+ *   - DateTimePicker                      日期时间组件，格式化为 YYYY-MM-DD HH:mm
+ *   - optionsBind                         下拉/单选/复选选项支持变量绑定（动态数据源）
+ *   - fieldLinkage                        字段联动：选 A → 自动填 B/C（从数据源查找匹配项）
+ *   - submitMapping                       提交映射：自动组装 itemList 格式，消灭手写 onSubmitClick
+ * 阶段三新增能力：
+ *   - labelAlign                          全局标签位置（top/left/inset），对齐 Fusion Form 标准
+ *   - fullWidth（全局）                    全局控制所有表单项组件是否 100% 宽，可被单项覆盖
+ *   - isPreview                           全局预览/只读态（依赖 Fusion Form isPreview 广播）
+ *   - labelCol / wrapperCol               via otherProps 透传，labelAlign=left 时配合使用
+ *   - onReset                             点击重置按钮后触发的回调事件
+ */
 import React from 'react';
 import './index.scss';
 import { FormProps } from '@alifd/next/lib/form';
-export type CustomFormItemType = 'Input' | 'TextArea' | 'Select' | 'RadioGroup' | 'CheckboxGroup' | 'NumberPicker' | 'DatePicker' | 'Upload';
+export type CustomFormItemType = 'Input' | 'TextArea' | 'Select' | 'RadioGroup' | 'CheckboxGroup' | 'NumberPicker' | 'DatePicker' | 'DateTimePicker' | 'Upload';
 export interface CustomFormItemSchema {
+    /** 字段名，对应提交值的 key，必填 */
     field: string;
+    /** 标签文字 */
     label?: string;
+    /** 是否必填（会显示红色星号，并在提交时校验） */
     required?: boolean;
+    /** 该字段的初始/默认值（优先级高于 CustomFormProps.initialValues） */
+    initialValue?: any;
+    /** 组件类型，默认 Input */
     componentType?: CustomFormItemType;
+    /** 传给组件的额外属性，如 placeholder、disabled、maxLength 等 */
     componentProps?: Record<string, any>;
+    /** 快捷配置 placeholder（等同于 componentProps.placeholder） */
+    placeholder?: string;
+    /** Select / RadioGroup / CheckboxGroup 的选项列表（静态配置） */
     options?: Array<{
         label: string;
         value: any;
     }>;
+    /** 动态选项（绑定变量/数据源后优先使用），仅 Select/RadioGroup/CheckboxGroup 生效 */
+    optionsBind?: any[];
+    /** 该表单项占几列（不超过父级 columns），默认 1 */
     columnSpan?: number;
+    /** 组件尺寸：small / medium / large，默认继承表单全局 size */
+    size?: 'small' | 'medium' | 'large';
+    /** 宽度是否占满容器（100%），默认 true */
+    fullWidth?: boolean;
+    /** 自定义错误提示文案（不设置则由 required 自动生成） */
+    help?: string;
+    /** 额外说明文案，显示在错误信息下方 */
+    extra?: string;
+    /** 传给 Form.Item 的额外属性，优先级最高，会覆盖上方所有同名配置 */
     formItemProps?: Record<string, any>;
 }
 type GridSpacing = [number] | [number, number] | [number, number, number] | [number, number, number, number];
-export interface CustomFormProps extends Omit<FormProps, 'onSubmit'> {
+/**
+ * computedFields：计算字段映射表
+ * key   = 要写入 values 的字段名
+ * value = 模板字符串，用 {fieldName} 引用其他字段值
+ * 示例：{ "order_desc": "{package_name},{package_price},日期：{banquet_date}" }
+ */
+export type ComputedFields = Record<string, string>;
+/**
+ * 字段联动规则（阶段二 + 阶段四 UX 简化）
+ *
+ * 【简单格式（推荐）】— 属性面板 ArraySetter 可视化编辑，每条规则对应一行：
+ *   { watchField, matchValue?, fillField, fillValue }
+ *   watchField  = 监听哪个字段变化
+ *   matchValue  = 匹配值（留空 = 任何变化都触发）
+ *   fillField   = 要回填的目标字段名
+ *   fillValue   = 回填的具体值
+ *
+ * 【高级格式（兼容旧配置）】— 支持动态数据源查找 + staticRules 嵌套格式：
+ *   { watchField, dataSource?, matchKey?, fillFields?, staticRules? }
+ */
+export interface FieldLinkageRule {
+    /** 监听的字段名（所有模式必填） */
+    watchField: string;
+    /** 触发回填的条件值（留空 = watchField 任何变化都触发） */
+    matchValue?: string | number;
+    /** 要回填的目标表单字段名 */
+    fillField?: string;
+    /** 回填的目标值 */
+    fillValue?: any;
+    /** 数据源数组（支持变量绑定），用于动态查找匹配项回填多个字段 */
+    dataSource?: any[];
+    /** 在 dataSource 中用于与 watchField 值比较匹配的 key，默认 'value' */
+    matchKey?: string;
+    /**
+     * 找到匹配项后，要回填的字段映射。
+     * key = 表单字段名（field），value = 数据源对象中的字段名
+     * 示例：{ "package_price": "price", "package_desc": "description" }
+     */
+    fillFields?: Record<string, string>;
+    /**
+     * 静态联动规则（不依赖 dataSource）。
+     * key = watchField 的匹配值，value = 要同时设置的字段映射 { formField: setValue }
+     * 示例：{ "豪华套餐": { "package_price": "9800" } }
+     */
+    staticRules?: Record<string, Record<string, any>>;
+}
+/** 提交映射 item（阶段二） */
+export interface SubmitMappingItem {
+    /** 写入结果数组中的 columnName */
+    columnName: string;
+    /** 从表单字段名取值（与 template 二选一） */
+    field?: string;
+    /** 模板字符串（同 computedFields 格式，与 field 二选一），如 "{package_name},{guest_count}人" */
+    template?: string;
+}
+/** rename 模式：单条字段重命名规则 */
+export interface FieldRenameItem {
+    /** 表单字段名（源） */
+    fromField: string;
+    /** API 参数名（目标） */
+    toField: string;
+}
+/**
+ * 操作按钮配置项（阶段四新增）
+ * 表单底部可配置多个按钮，每个按钮均可独立设置操作类型与数据源。
+ */
+export interface OperationItem {
+    /** 按钮显示文字 */
+    text: string;
+    /** 按钮操作类型：提交 / 重置 / 自定义 */
+    action: 'submit' | 'reset' | 'custom';
+    /** 按钮样式：primary（主要）/ secondary（次要）/ normal（普通），默认 normal */
+    type?: 'primary' | 'secondary' | 'normal';
+    /**
+     * 仅 action=submit 时生效：提交前是否执行必填校验，默认继承组件级 submitValidate（true）。
+     * 设置为 false 可跳过校验直接提交。
+     */
+    submitValidate?: boolean;
+    /**
+     * 仅 action=submit 时生效：绑定的提交数据源（在 lowcode-web 数据源面板中配置）。
+     * 优先级高于组件级 submitDataSource，未配置时回退到组件级 submitDataSource。
+     */
+    dataSource?: any;
+    /** 仅 action=custom 时生效：自定义点击回调函数 */
+    onClick?: (...args: any[]) => void;
+    /** 透传给 Button 组件的额外属性 */
+    buttonProps?: Record<string, any>;
+}
+/**
+ * 提交参数配置（阶段五扩展）
+ *
+ * 三种工作模式（mode）：
+ * - 'passthrough'：直接将 finalValues 作为请求参数，无需任何配置（字段名与 API 参数名相同时使用）。
+ * - 'rename'：按 fieldRenameMap 规则重命名指定字段，未列出的字段保持原名透传；
+ *             适合字段名与 API 参数名不一致的标准 REST 接口。
+ * - 'itemList'：将字段转换为动态表单格式 [{columnName, columnValue}]，
+ *              适合 /source/api/dynamicFormTableRecord/ 等动态表单接口。
+ *
+ * 向后兼容：未设置 mode 时，若 items 不为空则自动识别为 'itemList' 模式，否则等同于 'passthrough'。
+ */
+export interface SubmitMapping {
+    /**
+     * 参数构建模式，默认 'passthrough'（无 items 时）或 'itemList'（有 items 时，向后兼容）。
+     */
+    mode?: 'passthrough' | 'rename' | 'itemList';
+    /** rename 模式：字段重命名规则列表，未列出的字段按原名透传 */
+    fieldRenameMap?: FieldRenameItem[];
+    /** itemList 模式：组装结果写入 finalValues 的目标字段名，默认 'itemList' */
+    targetField?: string;
+    /** itemList 模式：字段映射规则 */
+    items?: SubmitMappingItem[];
+}
+export interface CustomFormProps extends Omit<FormProps, 'onSubmit' | 'onChange'> {
     columns?: number;
     spacing?: GridSpacing;
     emptyContent?: React.ReactNode;
     formItems?: CustomFormItemSchema[];
+    /** 字段初始值，key = field，value = 初始值（阶段一新增） */
+    initialValues?: Record<string, any>;
+    /** 计算字段声明，key = 目标字段名，value = 模板字符串如 "{a},{b}"（阶段一新增） */
+    computedFields?: ComputedFields;
+    /**
+     * 全局组件宽度占满（阶段三新增）
+     * 控制所有表单项的输入组件是否默认 100% 宽，可被单项 formItems[].fullWidth 覆盖。
+     * 不设置时沿用各项自身配置（默认无 style 约束）。
+     */
+    fullWidth?: boolean;
     showSubmit?: boolean;
     submitText?: string;
     submitValidate?: boolean;
@@ -29,8 +191,32 @@ export interface CustomFormProps extends Omit<FormProps, 'onSubmit'> {
     showReset?: boolean;
     resetText?: string;
     resetButtonProps?: Record<string, any>;
+    /**
+     * 操作按钮列表（阶段四新增）。
+     * 配置后取代 showSubmit / showReset 的显示逻辑，支持任意数量的提交 / 重置 / 自定义按钮。
+     * 未配置时（undefined）回退到旧版 showSubmit / showReset 双按钮模式，保证向后兼容。
+     */
+    operations?: OperationItem[];
+    /**
+     * 操作按钮区域的水平对齐方式（阶段四新增）。
+     * 'left' | 'center' | 'right'，默认 'center'。
+     */
+    operationAlign?: 'left' | 'center' | 'right';
     onSubmit?: (values: any, errors: any, field: any) => void;
     onSubmitFailed?: (values: any, errors: any, field: any) => void;
+    /**
+     * 统一字段变化事件（阶段一新增）
+     * field     = 发生变化的字段名
+     * value     = 该字段最新值
+     * allValues = 当前所有字段值（已合并 computedFields）
+     */
+    onChange?: (field: string, value: any, allValues: Record<string, any>) => void;
+    /** 点击重置按钮后触发（阶段三新增） */
+    onReset?: () => void;
+    /** 字段联动规则数组（阶段二新增） */
+    fieldLinkage?: FieldLinkageRule[];
+    /** 提交字段映射，自动组装 itemList 格式（阶段二新增） */
+    submitMapping?: SubmitMapping;
     children?: React.ReactNode;
 }
 declare const CustomForm: React.FC<CustomFormProps>;