@neatui/vue 4.8.2 → 5.1.0

package/src/components/loader/FormLoader/FormRender.vue

@@ -0,0 +1,503 @@
+<template>
+  <div ref="root" class="flex-block pr" @focusout="col._touched = true">
+    <slot v-if="custom" />
+    <button v-else-if="col.model[0] === 'Button'" type="button" ui-btn="@a s" v-bind="contentAttrs" v-on="events"><FieldExtra :value="displayOf(col, ctx)" :trusted="trusted" /></button>
+    <div v-else-if="col.model[0] === 'Html' && trusted" v-bind="contentAttrs" v-on="events" v-html="displayOf(col, ctx)"></div>
+    <div v-else-if="col.model[0] === 'Html' || col.model[0] === 'Text'" v-bind="contentAttrs" v-on="events"><FieldExtra :value="displayOf(col, ctx)" :trusted="trusted" /></div>
+    <div v-else-if="(mode === 'view' && !entry?.view) || entry?.component === FieldView" class="flex-block o-ls" :class="clh(col.model?.[1] || {})" v-on="events">{{ text }}</div>
+    <component
+      v-else-if="entry"
+      :is="entry.component"
+      :modelValue="displayOf(col, ctx)"
+      :class="entry.class"
+      v-bind="controlProps"
+      v-on="controlEvents"
+      @update:modelValue="update"
+    />
+    <FieldMessage :col="col" :mode="mode" />
+  </div>
+</template>
+<script lang="ts">
+  import { defineComponent, h, isVNode, markRaw } from 'vue';
+  import type { Component, VNode } from 'vue';
+  import { isArray, isObject, isString, isFunction } from '@fekit/utils';
+
+  /** 最近一层数组的操作上下文；行引用在排序后仍指向原行。 */
+  export interface FormArrayContext {
+    readonly list: any[];
+    readonly row: any;
+    readonly index: number;
+    readonly canAdd: boolean;
+    readonly canRemove: boolean;
+    readonly canMoveUp: boolean;
+    readonly canMoveDown: boolean;
+    add: () => void;
+    insertAfter: (index?: number) => void;
+    remove: () => void;
+    moveUp: () => void;
+    moveDown: () => void;
+  }
+
+  /** 联动上下文 */
+  export interface FormContext {
+    // 根表单数据
+    root: any;
+    // 当前层数据：分组内是嵌套对象，数组内是当前行
+    data: any;
+    // 数组行下标，不在数组内时为 undefined
+    index?: number;
+    array?: FormArrayContext;
+    // 当前层在根数据中的路径，比如 'business.address'、'members.0'
+    path: string;
+    mode: string;
+    route: any;
+    router: any;
+  }
+
+  /** 动态属性函数：(根数据只读副本, 当前字段, 上下文) */
+  export type FormSetup = (data: any, item: any, ctx: Omit<FormContext, 'path'> & { path: string; formPath: string; [key: string]: any }, router: any) => any;
+
+  /** 带监听的动态属性配置；watch 用点路径，'.' 开头表示当前层 */
+  export interface FormLinkage<T = any> {
+    value?: T;
+    setup?: FormSetup;
+    watch?: string[] | true;
+  }
+
+  /** 可以写成固定值、函数或联动配置的属性 */
+  export type Dynamic<T> = T | FormSetup | FormLinkage<T>;
+
+  /** 校验规则 */
+  export interface FormRule {
+    required?: boolean;
+    validator?: (value: any) => boolean | Promise<boolean>;
+    msg?: string;
+    // 兼容旧版提示字段；同时设置时以 msg 为准（包括空字符串）。
+    message?: string;
+    type?: 'risk' | 'warn' | string;
+  }
+
+  /** 字段值：default 初始化，get 显示/校验，set 写回。普通 value 可直接表示内容。 */
+  export interface FormValue {
+    default?: any;
+    get?: (value: any, ctx: FormContext) => any;
+    set?: (value: any, ctx: FormContext) => any;
+  }
+
+  /** 内容节点可以渲染的值 */
+  export type FormContent = string | number | boolean | null | VNode | { text?: string; html?: boolean; attrs?: Record<string, any> } | FormContent[];
+
+  /** 数组配置 */
+  export interface FormArray {
+    // 每一行的字段，兼容旧版 lists
+    child?: FormItem[];
+    lists?: FormItem[];
+    min?: number;
+    max?: number;
+    // 是否显示上移/下移
+    sortable?: boolean;
+    // 添加按钮文案，false 不显示
+    add?: string | false;
+    // 删除按钮文案，false 不显示
+    del?: string | false;
+    // 行内栅格
+    rows?: string;
+    // 绑定到每一行容器上
+    attrs?: Record<string, any>;
+    // 新行默认值
+    item?: Record<string, any> | (() => Record<string, any>);
+  }
+
+  /** 基础节点：标题和子节点复用同一套配置，不为装饰或交互增加专用字段。 */
+  export interface FormItem {
+    label?: Dynamic<string | [string, Record<string, any>] | FormItem[]>;
+    field?: string;
+    // 固定内容、{ text, html, attrs } 内容对象、VNode、数组；绑定字段时用 { default, get, set }；也可以是函数或联动配置
+    value?: FormValue | FormContent | FormSetup | FormLinkage<FormContent>;
+    child?: Dynamic<FormItem[]>;
+    attrs?: Dynamic<Record<string, any>>;
+    clear?: Dynamic<boolean | { value: boolean; restore?: boolean }>;
+    enums?: Dynamic<any[]>;
+    array?: Dynamic<FormArray | string>;
+    event?: Record<string, (ctx: FormContext & { item: any; node: any }, ...args: any[]) => any>;
+    model?: Dynamic<string | [string, Record<string, any>?]>;
+    rules?: Dynamic<FormRule[]>;
+    // 兼容原有布局和数据路径；普通容器布局也可直接使用 attrs。
+    media?: Dynamic<string>;
+    vertical?: Dynamic<boolean>;
+    paths?: string;
+    // 4.x 兼容：自定义插槽名；字段级冒号（false 不显示，string 自定义字符）
+    slot?: string;
+    colon?: boolean | string;
+  }
+
+  /** 字段与控件插槽（${field}、model 名、${field}-value、${field}-row）的参数 */
+  export interface FormSlotScope {
+    col: any;
+    node: any;
+    // 当前层数据
+    data: any;
+    mode: string;
+    // 原始值（未经 value.get）
+    value: any;
+    ctx: FormContext;
+    // 写回：经过 value.set，查看模式下不写入
+    update: (value: any) => void;
+    // Vue 控件直接 v-bind：modelValue 已经过 value.get
+    bind: { modelValue: any; 'onUpdate:modelValue': (value: any) => void; disabled: boolean };
+  }
+
+  /** 校验结果 */
+  export interface FormError {
+    field: string;
+    path: string;
+    label: string;
+    msg: string;
+    type: string;
+  }
+  export interface FormValidateResult {
+    valid: boolean;
+    errors: FormError[];
+    warnings: FormError[];
+  }
+
+  /** FormLoader 对外方法 */
+  export interface FormLoaderExpose {
+    /** 校验已显示字段；paths 只校验这些路径（含子路径） */
+    validate: (options?: { scroll?: boolean; paths?: string[] }) => Promise<FormValidateResult>;
+    reset: () => void;
+    clearValidate: () => void;
+    scrollToField: (path: string) => void;
+    /** 回填外部错误，返回没有匹配到字段的路径 */
+    setErrors: (errors: Record<string, string | { msg: string; type?: string }> | Array<{ path: string; msg: string; type?: string }>, options?: { scroll?: boolean }) => string[];
+    /** 与初始值相比发生变化的字段路径 */
+    getChanges: () => string[];
+    isDirty: (path?: string) => boolean;
+    /** 把当前数据设为新的初始值 */
+    setBaseline: () => void;
+    /** 数据副本；visibleOnly 去掉被 clear 隐藏的字段 */
+    getData: (options?: { visibleOnly?: boolean }) => any;
+  }
+
+  /** 动态属性任务 */
+  export interface LinkageTask {
+    idx: number;
+    key: string;
+    value: any;
+    setup: FormSetup;
+    // true 表示监听全部数据
+    watch: string[] | true;
+    hasInitialResult: boolean;
+    initialResult: any;
+    // 函数属性的计算结果；变化时重新应用，替代整表深拷贝监听
+    source?: () => any;
+  }
+
+  /** 控件注册信息 */
+  export interface FieldEntry {
+    component: Component;
+    // 查看模式使用控件自身的 readonly 展示（如图片库）。
+    view?: boolean;
+    validate?: (value: any, props: any) => string | null | Promise<string | null>;
+    // 是否把 enums 作为 options 传入
+    options?: boolean;
+    // 控件默认 class
+    class?: string;
+    // 字段缺失时的初始值，函数参数为 model[1]
+    emptyValue?: any | ((props: any) => any);
+  }
+
+  // 计算Label行高
+  export const clh = ({ sz = '' }: any = {}) => {
+    const lhs: any = { xs: 'lh-sm', s: 'lh-mm', m: 'lh-ls', l: 'lh-ll', xl: 'lh-xl' };
+    return lhs[sz] || 'lh-ls';
+  };
+
+  // 数组里全是空值也算空，比如日期范围的 ['', '']
+  const isBlank = (value: any) => value === '' || value === null || value === undefined;
+  export const isEmpty = (value: any) => isBlank(value) || (isArray(value) && value.every(isBlank));
+
+  // 标题既可以是文字，也可以是一棵普通节点树。
+  export const labelNodes = (label: any): FormItem[] | null =>
+    isArray(label) && label.every((item: any) => isObject(item) && !isArray(item)) ? label : null;
+  export const labelText = (label: any): string => {
+    const nodes = labelNodes(label);
+    if (nodes) return nodes.map((node) => typeof node.value === 'string' ? node.value : labelText(node.label)).join('');
+    return String((isArray(label) ? label[0] : label) ?? '');
+  };
+  export const labelAttrs = (label: any) => (!labelNodes(label) && isArray(label) ? label[1] || {} : {});
+  export const rulesOf = (col: any = {}): FormRule[] => {
+    // model 参数与旧版 v-bind 一致，可以覆盖节点 rules（包括显式空数组）。
+    const rules = col.model?.[1]?.rules ?? col.rules;
+    return isArray(rules) ? rules.map((rule: FormRule) => rule && rule.msg == null && rule.message !== undefined ? { ...rule, msg: rule.message } : rule) : [];
+  };
+  export const valueBinding = (value: any): value is FormValue =>
+    isObject(value) && !isArray(value) && ['default', 'get', 'set'].some((key) => Object.prototype.hasOwnProperty.call(value, key));
+  export const displayOf = (col: any = {}, ctx?: any) => {
+    const raw = col._data?.[col.field];
+    if (valueBinding(col.value)) return isFunction(col.value.get) ? col.value.get(raw, ctx) : raw;
+    return col.value !== undefined ? col.value : raw;
+  };
+  // 内置控件和插槽使用相同写回规则，查看模式不接受写入。
+  export const writeValue = (col: any, value: any, ctx: FormContext) => {
+    if (!col.field || ctx.mode === 'view') return;
+    const binding = col.value;
+    col._data[col.field] = valueBinding(binding) && typeof binding.set === 'function' ? binding.set(value, ctx) : value;
+  };
+
+  export const eventsOf = (col: any, ctx: FormContext) => {
+    const handlers: Record<string, (...args: any[]) => any> = {};
+    Object.entries(col.event || {}).forEach(([name, fn]) => {
+      if (isFunction(fn)) handlers[name] = (...args: any[]) => (fn as Function)({ ...ctx, item: col, node: col }, ...args);
+    });
+    return handlers;
+  };
+
+  // 内容渲染：字符串按文本渲染；VNode 原样渲染；{ text, html, attrs } 只有 html 为 true 且内容来自配置时才按 HTML 渲染
+  const render = (value: any, trusted: boolean): any => {
+    if (value === null || value === undefined || value === '') return null;
+    if (isVNode(value)) return value;
+    if (isArray(value)) return value.map((item: any) => render(item, trusted));
+    if (isObject(value)) {
+      const { text = '', html = false, attrs = {} } = value;
+      return html && trusted ? h('span', { ...attrs, innerHTML: text }) : h('span', trusted ? attrs : {}, String(text));
+    }
+    return h('span', String(value));
+  };
+
+  export const FieldMessage = defineComponent({
+    props: ['col', 'mode'],
+    setup: (props) => () => props.mode !== 'view' ? [
+      props.col.model?.[1]?.verify && props.col._checked
+        ? h('i', { 'ui-form-verify': props.col._error ? 'no' : isEmpty(props.col._data?.[props.col.field]) ? '' : 'ok', 'aria-hidden': 'true' }) : null,
+      props.col._error ? h('p', { id: `${props.col._fid}-error`, 'data-field-error': props.col.field,
+          role: props.col._error.type === 'warn' ? 'status' : 'alert',
+          class: `mt-xs ${props.col._error.type === 'warn' ? 'co-warn' : 'co-risk'}` }, props.col._error.msg) : null,
+    ] : null,
+  });
+
+  export const FieldExtra = defineComponent({
+    name: 'FieldExtra',
+    props: {
+      value: { type: null, default: null },
+      trusted: { type: Boolean, default: false },
+    },
+    setup(props) {
+      return () => render(props.value, props.trusted);
+    },
+  });
+
+  import {
+    Radio,
+    Gallery,
+    Input,
+    InputRange,
+    Switch,
+    Checkbox,
+    CheckboxGroup,
+    Textarea,
+    Select,
+    SelectList,
+    SelectTags,
+    SelectPicker,
+    SearchSelect,
+    PageSelect,
+    SelectTree,
+    MoreSelect,
+    MoreSelectList,
+    MoreSelectTags,
+    MoreSelectPicker,
+    MoreSelectTree,
+    DatePicker,
+    TimePicker,
+    DateRangePicker,
+    SearchMoreSelect,
+    ImgUpload,
+    Upload,
+    Cascader,
+  } from '../../form';
+  import { timeError } from '../../form/TimePicker.vue';
+  import { Tree } from '../../display';
+
+  const option = (component: any, extra: Partial<FieldEntry> = {}): FieldEntry => ({ component: markRaw(component), options: true, class: 'w-full', ...extra });
+  const multiple = { emptyValue: () => [] };
+
+  // View 由当前渲染器直接展示；注册表保留标记以兼容自定义注册。
+  export const FieldView = defineComponent({ name: 'FormView', render: () => null });
+
+  // 占位：只占栅格，不渲染内容
+  const Blank = defineComponent({ name: 'FormBlank', render: () => null });
+
+  // model[0] => 控件，未注册的 model 走插槽
+  const registry: Record<string, FieldEntry> = {
+    Radio: option(Radio),
+    Gallery: option(Gallery, { view: true, emptyValue: (props: any) => props?.multiple ? [] : '' }),
+    Input: { component: markRaw(Input), class: 'w-full' },
+    InputRange: { component: markRaw(InputRange), class: 'w-full', emptyValue: () => [] },
+    Select: option(Select),
+    SelectList: option(SelectList),
+    SelectTags: option(SelectTags, multiple),
+    SelectPicker: option(SelectPicker),
+    SearchSelect: option(SearchSelect),
+    MoreSelect: option(MoreSelect, multiple),
+    MoreSelectList: option(MoreSelectList, multiple),
+    MoreSelectTags: option(MoreSelectTags, multiple),
+    MoreSelectPicker: option(MoreSelectPicker, multiple),
+    SearchMoreSelect: option(SearchMoreSelect, multiple),
+    MoreSelectTree: option(MoreSelectTree, multiple),
+    PageSelect: option(PageSelect),
+    SelectTree: option(SelectTree),
+    Cascader: option(Cascader, { emptyValue: (props: any) => (props?.multiple ? [] : '') }),
+    DatePicker: { component: markRaw(DatePicker), class: 'w-full' },
+    TimePicker: { component: markRaw(TimePicker), validate: timeError, class: 'w-full' },
+    DateRangePicker: { component: markRaw(DateRangePicker), class: 'w-full', emptyValue: () => [] },
+    ImgUpload: { component: markRaw(ImgUpload) },
+    Upload: { component: markRaw(Upload) },
+    Textarea: { component: markRaw(Textarea) },
+    Switch: { component: markRaw(Switch), emptyValue: false },
+    // Checkbox 按值是否为数组区分单选/多选：options 是 { label, value } 列表时初始化为 []
+    Checkbox: {
+      component: markRaw(Checkbox),
+      emptyValue: (props: any) => (Array.isArray(props?.options) && props.options.some((item: any) => item && typeof item === 'object' && 'label' in item) ? [] : false),
+    },
+    CheckboxGroup: { component: markRaw(CheckboxGroup), options: true, emptyValue: () => [] },
+    Tree: { component: markRaw(Tree), class: 'mt-sm', emptyValue: () => [] },
+    View: { component: markRaw(FieldView), options: true },
+    Text: { component: markRaw(FieldView) },
+    Html: { component: markRaw(FieldView) },
+    Button: { component: markRaw(FieldView) },
+    Blank: { component: markRaw(Blank) },
+  };
+
+  // 仅补名称别名；显式注册同名控件时仍优先使用注册项。
+  const fieldAliases: Record<string, string> = { TextArea: 'Textarea', view: 'View', SelectImg: 'Gallery' };
+  export const getField = (model: string = ''): FieldEntry | undefined => registry[model] || registry[fieldAliases[model] ?? ''];
+
+  // 注册自定义控件，比如业务里的图片库；注册后 model 直接写名字即可。富文本等重控件建议用插槽接入，不进注册表
+  export const registerField = (name: string, entry: FieldEntry) => {
+    registry[name] = { ...entry, component: markRaw(entry.component as any) };
+  };
+
+  // 字段缺失时的初始值
+  export const emptyValueOf = (model: any[] = []) => {
+    const entry = getField(model[0]);
+    const value = entry?.emptyValue;
+    if (typeof value === 'function') return value(model[1]);
+    return value === undefined ? '' : value;
+  };
+</script>
+<script lang="ts" setup>
+  // 单个字段的渲染：内置内容节点、注册控件或插槽，以及统一的错误提示
+  import { computed, ref, watch, nextTick, onMounted, onUpdated } from 'vue';
+  const props = defineProps<{
+    col: any;
+    entry?: FieldEntry;
+    interacted: boolean;
+    mode?: string;
+    ctx: FormContext;
+    custom?: boolean;
+  }>();
+  // 在选项树里按 value 找 label
+  const findLabel = (options: any[] = [], value: any): any => {
+    for (const option of isArray(options) ? options : []) {
+      if (option && typeof option === 'object') {
+        if (`${option.value}` === `${value}`) return option.label;
+        const found = findLabel(option.children, value);
+        if (found !== undefined) return found;
+      } else if (`${option}` === `${value}`) {
+        return option;
+      }
+    }
+    return undefined;
+  };
+
+  // 原控件类型：model 为 View 时由 model[1].type 指定，否则就是 model[0]
+  const type = computed(() => (['View', 'view'].includes(props.col.model?.[0]) ? props.col.model?.[1]?.type : props.col.model?.[0]));
+
+  const text = computed(() => {
+    const { col } = props;
+    const value = displayOf(col, props.ctx);
+    const format = col.model?.[1]?.format;
+    if (isFunction(format)) return format(value, col);
+    if (isEmpty(value)) return col.model?.[1]?.empty ?? '-';
+    if (typeof value === 'boolean') return value ? '是' : '否';
+    const one = (v: any) => findLabel(col.enums, v) ?? v;
+    if (isArray(value)) {
+      // 日期范围等控件的空值是 ['', '']
+      const list = value.filter((v: any) => !isEmpty(v));
+      if (!list.length) return col.model?.[1]?.empty ?? '-';
+      const sep = type.value === 'DateRangePicker' ? ' ~ ' : type.value === 'Cascader' ? ' / ' : '、';
+      return list.map(one).join(sep);
+    }
+    return String(one(value));
+  });
+  // 配置里写死、由配置函数生成或经 value.get 转换的内容视为可信；直接显示 field 数据时按文本渲染，避免 XSS。
+  const trusted = computed(() => {
+    const { value } = props.col;
+    return value !== undefined && (!valueBinding(value) || isFunction(value.get));
+  });
+  const events = computed(() => eventsOf(props.col, props.ctx));
+  // 先写回数据再通知配置里的 update:modelValue，与插槽的 update 顺序一致。
+  const controlEvents = computed(() => {
+    const { 'update:modelValue': _, ...rest } = events.value;
+    return rest;
+  });
+  const update = (value: any) => {
+    props.col._touched = true;
+    writeValue(props.col, value, props.ctx);
+    events.value['update:modelValue']?.(value);
+  };
+
+  // FormLoader 自己的参数只传给声明了它们的控件，避免落到 Radio、Gallery 等控件的 DOM 上。
+  const formOnly = ['interacted', 'rules', 'verify', 'co', 'format', 'empty'];
+  const controlProps = computed(() => {
+    const { col, entry, mode } = props;
+    const options = col.model?.[1] || {};
+    const merged: Record<string, any> = {
+      interacted: props.interacted,
+      options: entry?.options ? col.enums : undefined,
+      ...options,
+      rules: [],
+      verify: false,
+      co: col._error?.type || options.co,
+      readonly: mode === 'view' ? true : options.readonly,
+      disabled: mode === 'view' ? true : options.disabled,
+    };
+    const declared: any = (entry?.component as any)?.props;
+    // 没有声明 props 的自定义注册控件可能通过 $attrs 读取这些参数，保持透传。
+    const declares = (key: string) => !declared || (isArray(declared) ? declared.includes(key) : Object.prototype.hasOwnProperty.call(declared, key));
+    formOnly.forEach((key) => { if (!declares(key)) delete merged[key]; });
+    if (merged.options === undefined) delete merged.options;
+    return merged;
+  });
+  // 按钮和内容节点只接收普通属性
+  const contentAttrs = computed(() => {
+    const attrs = { ...(props.col.model?.[1] || {}) };
+    formOnly.forEach((key) => delete attrs[key]);
+    return attrs;
+  });
+
+  // 错误提示关联到实际输入元素，读屏软件才能读出；只移除自己加上的属性。
+  const root = ref<HTMLElement>();
+  const inputs = 'input:not([type=hidden]):not([type=search]), textarea, select, [contenteditable="true"], [role="radiogroup"]';
+  const describe = () => {
+    const el = root.value;
+    // 非 DOM 渲染环境（SSR、自定义渲染器）没有查询接口
+    if (!el || typeof el.querySelectorAll !== 'function') return;
+    const errorId = props.col._error && props.mode !== 'view' ? `${props.col._fid}-error` : '';
+    el.querySelectorAll<HTMLElement>(inputs).forEach((node) => {
+      if (errorId) {
+        node.setAttribute('aria-invalid', 'true');
+        node.setAttribute('aria-describedby', errorId);
+        node.dataset.formAria = '';
+      } else if (node.dataset.formAria !== undefined) {
+        node.removeAttribute('aria-invalid');
+        node.removeAttribute('aria-describedby');
+        delete node.dataset.formAria;
+      }
+    });
+  };
+  onMounted(describe);
+  onUpdated(describe);
+  watch(() => [props.col._error, props.mode], () => nextTick(describe));
+</script>