@dazhicheng/ui 1.5.33 → 1.5.35

package/dist/components/tt-form/src/types.d.ts

@@ -0,0 +1,452 @@
+import { ButtonProps, CheckboxProps, CheckboxGroupProps, DatePickerProps, InputProps, InputNumberProps, RadioProps, RadioGroupProps, SelectProps, SelectV2Props, SwitchProps, TimePickerDefaultProps, UploadProps, CascaderProps, ColorPickerProps } from 'element-plus';
+import { FieldOptions, FormContext, GenericObject } from 'vee-validate';
+import { Component, HtmlHTMLAttributes, MaybeRefOrGetter, Ref, VNode } from 'vue';
+import { ZodTypeAny } from 'zod';
+import { TtTextProps } from '../../tt-text';
+import { TtSelectProp } from '../../tt-select';
+import { TtUploadProps } from '../../tt-upload';
+import { FormApi } from './formApi';
+export type FormLayout = "horizontal" | "inline" | "vertical";
+export interface BaseFormComponentMap {
+    TtSelect: TtSelectProp;
+    ElCheckbox: CheckboxProps;
+    ElCheckboxButton: CheckboxProps;
+    ElCheckboxGroup: CheckboxGroupProps;
+    ElDatePicker: DatePickerProps;
+    ElInput: InputProps;
+    ElInputNumber: InputNumberProps;
+    ElRadio: RadioProps;
+    ElRadioGroup: RadioGroupProps;
+    ElSelect: SelectProps;
+    ElSelectV2: SelectV2Props;
+    ElSwitch: SwitchProps;
+    ElTimePicker: TimePickerDefaultProps;
+    ElTreeSelect: Record<string, any>;
+    ElUpload: UploadProps;
+    ElCascader: CascaderProps;
+    TtUpload: TtUploadProps;
+    ElColorPicker: ColorPickerProps;
+}
+/**
+ * 表单组件类型字符串联合类型
+ * 基于 BaseFormComponentMap 接口的键名
+ */
+export type BaseFormComponentType = keyof BaseFormComponentMap;
+type Breakpoints = "2xl:" | "3xl:" | "" | "lg:" | "md:" | "sm:" | "xl:";
+type GridCols = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
+export type WrapperClassType = `${Breakpoints}grid-cols-${GridCols}` | (Record<never, never> & string);
+export type FormItemClassType = `${Breakpoints}cols-end-${"auto" | GridCols}` | `${Breakpoints}cols-span-${"auto" | "full" | GridCols}` | `${Breakpoints}cols-start-${"auto" | GridCols}` | (Record<never, never> & string) | WrapperClassType;
+export type FormFieldOptions = Partial<FieldOptions & {
+    validateOnBlur?: boolean;
+    validateOnChange?: boolean;
+    validateOnInput?: boolean;
+    validateOnModelUpdate?: boolean;
+}>;
+export interface FormShape {
+    /** 默认值 */
+    default?: any;
+    /** 字段名 */
+    fieldName: string;
+    /** 是否必填 */
+    required?: boolean;
+    rules?: ZodTypeAny;
+}
+export type MaybeComponentPropKey = "options" | "placeholder" | "title" | keyof HtmlHTMLAttributes | (Record<never, never> & string);
+export type MaybeComponentProps = {
+    [K in MaybeComponentPropKey]?: any;
+};
+export type FormActions = FormContext<GenericObject>;
+export type CustomRenderType = (() => Component | string) | string;
+export type FormSchemaRuleType = "required" | "selectRequired" | null | (Record<never, never> & string) | ZodTypeAny;
+type FormItemDependenciesCondition<T = boolean | PromiseLike<boolean>> = (value: Partial<Record<string, any>>, actions: FormActions) => T;
+type FormItemDependenciesConditionWithRules = (value: Partial<Record<string, any>>, actions: FormActions) => FormSchemaRuleType | PromiseLike<FormSchemaRuleType>;
+type FormItemDependenciesConditionWithProps = (value: Partial<Record<string, any>>, actions: FormActions) => MaybeComponentProps | PromiseLike<MaybeComponentProps>;
+export interface FormItemDependencies {
+    /**
+     * 组件参数
+     * @returns 组件参数
+     */
+    componentProps?: FormItemDependenciesConditionWithProps;
+    /**
+     * 是否禁用
+     * @returns 是否禁用
+     */
+    disabled?: boolean | FormItemDependenciesCondition;
+    /**
+     * 是否渲染（删除dom）
+     * @returns 是否渲染
+     */
+    if?: boolean | FormItemDependenciesCondition;
+    /**
+     * 是否必填
+     * @returns 是否必填
+     */
+    required?: FormItemDependenciesCondition;
+    /**
+     * 字段规则
+     */
+    rules?: FormItemDependenciesConditionWithRules;
+    /**
+     * 是否隐藏(Css)
+     * @returns 是否隐藏
+     */
+    show?: boolean | FormItemDependenciesCondition;
+    /**
+     * 任意触发都会执行
+     */
+    trigger?: FormItemDependenciesCondition<void>;
+    /**
+     * 触发字段
+     */
+    triggerFields: string[];
+}
+type ComponentProps = ((value: Partial<Record<string, any>>, actions: FormActions) => MaybeComponentProps) | MaybeComponentProps;
+export interface FormCommonConfig {
+    /**
+     * 在Label后显示一个冒号
+     */
+    colon?: boolean;
+    /**
+     * 所有表单项的props
+     */
+    componentProps?: ComponentProps;
+    /**
+     * 所有表单项的控件样式
+     */
+    controlClass?: string;
+    /**
+     * 所有表单项的禁用状态
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 是否禁用所有表单项的change事件监听
+     * @default true
+     */
+    disabledOnChangeListener?: boolean;
+    /**
+     * 是否禁用所有表单项的input事件监听
+     * @default true
+     */
+    disabledOnInputListener?: boolean;
+    /**
+     * 所有表单项的空状态值,默认都是undefined，naive-ui的空状态值是null
+     */
+    emptyStateValue?: null | undefined;
+    /**
+     * 所有表单项的控件样式
+     * @default {}
+     */
+    formFieldProps?: FormFieldOptions;
+    /**
+     * 所有表单项的栅格布局，支持函数形式
+     * @default ""
+     */
+    formItemClass?: (() => string) | string;
+    /**
+     * 隐藏所有表单项label
+     * @default false
+     */
+    hideLabel?: boolean;
+    /**
+     * 是否隐藏必填标记
+     * @default false
+     */
+    hideRequiredMark?: boolean;
+    /**
+     * 所有表单项的label样式
+     * @default ""
+     */
+    labelClass?: string;
+    /**
+     * 所有表单项的label宽度
+     */
+    labelWidth?: number;
+    /**
+     * 所有表单项的model属性名
+     * @default "modelValue"
+     */
+    modelPropName?: string;
+    /**
+     * 所有表单项的wrapper样式
+     */
+    wrapperClass?: string;
+}
+type RenderComponentContentType = (value: Partial<Record<string, any>>, api: FormActions) => Record<string, any>;
+export type HandleSubmitFn = (values: Record<string, any>) => Promise<void> | void;
+export type HandleResetFn = (values: Record<string, any>) => Promise<void> | void;
+export type FieldMappingTime = [
+    string,
+    [
+        string,
+        string
+    ],
+    (((value: any, fieldName: string) => any) | [string, string] | null | string)?
+][];
+export type ArrayToStringFields = Array<[string[], string?] | string | string[]>;
+export interface FormSchema<T extends BaseFormComponentType = BaseFormComponentType> extends FormCommonConfig {
+    /** 组件 */
+    component: Component | T;
+    /** 组件参数 */
+    componentProps?: ComponentProps;
+    /** 默认值 */
+    defaultValue?: any;
+    /** 依赖 */
+    dependencies?: FormItemDependencies;
+    /** 描述 */
+    description?: CustomRenderType;
+    /** 字段名 */
+    fieldName: string;
+    /** 帮助信息 */
+    help?: CustomRenderType;
+    /** 是否隐藏表单项 */
+    hide?: boolean;
+    /** 表单项 */
+    label?: CustomRenderType;
+    renderComponentContent?: RenderComponentContentType;
+    /** 字段规则 */
+    rules?: FormSchemaRuleType;
+    /** 后缀 */
+    suffix?: CustomRenderType;
+    /** 帮助信息触发器 */
+    helpTrigger?: "hover" | "click" | "focus" | "contextmenu";
+    /** label本身文字气泡设置 */
+    toolTip?: TtTextProps;
+    /** 非label文字气泡设置 */
+    toolTipText?: CustomRenderType;
+}
+/** 插槽 scope 参数，传递给渲染函数或具名插槽 */
+export interface FormSlotScope {
+    /** 当前表单所有字段的值 */
+    values: Record<string, any>;
+    /** 表单操作方法（validate / resetForm / getValues 等） */
+    formActions: FormActions;
+}
+/**
+ * 自定义插槽 schema，在表单字段之间插入任意自定义内容。
+ * content 为字符串时作为具名插槽名，在模板中用 `<template #slotName="{ values, formActions }">` 编写；
+ * content 为函数时直接返回 VNode。
+ * @property {"slot"} type - 固定为 "slot"
+ * @property {string | ((scope: FormSlotScope) => VNode)} content - 插槽名或渲染函数
+ * @property {WrapperClassType} [wrapperClass] - 容器额外 class（如 col-span-full）
+ */
+export interface FormSlotSchema {
+    /** 类型标识 */
+    type: "slot";
+    /** 插槽名（字符串）或渲染函数 */
+    content: string | ((scope: FormSlotScope) => VNode);
+    /** 容器额外 class */
+    wrapperClass?: WrapperClassType;
+    /**
+     * 是否显示，支持布尔值或函数 (values, actions) => boolean | Promise<boolean>，默认 true。
+     * 仅在 GroupForm 场景下生效。
+     */
+    ifShow?: boolean | ((values: Record<string, any>, actions: FormActions) => boolean | PromiseLike<boolean>);
+}
+export interface FormFieldProps extends FormSchema {
+    required?: boolean;
+}
+export interface FormRenderProps<T extends BaseFormComponentType = BaseFormComponentType> {
+    /**
+     * 表单字段数组映射字符串配置 默认使用","
+     */
+    arrayToStringFields?: ArrayToStringFields;
+    /**
+     * 是否折叠，在showCollapseButton=true下生效
+     * true:折叠 false:展开
+     */
+    collapsed?: boolean;
+    /**
+     * 折叠时保持行数
+     * @default 1
+     */
+    collapsedRows?: number;
+    /**
+     * 是否触发resize事件
+     * @default false
+     */
+    collapseTriggerResize?: boolean;
+    /**
+     * 表单项通用后备配置，当子项目没配置时使用这里的配置，子项目配置优先级高于此配置
+     */
+    commonConfig?: FormCommonConfig;
+    /**
+     * 紧凑模式（移除表单每一项底部为校验信息预留的空间）
+     */
+    compact?: boolean;
+    /**
+     * 组件v-model事件绑定
+     */
+    componentBindEventMap?: Partial<Record<BaseFormComponentType, string>>;
+    /**
+     * 组件集合
+     */
+    componentMap: Record<BaseFormComponentType, Component>;
+    /**
+     * 表单字段映射到时间格式
+     */
+    fieldMappingTime?: FieldMappingTime;
+    /**
+     * 表单实例
+     */
+    form?: FormContext<GenericObject>;
+    /**
+     * 表单项布局
+     */
+    layout?: FormLayout;
+    /**
+     * 表单定义，支持普通字段和自定义插槽混合
+     */
+    schema?: (FormSchema<T> | FormSlotSchema)[];
+    /**
+     * 是否显示展开/折叠
+     */
+    showCollapseButton?: boolean;
+    /**
+     * 格式化日期
+     */
+    /**
+     * 表单栅格布局
+     * @default "grid-cols-1"
+     */
+    wrapperClass?: WrapperClassType;
+}
+export type ActionButtonOptions = {
+    [key: string]: any;
+    content?: MaybeRefOrGetter<string>;
+    show?: boolean;
+    customFn?: (value: Record<string, any>) => Record<string, any>;
+} & Partial<ButtonProps>;
+export interface TtFormProps<T extends BaseFormComponentType = BaseFormComponentType> extends Omit<FormRenderProps<T>, "componentBindEventMap" | "componentMap" | "form"> {
+    /**
+     * 操作按钮是否反转（提交按钮前置）
+     */
+    actionButtonsReverse?: boolean;
+    /**
+     * 操作按钮组的样式
+     * newLine: 在新行显示。rowEnd: 在行内显示，靠右对齐（默认）。inline: 使用grid默认样式
+     */
+    actionLayout?: "inline" | "newLine" | "rowEnd";
+    /**
+     * 操作按钮组显示位置，默认靠右显示
+     */
+    actionPosition?: "center" | "left" | "right";
+    /**
+     * 表单操作区域class
+     */
+    actionWrapperClass?: Array<object | string> | object | string;
+    /**
+     * 表单字段数组映射字符串配置 默认使用","
+     */
+    arrayToStringFields?: ArrayToStringFields;
+    /**
+     * 表单字段映射
+     */
+    fieldMappingTime?: FieldMappingTime;
+    /**
+     * 表单收起展开状态变化回调
+     */
+    handleCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * 表单重置回调
+     */
+    handleReset?: HandleResetFn;
+    /**
+     * 表单提交回调
+     */
+    handleSubmit?: HandleSubmitFn;
+    /**
+     * 表单值变化回调
+     */
+    handleValuesChange?: (values: Record<string, any>, fieldsChanged: string[]) => void;
+    /**
+     * 重置按钮参数
+     */
+    resetButtonOptions?: ActionButtonOptions;
+    /**
+     * 验证失败时是否自动滚动到第一个错误字段
+     * @default false
+     */
+    scrollToFirstError?: boolean;
+    /**
+     * 是否显示默认操作按钮
+     * @default true
+     */
+    showDefaultActions?: boolean;
+    /**
+     * 提交按钮参数
+     */
+    submitButtonOptions?: ActionButtonOptions;
+    /**
+     * 是否在字段值改变时提交表单
+     * @default false
+     */
+    submitOnChange?: boolean;
+    /**
+     * 是否在回车时提交表单
+     * @default false
+     */
+    submitOnEnter?: boolean;
+}
+export type ExtendedFormApi = Omit<FormApi, "getValues" | "validate"> & {
+    /**
+     * 校验表单，支持通过第二个参数控制是否滚动到第一个错误分组
+     * @param {any} [opts] - 原始 validate 选项
+     * @param {boolean} [scrollToError] - 是否滚动到第一个错误分组，不传时使用全局配置 scrollToFirstError
+     */
+    validate: (opts?: any, scrollToError?: boolean) => Promise<{
+        valid: boolean;
+        errors: Record<string, string>;
+        results?: any;
+    }>;
+    /**
+     * 获取表单值
+     * @param {boolean} [isGroup] - 为 true 时返回按分组 key 嵌套的对象，默认 false 返回扁平值
+     * @returns {Promise<T>} 表单值
+     */
+    getValues: <T = Record<string, any>>(isGroup?: boolean) => Promise<T>;
+    useStore: <T = NoInfer<TtFormProps>>(selector?: (state: NoInfer<TtFormProps>) => T) => Readonly<Ref<T>>;
+    /** 滚动到指定分组（仅 useGroupForm 场景下可用） */
+    scrollToGroup?: (key: string) => void;
+    /**
+     * 动态更新分组 schema（同时更新 UI 渲染和底层字段注册），仅 useGroupForm 场景下可用
+     * @param {any[]} newSchema - 新的分组 schema（实际类型为 GroupFormSchema[]，此处用 any[] 避免循环依赖）
+     */
+    updateGroupSchema?: (newSchema: any[]) => void;
+    /**
+     * 在指定分组中增量插入字段，无需全量重建 schema
+     * @param {string} groupKey - 目标分组的 key
+     * @param {any[]} fields - 要插入的字段或子结构（实际类型为 GroupFormSchema[]）
+     * @param {InsertPosition} [position] - 插入位置：before/after 匹配 fieldName、slot content 或 group key；省略则追加到末尾
+     */
+    appendFields?: (groupKey: string, fields: any[], position?: {
+        before?: string;
+        after?: string;
+    }) => void;
+    /**
+     * 按字段名从 groupSchema 树中移除字段，无需全量重建 schema
+     * @param {string[]} fieldNames - 要移除的字段名列表
+     */
+    removeFields?: (fieldNames: string[]) => void;
+};
+export interface TtFormAdapterOptions<T extends BaseFormComponentType = BaseFormComponentType> {
+    config?: {
+        baseModelPropName?: string;
+        disabledOnChangeListener?: boolean;
+        disabledOnInputListener?: boolean;
+        emptyStateValue?: null | undefined;
+        modelPropNameMap?: Partial<Record<T, string>>;
+    };
+    defineRules?: {
+        required?: (value: any, params: any, ctx: Record<string, any>) => boolean | string;
+        selectRequired?: (value: any, params: any, ctx: Record<string, any>) => boolean | string;
+    };
+}
+/**
+ * 根据组件类型推断组件参数类型的基础类型
+ * Base type for component props based on component type
+ * @template T - 组件类型（内置组件名或自定义组件）
+ * @template P - 自定义组件的 Props 类型（可选，用于自定义组件类型推断）
+ */
+export type InferredComponentPropsType<T extends BaseFormComponentType | Component, P = never> = T extends BaseFormComponentType ? Partial<BaseFormComponentMap[T]> & MaybeComponentProps : [P] extends [never] ? MaybeComponentProps : Partial<P> & MaybeComponentProps;
+export {};

