@c2-markdown-ui/react 0.4.3 → 0.4.4

package/src/widgets/Form.tsx

@@ -1,512 +1,372 @@
-import React, { useEffect, useMemo, useRef, useState } from 'react';
-import { Button } from './Button';
-import { ButtonGroup } from './ButtonGroup';
-import { Cascader } from './Cascader';
-import { TreeSelect } from './TreeSelect';
-import { Select } from './Select';
-import { SelectMulti } from './SelectMulti';
-import { RadioGroup } from './Radio';
-import { Slider } from './Slider';
-import { Switch } from './Switch';
-import { TextInput } from './TextInput';
-import { DatePicker } from './DatePicker';
-import { NumberInput } from './NumberInput';
-import { Chart } from './Chart';
-import { parseChoice } from './choiceUtils';
-
-export interface FieldWhen {
-  /** 依赖的字段 id */
-  field: string;
-  /** 依赖字段命中这些值之一时才展示 */
-  values: string[];
-}
-
-/** 条件组合：all 且组（全部命中）、any 或组（任一命中），两组同时存在取交集 */
-export interface FieldWhenGroup {
-  all?: FieldWhen[];
-  any?: FieldWhen[];
-}
-
-export interface Field {
-  type: string;
-  id: string;
-  /** 在 row 内占据的栅格数（1-24，类似 antd Col 的 span） */
-  span?: number;
-  /** 条件显示：依赖字段的取值命中时才展示；
-   *  多条件时为数组（AND 组合：全部命中才显示）；
-   *  分组形态 { all, any }：且组全部命中 且 或组任一命中 */
-  when?: FieldWhen | FieldWhen[] | FieldWhenGroup;
-  [key: string]: any;
-}
-
-export interface FormRow {
-  /** 列间距（px），类似 antd Row 的 gutter */
-  gutter?: number;
-  fields: Field[];
-}
-
-export interface FormProps {
-  /** 表单 id（字段级统计事件携带，用于区分多个表单） */
-  id?: string;
-  fields: Field[];
-  /** 行分组（对象形态 { gutter, fields }；兼容旧数组形态 Field[][]） */
-  rows?: (FormRow | Field[])[];
-  inline?: boolean;
-  columns?: number;
-  submitLabel?: string;
-  /** 取消按钮文案，未设置则不显示 */
-  cancelLabel?: string;
-  /** 清空/重置按钮文案，未设置则不显示 */
-  resetLabel?: string;
-  /** 按钮组对齐：left / center / right */
-  buttonsAlign?: 'left' | 'center' | 'right';
-  /** 字段 label 与内容的布局：vertical 上下（默认）/ horizontal 左右 */
-  layout?: 'vertical' | 'horizontal';
-  /** 左右布局时 label 的宽度（px），默认 80 */
-  labelWidth?: number;
-  /** 左右布局时内容区域的宽度（px 或省略自适应填满） */
-  contentWidth?: number;
-  /** 是否禁用：级联禁用所有字段与按钮 */
-  disabled?: boolean;
-  /** 外部注入的初始值 { 字段id: 值 }，优先级高于字段 default；仅覆盖表单中已声明的字段 id */
-  initialData?: Record<string, unknown>;
-  onchange: (values: Record<string, unknown>) => void;
-  /** 提交成功回调：校验通过后触发，独立于 onchange 的提交事件 */
-  onsubmit?: (values: Record<string, unknown>) => void;
-  /** 字段级变化回调：任一表单项被填写时触发，携带统计信息与最新表单数据 */
-  onfieldchange?: (stats: FormStats) => void;
-}
-
-/** 表单统计信息：字段级变化事件携带 */
-export interface FormStats {
-  /** 表单 id */
-  id: string;
-  /** 当前展示（可见）的字段数 */
-  visibleCount: number;
-  /** 已填写（非空）的字段数 */
-  filledCount: number;
-  /** 当前表单数据（含隐藏字段值） */
-  values: Record<string, unknown>;
-}
-
-export const Form: React.FC<FormProps> = ({
-  fields,
-  rows,
-  inline,
-  columns,
-  submitLabel,
-  cancelLabel,
-  resetLabel,
-  buttonsAlign,
-  layout,
-  labelWidth,
-  contentWidth,
-  disabled = false,
-  initialData: externalData,
-  onchange,
-  onsubmit,
-  onfieldchange,
-  id: formId
-}) => {
-  const initialData = useMemo(() => {
-    const acc: Record<string, unknown> = {};
-    const seen = new Set<string>();
-    for (const f of fields) {
-      if (!f?.id || seen.has(f.id)) continue; // 重复 id 防护：默认值只取首次出现
-      seen.add(f.id);
-      if (f.type === 'button-group' || f.type === 'select') {
-        // choices[0] 可能是 key:label 格式，默认值取 key（表单值体系）
-        if (f.default !== undefined && f.default !== null && f.default !== '') {
-          acc[f.id] = parseChoice(String(f.default)).value;
-        } else {
-          acc[f.id] = Array.isArray(f.choices) && f.choices.length ? parseChoice(String(f.choices[0])).value : undefined;
-        }
-      } else if (f.type === 'select-multi') {
-        const d = f.default;
-        // choices 可能是对象数组（{value,key,label}）：default 写 label 时映射回 value 取值体系
-        const objChoices = (Array.isArray(f.choices) ? f.choices : [])
-          .filter((c: any) => c && typeof c === 'object') as Array<{ value?: string; key?: string; label?: string }>;
-        const mapDefault = (v: any): string => {
-          const s = String(v);
-          const hit = objChoices.find(c => String(c.value ?? c.key) === s || c.label === s);
-          return hit ? String(hit.value ?? hit.key) : parseChoice(s).value;
-        };
-        acc[f.id] = Array.isArray(d)
-          ? d.map(mapDefault)
-          : (d ? [mapDefault(d)] : []);
-      } else if (f.type === 'radio-group') {
-        // 单选：choices 可能是对象数组（{value,key,label}），default 写 label 时映射回 value
-        const d = f.default;
-        const objChoices = (Array.isArray(f.choices) ? f.choices : [])
-          .filter((c: any) => c && typeof c === 'object') as Array<{ value?: string; key?: string; label?: string }>;
-        const mapDefault = (v: any): string => {
-          const s = String(v);
-          const hit = objChoices.find(c => String(c.value ?? c.key) === s || c.label === s);
-          return hit ? String(hit.value ?? hit.key) : parseChoice(s).value;
-        };
-        if (d !== undefined && d !== null && d !== '') {
-          acc[f.id] = mapDefault(Array.isArray(d) ? d[0] : d);
-        } else {
-          acc[f.id] = Array.isArray(f.choices) && f.choices.length ? mapDefault(f.choices[0]) : '';
-        }
-      } else if (f.type === 'cascade') {
-        acc[f.id] = f.default ?? '';
-      } else if (f.type === 'slider') {
-        acc[f.id] = f.default ?? (typeof f.min === 'number' ? f.min : 0);
-      } else if (f.type === 'switch') {
-        acc[f.id] = f.default ?? false;
-      } else if (f.type === 'date-picker') {
-        // 范围模式默认 []（空数组），单选默认 null；default 已是时间戳/格式化字符串
-        acc[f.id] = f.range
-          ? (Array.isArray(f.default) ? f.default : (f.default !== undefined ? [f.default] : []))
-          : (f.default ?? null);
-      } else if (f.type === 'number-input') {
-        // 无 default 时为 null（空值），由组件内部处理显示
-        acc[f.id] = f.default ?? null;
-      } else if (f.type === 'text-input') {
-        acc[f.id] = f.default ?? '';
-      }
-    }
-
-    // 外部注入的初始值覆盖（仅覆盖表单已声明的字段 id：fields 与 rows 的并集）
-    if (externalData) {
-      const declaredIds = new Set<string>();
-      for (const f of fields ?? []) { if (f?.id) declaredIds.add(f.id); }
-      for (const r of rows ?? []) {
-        const rowFields = Array.isArray(r) ? r : (r?.fields ?? []);
-        for (const f of rowFields) { if (f?.id) declaredIds.add(f.id); }
-      }
-      for (const [k, v] of Object.entries(externalData)) {
-        if (declaredIds.has(k)) acc[k] = v;
-      }
-    }
-
-    return acc;
-  }, [fields, rows, externalData]);
-
-  const [data, setData] = useState<Record<string, unknown>>(initialData);
-
-  // 子组件以 default 初始化内部状态且仅挂载时读取一次；
-  // version 用于 initialData 变化（异步回填）/重置时 remount 子组件，让新值真正回显
-  const [version, setVersion] = useState(0);
-  const isFirstEffect = useRef(true);
-
-  useEffect(() => {
-    if (isFirstEffect.current) { isFirstEffect.current = false; return; }
-    setData(initialData);
-    setVersion(v => v + 1);
-  }, [initialData]);
-
-  // 字段校验错误：提交时统一校验填充，key 为字段 id
-  const [errors, setErrors] = useState<Record<string, string>>({});
-
-  /** 空值口径：undefined / null / 空串 / 空数组 */
-  const isEmptyVal = (v: unknown): boolean =>
-    v === undefined || v === null || v === '' || (Array.isArray(v) && v.length === 0);
-
-  /** 基于给定表单数据计算统计信息（可见性与取值统一基于传入的 values，避免闭包旧值） */
-  const computeStats = (values: Record<string, unknown>): FormStats => {
-    const visibleFields = uniqueFields.filter(f => isVisible(f, values));
-    return {
-      id: formId ?? '',
-      visibleCount: visibleFields.length,
-      filledCount: visibleFields.filter(f => !isEmptyVal(values[f.id])).length,
-      values
-    };
-  };
-
-  const setValue = (id: string, value: unknown) => {
-    setErrors(prev => (prev[id] ? { ...prev, [id]: '' } : prev));
-    setData(prev => {
-      const next = { ...prev, [id]: value };
-      // 字段级统计事件：在函数式更新内基于合并后的新值计算，
-      // 避免 isVisible 读取变更前的旧依赖值（stale closure 导致统计滞后一步）
-      if (onfieldchange) onfieldchange(computeStats(next));
-      return next;
-    });
-  };
-
-  /** 字段是否可见：无 when 时恒可见；
-   *  - 单条件：依赖字段值命中 values 任一
-   *  - 数组（FieldWhen[]）：AND 组合，全部命中才显示
-   *  - 分组（FieldWhenGroup）：且组 all 全部命中 且 或组 any 任一命中
-   *  values 显式传入依赖值（渲染时传 state data；事件统计时传合并后的新值） */
-  const isVisible = (f: Field, values: Record<string, unknown> = data): boolean => {
-    if (!f.when) return true;
-    const matchCond = (c: any): boolean => {
-      if (!c?.field || !Array.isArray(c.values) || c.values.length === 0) return true; // 非法条件忽略
-      const dep = values[c.field];
-      const op = c.op || 'eq';
-      if (op === 'eq') {
-        // 依赖值为数组时任一元素命中即可（支持 select-multi 等多选字段作为依赖）
-        if (Array.isArray(dep)) return dep.some(v => c.values.includes(String(v ?? '')));
-        return c.values.includes(String(dep ?? ''));
-      }
-      const left = Number(dep);
-      if (dep === undefined || dep === null || dep === '' || isNaN(left)) return false;
-      return c.values.some((v: string) => {
-        const right = Number(v);
-        if (isNaN(right)) return false;
-        if (op === 'gt') return left > right;
-        if (op === 'gte') return left >= right;
-        if (op === 'lt') return left < right;
-        if (op === 'lte') return left <= right;
-        return left !== right; // ne
-      });
-    };
-    const when = f.when as any;
-    if (!Array.isArray(when) && typeof when === 'object' && ('all' in when || 'any' in when)) {
-      const allOk = (when.all || []).every(matchCond);
-      const anyList = when.any || [];
-      const anyOk = anyList.length === 0 ? true : anyList.some(matchCond);
-      return allOk && anyOk;
-    }
-    const conds = Array.isArray(when) ? when : [when];
-    if (conds.length === 0) return true;
-    return conds.every(matchCond);
-  };
-
-  /** 单字段校验：返回错误文案或空串 */
-  const validateField = (f: Field): string => {
-    const v = data[f.id];
-    if (f.required) {
-      const empty = v === undefined || v === null || v === '' ||
-        (Array.isArray(v) && v.length === 0);
-      if (empty) return f.message || (f.label ? `请填写${f.label}` : '该项为必填项');
-    }
-    if (f.pattern && typeof v === 'string' && v && !new RegExp(f.pattern).test(v)) {
-      return f.message || (f.label ? `${f.label}格式不正确` : '格式不正确');
-    }
-    return '';
-  };
-
-  /** 提交前校验所有可见字段，全部通过返回 true（隐藏字段不校验） */
-  const validateAll = (): boolean => {
-    const next: Record<string, string> = {};
-    for (const f of uniqueFields) {
-      if (!isVisible(f)) continue;
-      const err = validateField(f);
-      if (err) next[f.id] = err;
-    }
-    setErrors(next);
-    return Object.keys(next).length === 0;
-  };
-
-  const handleSubmit = () => {
-    if (disabled) return;
-    if (!validateAll()) return;
-    // 提交数据中剔除隐藏字段的值（避免提交不可见的中间值）
-    const visible: Record<string, unknown> = {};
-    for (const key of Object.keys(data)) {
-      const f = uniqueFields.find(x => x.id === key);
-      if (f && !isVisible(f)) continue;
-      visible[key] = data[key];
-    }
-    onchange(visible);
-    onsubmit?.(visible);
-  };
-
-  const handleReset = () => {
-    if (disabled) return;
-    setData(initialData);
-    setErrors({});
-    setVersion(v => v + 1); // remount 子组件，界面回到初始值
-    // 重置同样派发统计事件：让面板即时回到初始统计口径
-    if (onfieldchange) onfieldchange(computeStats(initialData));
-  };
-
-  const handleCancel = () => {
-    if (disabled) return;
-    onchange({ ...initialData, _action: 'cancel' });
-  };
-
-  /** 按钮组：提交 + 可选的清空/取消，data-align 控制对齐；全部未设置则不渲染 */
-  const renderActions = () => {
-    if (!cancelLabel && !resetLabel && !submitLabel) return null;
-    return (
-      <div className="widget-form-actions" data-align={buttonsAlign || 'left'}>
-        {cancelLabel && <button type="button" className="widget-form-cancel" onClick={handleCancel} disabled={disabled}>{cancelLabel}</button>}
-        {resetLabel && <button type="button" className="widget-form-reset" onClick={handleReset} disabled={disabled}>{resetLabel}</button>}
-        {submitLabel && <button type="button" className="widget-form-submit" onClick={handleSubmit} disabled={disabled}>{submitLabel}</button>}
-      </div>
-    );
-  };
-
-  const renderField = (field: Field) => {
-    const commonProps = {
-      ...field,
-      // 用当前表单值覆盖字段 default：子组件以 default 初始化内部状态，
-      // 这样外部 data / 表单默认值才能回显到界面
-      default: data[field.id] !== undefined ? data[field.id] : field.default,
-      disabled: disabled || !!field.disabled,
-      onchange: (value: any) => setValue(field.id, value)
-    };
-
-    switch (field.type) {
-      case 'button':
-        return <Button {...commonProps} />;
-      case 'button-group':
-        return <ButtonGroup {...commonProps} choices={field.choices ?? []} />;
-      case 'select':
-        return <Select {...commonProps} choices={field.choices ?? []} />;
-      case 'select-multi':
-        return <SelectMulti {...commonProps} choices={field.choices ?? []} error={errors[field.id] || ''} />;
-      case 'radio-group':
-        return <RadioGroup {...commonProps} choices={field.choices ?? []} error={errors[field.id] || ''} />;
-      case 'cascade':
-        return <Cascader {...commonProps} choices={field.choices ?? []} error={errors[field.id] || ''} />;
-      case 'tree-select':
-        return <TreeSelect {...commonProps} choices={field.choices ?? []} error={errors[field.id] || ''} />;
-      case 'slider':
-        return (
-          <Slider
-            {...commonProps}
-            min={field.min ?? 0}
-            max={field.max ?? 100}
-          />
-        );
-      case 'switch':
-        return <Switch {...commonProps} />;
-      case 'text-input':
-        return <TextInput {...commonProps} error={errors[field.id] || ''} />;
-      case 'date-picker':
-        return <DatePicker {...commonProps} error={errors[field.id] || ''} />;
-      case 'number-input':
-        return <NumberInput {...commonProps} error={errors[field.id] || ''} />;
-      case 'chart-line':
-      case 'chart-bar':
-      case 'chart-pie':
-      case 'chart-scatter':
-        return <Chart {...field} type={field.type} labels={field.labels ?? []} datasets={field.datasets ?? []} onchange={(value: any) => setValue(field.id, value)} />;
-      default:
-        return null;
-    }
-  };
-
-  const containerClass = inline ? 'widget-form widget-form-inline' : 'widget-form';
-
-  // 左右布局：容器类 + CSS 变量（label 宽度 / 内容宽度）
-  const isHorizontal = layout === 'horizontal';
-  const layoutClass = isHorizontal ? 'widget-form-layout-horizontal' : '';
-  const layoutStyleVars: Record<string, string> | undefined = isHorizontal
-    ? ({
-        '--form-label-width': `${labelWidth ?? 80}px`,
-        ...(contentWidth ? { '--form-content-width': `${contentWidth}px` } : {})
-      })
-    : undefined;
-
-  const containerStyle: React.CSSProperties | undefined = columns
-    ? ({ '--form-columns': columns, ...layoutStyleVars } as React.CSSProperties)
-    : (layoutStyleVars as React.CSSProperties | undefined);
-
-  // 字段模式（无 row 分组）：任一字段带显式 span 时切换为 24 栅格布局，让 span 生效
-  // （无 span 的字段保持整行显示，不配 span 的表单仍走原布局，完全向后兼容）
-  const fieldsGridMode = !inline && (!rows || rows.length === 0) &&
-    fields.some(f => typeof f.span === 'number' && f.span >= 1 && f.span <= 24);
-
-  /** 字段模式栅格样式：显式 span 占 N 列；无 span 占满整行（1/-1，保持传统一行一个） */
-  const fieldsSpanStyle = (field: Field): React.CSSProperties | undefined => {
-    if (!fieldsGridMode && !inline) return undefined;
-    const s = typeof field.span === 'number' && field.span >= 1 && field.span <= 24 ? Math.round(field.span) : 0;
-    if (inline) {
-      // inline 模式：显式 span 覆盖 flex-basis（占行宽 N/24，flex-shrink 保证与相邻字段同行收放）
-      return s >= 1 ? { flex: `0 1 calc(${s} / 24 * 100%)` } : undefined;
-    }
-    return { gridColumn: s >= 1 ? `span ${s}` : '1 / -1' };
-  };
-
-  // 规范化 row：兼容旧数组形态 Field[][]
-  const normalizeRow = (row: FormRow | Field[]): FormRow =>
-    Array.isArray(row) ? { fields: row } : row;
-
-  // ---------- 重复 id 防护：与 svelte 版一致，只保留每个 id 的首次出现 ----------
-  const dedupeFields = (list: Field[]): Field[] => {
-    const seen = new Set<string>();
-    return (list ?? []).filter(f => {
-      if (!f?.id || seen.has(f.id)) return false;
-      seen.add(f.id);
-      return true;
-    });
-  };
-  const uniqueFields = useMemo(() => dedupeFields(fields), [fields]);
-  const normRows = useMemo(
-    () => (Array.isArray(rows) ? rows.map(normalizeRow).map(r => ({ ...r, fields: dedupeFields(r.fields) })).filter(r => r.fields.length > 0) : []),
-    [rows]
-  );
-
-  // 计算行内每个字段的 grid span（24 栅格，类似 antd）
-  // 显式 span 优先；无 span 时若 form 设置了 columns，则每字段占 24/columns（跨行对齐），
-  // 否则均分剩余栅格；总 span 超 24 时自动换行（由 grid auto-flow 处理）
-  const computeSpans = (fields: Field[]): number[] => {
-    const spans = fields.map(f => (typeof f.span === 'number' && f.span >= 1 && f.span <= 24 ? Math.round(f.span) : undefined));
-    const fixedTotal = spans.reduce((acc, s) => acc + (s ?? 0), 0);
-    const autoCount = spans.filter(s => s === undefined).length;
-    let autoSpan = 0;
-    if (autoCount > 0) {
-      if (columns && columns >= 1) {
-        autoSpan = Math.max(Math.floor(24 / columns), 1);
-      } else {
-        const remaining = Math.max(24 - fixedTotal, 0);
-        autoSpan = Math.max(Math.floor(remaining / autoCount), 1);
-      }
-    }
-    return spans.map(s => s ?? autoSpan);
-  };
-
-  // Rows 分组模式（24 栅格）
-  if (rows && rows.length > 0) {
-    // 设置 columns 时：所有 row 的字段合并流动，每行自动 columns 列（覆盖 row 手动分组）
-    if (columns && columns >= 1) {
-      const allFields = normRows.flatMap(r => r.fields).filter(f => isVisible(f));
-      const spans = computeSpans(allFields);
-      const gutter = normRows.find(r => r.gutter !== undefined)?.gutter;
-      return (
-        <div className={`widget-form ${layoutClass}`} style={layoutStyleVars as React.CSSProperties | undefined}>
-          <div
-            className="widget-form-row"
-            style={gutter !== undefined ? ({ '--row-gutter': `${gutter}px` } as React.CSSProperties) : undefined}
-          >
-            {allFields.map((field, fi) => (
-              <div className="widget-form-field" key={`${field.id}:${version}`} style={{ gridColumn: `span ${spans[fi]}` }}>
-                {renderField(field)}
-              </div>
-            ))}
-          </div>
-          {renderActions()}
-        </div>
-      );
-    }
-
-    return (
-      <div className={`widget-form ${layoutClass}`} style={layoutStyleVars as React.CSSProperties | undefined}>
-        {normRows.map((row, ri) => {
-          const visibleFields = row.fields.filter(f => isVisible(f));
-          const spans = computeSpans(visibleFields);
-          return (
-            <div
-              className="widget-form-row"
-              key={ri}
-              style={row.gutter !== undefined ? ({ '--row-gutter': `${row.gutter}px` } as React.CSSProperties) : undefined}
-            >
-              {visibleFields.map((field, fi) => (
-                <div className="widget-form-field" key={`${field.id}:${version}`} style={{ gridColumn: `span ${spans[fi]}` }}>
-                  {renderField(field)}
-                </div>
-              ))}
-            </div>
-          );
-        })}
-        {renderActions()}
-      </div>
-    );
-  }
-
-  return (
-    <div className={fieldsGridMode ? `${containerClass} ${layoutClass} widget-form-fields-grid` : `${containerClass} ${layoutClass}`} style={containerStyle}>
-      {uniqueFields.filter(f => isVisible(f)).map((field) => (
-        <div className="widget-form-field" key={`${field.id}:${version}`} data-field-type={field.type} style={fieldsSpanStyle(field)}>{renderField(field)}</div>
-      ))}
-      {renderActions()}
-    </div>
-  );
-};
+import React, { useEffect, useMemo, useState } from 'react';
+import { Button } from './Button';
+import { ButtonGroup } from './ButtonGroup';
+import { Cascader } from './Cascader';
+import { Select } from './Select';
+import { SelectMulti } from './SelectMulti';
+import { RadioGroup } from './Radio';
+import { Slider } from './Slider';
+import { Switch } from './Switch';
+import { TextInput } from './TextInput';
+import { DatePicker } from './DatePicker';
+import { NumberInput } from './NumberInput';
+import { Chart } from './Chart';
+import { parseChoice } from './choiceUtils';
+
+export interface FieldWhen {
+  /** 依赖的字段 id */
+  field: string;
+  /** 依赖字段命中这些值之一时才展示 */
+  values: string[];
+}
+
+/** 条件组合：all 且组（全部命中）、any 或组（任一命中），两组同时存在取交集 */
+export interface FieldWhenGroup {
+  all?: FieldWhen[];
+  any?: FieldWhen[];
+}
+
+export interface Field {
+  type: string;
+  id: string;
+  /** 在 row 内占据的栅格数（1-24，类似 antd Col 的 span） */
+  span?: number;
+  /** 条件显示：依赖字段的取值命中时才展示；
+   *  多条件时为数组（AND 组合：全部命中才显示）；
+   *  分组形态 { all, any }：且组全部命中 且 或组任一命中 */
+  when?: FieldWhen | FieldWhen[] | FieldWhenGroup;
+  [key: string]: any;
+}
+
+export interface FormRow {
+  /** 列间距（px），类似 antd Row 的 gutter */
+  gutter?: number;
+  fields: Field[];
+}
+
+export interface FormProps {
+  fields: Field[];
+  /** 行分组（对象形态 { gutter, fields }；兼容旧数组形态 Field[][]） */
+  rows?: (FormRow | Field[])[];
+  inline?: boolean;
+  columns?: number;
+  submitLabel?: string;
+  /** 取消按钮文案，未设置则不显示 */
+  cancelLabel?: string;
+  /** 清空/重置按钮文案，未设置则不显示 */
+  resetLabel?: string;
+  /** 按钮组对齐：left / center / right */
+  buttonsAlign?: 'left' | 'center' | 'right';
+  /** 是否禁用：级联禁用所有字段与按钮 */
+  disabled?: boolean;
+  onchange: (values: Record<string, unknown>) => void;
+}
+
+export const Form: React.FC<FormProps> = ({
+  fields,
+  rows,
+  inline,
+  columns,
+  submitLabel,
+  cancelLabel,
+  resetLabel,
+  buttonsAlign,
+  disabled = false,
+  onchange
+}) => {
+  const initialData = useMemo(() => {
+    const acc: Record<string, unknown> = {};
+    const seen = new Set<string>();
+    for (const f of fields) {
+      if (!f?.id || seen.has(f.id)) continue; // 重复 id 防护：默认值只取首次出现
+      seen.add(f.id);
+      if (f.type === 'button-group' || f.type === 'select') {
+        // choices[0] 可能是 key:label 格式，默认值取 key（表单值体系）
+        if (f.default !== undefined && f.default !== null && f.default !== '') {
+          acc[f.id] = parseChoice(String(f.default)).value;
+        } else {
+          acc[f.id] = Array.isArray(f.choices) && f.choices.length ? parseChoice(String(f.choices[0])).value : undefined;
+        }
+      } else if (f.type === 'select-multi') {
+        const d = f.default;
+        // choices 可能是对象数组（{value,key,label}）：default 写 label 时映射回 value 取值体系
+        const objChoices = (Array.isArray(f.choices) ? f.choices : [])
+          .filter((c: any) => c && typeof c === 'object') as Array<{ value?: string; key?: string; label?: string }>;
+        const mapDefault = (v: any): string => {
+          const s = String(v);
+          const hit = objChoices.find(c => String(c.value ?? c.key) === s || c.label === s);
+          return hit ? String(hit.value ?? hit.key) : parseChoice(s).value;
+        };
+        acc[f.id] = Array.isArray(d)
+          ? d.map(mapDefault)
+          : (d ? [mapDefault(d)] : []);
+      } else if (f.type === 'radio-group') {
+        // 单选：choices 可能是对象数组（{value,key,label}），default 写 label 时映射回 value
+        const d = f.default;
+        const objChoices = (Array.isArray(f.choices) ? f.choices : [])
+          .filter((c: any) => c && typeof c === 'object') as Array<{ value?: string; key?: string; label?: string }>;
+        const mapDefault = (v: any): string => {
+          const s = String(v);
+          const hit = objChoices.find(c => String(c.value ?? c.key) === s || c.label === s);
+          return hit ? String(hit.value ?? hit.key) : parseChoice(s).value;
+        };
+        if (d !== undefined && d !== null && d !== '') {
+          acc[f.id] = mapDefault(Array.isArray(d) ? d[0] : d);
+        } else {
+          acc[f.id] = Array.isArray(f.choices) && f.choices.length ? mapDefault(f.choices[0]) : '';
+        }
+      } else if (f.type === 'cascade') {
+        acc[f.id] = f.default ?? '';
+      } else if (f.type === 'slider') {
+        acc[f.id] = f.default ?? (typeof f.min === 'number' ? f.min : 0);
+      } else if (f.type === 'switch') {
+        acc[f.id] = f.default ?? false;
+      } else if (f.type === 'date-picker') {
+        // 范围模式默认 []（空数组），单选默认 null；default 已是时间戳/格式化字符串
+        acc[f.id] = f.range
+          ? (Array.isArray(f.default) ? f.default : (f.default !== undefined ? [f.default] : []))
+          : (f.default ?? null);
+      } else if (f.type === 'number-input') {
+        // 无 default 时为 null（空值），由组件内部处理显示
+        acc[f.id] = f.default ?? null;
+      } else if (f.type === 'text-input') {
+        acc[f.id] = f.default ?? '';
+      }
+    }
+    return acc;
+  }, [fields]);
+
+  const [data, setData] = useState<Record<string, unknown>>(initialData);
+
+  useEffect(() => {
+    setData(initialData);
+  }, [initialData]);
+
+  const setValue = (id: string, value: unknown) => {
+    setData(prev => ({ ...prev, [id]: value }));
+  };
+
+  /** 字段是否可见：无 when 时恒可见；
+   *  - 单条件：依赖字段值命中 values 任一
+   *  - 数组（FieldWhen[]）：AND 组合，全部命中才显示
+   *  - 分组（FieldWhenGroup）：且组 all 全部命中 且 或组 any 任一命中 */
+  const isVisible = (f: Field): boolean => {
+    if (!f.when) return true;
+    const matchCond = (c: any): boolean => {
+      if (!c?.field || !Array.isArray(c.values) || c.values.length === 0) return true; // 非法条件忽略
+      const dep = data[c.field];
+      const op = c.op || 'eq';
+      if (op === 'eq') return c.values.includes(String(dep ?? ''));
+      const left = Number(dep);
+      if (dep === undefined || dep === null || dep === '' || isNaN(left)) return false;
+      return c.values.some((v: string) => {
+        const right = Number(v);
+        if (isNaN(right)) return false;
+        if (op === 'gt') return left > right;
+        if (op === 'gte') return left >= right;
+        if (op === 'lt') return left < right;
+        if (op === 'lte') return left <= right;
+        return left !== right; // ne
+      });
+    };
+    const when = f.when as any;
+    if (!Array.isArray(when) && typeof when === 'object' && ('all' in when || 'any' in when)) {
+      const allOk = (when.all || []).every(matchCond);
+      const anyList = when.any || [];
+      const anyOk = anyList.length === 0 ? true : anyList.some(matchCond);
+      return allOk && anyOk;
+    }
+    const conds = Array.isArray(when) ? when : [when];
+    if (conds.length === 0) return true;
+    return conds.every(matchCond);
+  };
+
+  const handleSubmit = () => {
+    if (disabled) return;
+    onchange({ ...data });
+  };
+
+  const handleReset = () => {
+    if (disabled) return;
+    setData(initialData);
+  };
+
+  const handleCancel = () => {
+    if (disabled) return;
+    onchange({ ...initialData, _action: 'cancel' });
+  };
+
+  /** 按钮组：提交 + 可选的清空/取消，data-align 控制对齐；全部未设置则不渲染 */
+  const renderActions = () => {
+    if (!cancelLabel && !resetLabel && !submitLabel) return null;
+    return (
+      <div className="widget-form-actions" data-align={buttonsAlign || 'left'}>
+        {cancelLabel && <button type="button" className="widget-form-cancel" onClick={handleCancel} disabled={disabled}>{cancelLabel}</button>}
+        {resetLabel && <button type="button" className="widget-form-reset" onClick={handleReset} disabled={disabled}>{resetLabel}</button>}
+        {submitLabel && <button type="button" className="widget-form-submit" onClick={handleSubmit} disabled={disabled}>{submitLabel}</button>}
+      </div>
+    );
+  };
+
+  const renderField = (field: Field) => {
+    const commonProps = {
+      ...field,
+      disabled: disabled || !!field.disabled,
+      onchange: (value: any) => setValue(field.id, value)
+    };
+
+    switch (field.type) {
+      case 'button':
+        return <Button {...commonProps} />;
+      case 'button-group':
+        return <ButtonGroup {...commonProps} choices={field.choices ?? []} />;
+      case 'select':
+        return <Select {...commonProps} choices={field.choices ?? []} />;
+      case 'select-multi':
+        return <SelectMulti {...commonProps} choices={field.choices ?? []} />;
+      case 'radio-group':
+        return <RadioGroup {...commonProps} choices={field.choices ?? []} />;
+      case 'cascade':
+        return <Cascader {...commonProps} choices={field.choices ?? []} />;
+      case 'slider':
+        return (
+          <Slider 
+            {...commonProps} 
+            min={field.min ?? 0} 
+            max={field.max ?? 100} 
+          />
+        );
+      case 'switch':
+        return <Switch {...commonProps} />;
+      case 'text-input':
+        return <TextInput {...commonProps} />;
+      case 'date-picker':
+        return <DatePicker {...commonProps} />;
+      case 'number-input':
+        return <NumberInput {...commonProps} />;
+      case 'chart-line':
+      case 'chart-bar':
+      case 'chart-pie':
+      case 'chart-scatter':
+        return <Chart {...field} type={field.type} labels={field.labels ?? []} datasets={field.datasets ?? []} onchange={(value: any) => setValue(field.id, value)} />;
+      default:
+        return null;
+    }
+  };
+
+  const containerClass = inline ? 'widget-form widget-form-inline' : 'widget-form';
+  const containerStyle: React.CSSProperties | undefined = columns
+    ? ({ '--form-columns': columns } as React.CSSProperties)
+    : undefined;
+
+  // 字段模式（无 row 分组）：任一字段带显式 span 时切换为 24 栅格布局，让 span 生效
+  // （无 span 的字段保持整行显示，不配 span 的表单仍走原布局，完全向后兼容）
+  const fieldsGridMode = !inline && (!rows || rows.length === 0) &&
+    fields.some(f => typeof f.span === 'number' && f.span >= 1 && f.span <= 24);
+
+  /** 字段模式栅格样式：显式 span 占 N 列；无 span 占满整行（1/-1，保持传统一行一个） */
+  const fieldsSpanStyle = (field: Field): React.CSSProperties | undefined => {
+    if (!fieldsGridMode && !inline) return undefined;
+    const s = typeof field.span === 'number' && field.span >= 1 && field.span <= 24 ? Math.round(field.span) : 0;
+    if (inline) {
+      // inline 模式：显式 span 覆盖 flex-basis（占行宽 N/24，flex-shrink 保证与相邻字段同行收放）
+      return s >= 1 ? { flex: `0 1 calc(${s} / 24 * 100%)` } : undefined;
+    }
+    return { gridColumn: s >= 1 ? `span ${s}` : '1 / -1' };
+  };
+
+  // 规范化 row：兼容旧数组形态 Field[][]
+  const normalizeRow = (row: FormRow | Field[]): FormRow =>
+    Array.isArray(row) ? { fields: row } : row;
+
+  // ---------- 重复 id 防护：与 svelte 版一致，只保留每个 id 的首次出现 ----------
+  const dedupeFields = (list: Field[]): Field[] => {
+    const seen = new Set<string>();
+    return (list ?? []).filter(f => {
+      if (!f?.id || seen.has(f.id)) return false;
+      seen.add(f.id);
+      return true;
+    });
+  };
+  const uniqueFields = useMemo(() => dedupeFields(fields), [fields]);
+  const normRows = useMemo(
+    () => (Array.isArray(rows) ? rows.map(normalizeRow).map(r => ({ ...r, fields: dedupeFields(r.fields) })).filter(r => r.fields.length > 0) : []),
+    [rows]
+  );
+
+  // 计算行内每个字段的 grid span（24 栅格，类似 antd）
+  // 显式 span 优先；无 span 时若 form 设置了 columns，则每字段占 24/columns（跨行对齐），
+  // 否则均分剩余栅格；总 span 超 24 时自动换行（由 grid auto-flow 处理）
+  const computeSpans = (fields: Field[]): number[] => {
+    const spans = fields.map(f => (typeof f.span === 'number' && f.span >= 1 && f.span <= 24 ? Math.round(f.span) : undefined));
+    const fixedTotal = spans.reduce((acc, s) => acc + (s ?? 0), 0);
+    const autoCount = spans.filter(s => s === undefined).length;
+    let autoSpan = 0;
+    if (autoCount > 0) {
+      if (columns && columns >= 1) {
+        autoSpan = Math.max(Math.floor(24 / columns), 1);
+      } else {
+        const remaining = Math.max(24 - fixedTotal, 0);
+        autoSpan = Math.max(Math.floor(remaining / autoCount), 1);
+      }
+    }
+    return spans.map(s => s ?? autoSpan);
+  };
+
+  // Rows 分组模式（24 栅格）
+  if (rows && rows.length > 0) {
+    // 设置 columns 时：所有 row 的字段合并流动，每行自动 columns 列（覆盖 row 手动分组）
+    if (columns && columns >= 1) {
+      const allFields = normRows.flatMap(r => r.fields).filter(isVisible);
+      const spans = computeSpans(allFields);
+      const gutter = normRows.find(r => r.gutter !== undefined)?.gutter;
+      return (
+        <div className="widget-form">
+          <div
+            className="widget-form-row"
+            style={gutter !== undefined ? ({ '--row-gutter': `${gutter}px` } as React.CSSProperties) : undefined}
+          >
+            {allFields.map((field, fi) => (
+              <div className="widget-form-field" key={field.id} style={{ gridColumn: `span ${spans[fi]}` }}>
+                {renderField(field)}
+              </div>
+            ))}
+          </div>
+          {renderActions()}
+        </div>
+      );
+    }
+
+    return (
+      <div className="widget-form">
+        {normRows.map((row, ri) => {
+          const visibleFields = row.fields.filter(isVisible);
+          const spans = computeSpans(visibleFields);
+          return (
+            <div
+              className="widget-form-row"
+              key={ri}
+              style={row.gutter !== undefined ? ({ '--row-gutter': `${row.gutter}px` } as React.CSSProperties) : undefined}
+            >
+              {visibleFields.map((field, fi) => (
+                <div className="widget-form-field" key={field.id} style={{ gridColumn: `span ${spans[fi]}` }}>
+                  {renderField(field)}
+                </div>
+              ))}
+            </div>
+          );
+        })}
+        {renderActions()}
+      </div>
+    );
+  }
+
+  return (
+    <div className={fieldsGridMode ? `${containerClass} widget-form-fields-grid` : containerClass} style={containerStyle}>
+      {uniqueFields.filter(isVisible).map((field) => (
+        <div className="widget-form-field" key={field.id} data-field-type={field.type} style={fieldsSpanStyle(field)}>{renderField(field)}</div>
+      ))}
+      {renderActions()}
+    </div>
+  );
+};