package/dist/components/tt-form/src/useForm.d.ts

@@ -0,0 +1,2 @@
+import { BaseFormComponentType, ExtendedFormApi, TtFormProps } from './types';
+export declare function useForm<T extends BaseFormComponentType = BaseFormComponentType>(options: TtFormProps<T>): readonly [import('vue').DefineSetupFnComponent<TtFormProps<keyof import('./types').BaseFormComponentMap>, {}, {}, TtFormProps<keyof import('./types').BaseFormComponentMap> & {}, import('vue').PublicProps>, ExtendedFormApi];

package/dist/components/tt-form/src/useFormContext.d.ts

@@ -0,0 +1,12 @@
+import { ComputedRef } from 'vue';
+import { ExtendedFormApi, FormActions, TtFormProps } from './types';
+type ExtendFormProps = TtFormProps & {
+    formApi?: ExtendedFormApi;
+};
+export declare const injectFormProps: <T extends [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions] | null | undefined = [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions]>(fallback?: T | undefined) => T extends null ? [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions] | null : [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions], provideFormProps: (contextValue: [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions]) => [ExtendFormProps | ComputedRef<ExtendFormProps>, FormActions];
+export declare const injectComponentRefMap: <T extends Map<string, unknown> | null | undefined = Map<string, unknown>>(fallback?: T | undefined) => T extends null ? Map<string, unknown> | null : Map<string, unknown>, provideComponentRefMap: (contextValue: Map<string, unknown>) => Map<string, unknown>;
+export declare function useFormInitial(props: ComputedRef<TtFormProps> | TtFormProps): {
+    delegatedSlots: ComputedRef<string[]>;
+    form: import('vee-validate').FormContext<Record<string, any>, Record<string, any>>;
+};
+export {};