@_tc/template-core 0.0.1-bate.37 → 0.0.1-bate.39

package/fe/packages/ui/react/components/Button/Button.js

@@ -9,6 +9,7 @@ const Button = forwardRef((props, ref) => {
     const loading = loadingProp;
     const disabled = disabledProp;
     const isDisabled = disabled || loading;
+    // 基础样式
     const baseStyles = 'inline-flex items-center justify-center rounded-lg font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 cursor-pointer';
     const getVariantStyles = () => {
         if (variant === 'text' || variant === 'link') {
@@ -34,6 +35,7 @@ const Button = forwardRef((props, ref) => {
         return cn(variantStyles[variant], ghostStyles);
     };
     const disabledStyles = 'disabled:bg-background/60 disabled:border-border/60 disabled:text-foreground/40 disabled:hover:bg-background/60 aria-disabled:text-foreground/40 aria-disabled:hover:bg-transparent';
+    // 尺寸样式
     const sizeStyles = {
         sm: 'h-8 px-3 text-sm',
         md: 'h-10 px-4 text-sm',
@@ -45,6 +47,7 @@ const Button = forwardRef((props, ref) => {
         lg: 'h-5 w-5',
     };
     const loadingIcon = loading ? (_jsx("span", { className: cn('flex items-center', children && 'mr-2'), children: _jsxs("svg", { className: cn('animate-spin', spinnerSize[size]), xmlns: "http://www.w3.org/2000/svg", fill: "none", viewBox: "0 0 24 24", children: [_jsx("circle", { className: "opacity-25", cx: "12", cy: "12", r: "10", stroke: "currentColor", strokeWidth: "4" }), _jsx("path", { className: "opacity-75", fill: "currentColor", d: "M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z" })] }) }, "loading")) : null;
+    // 展示内容
     const contents = [
         loadingIcon,
         !loading && leftIcon && (_jsx("span", { className: cn('flex items-center', 'mr-2'), children: leftIcon }, "left")),

package/fe/packages/ui/react/components/Button/SumbitButton.d.ts

@@ -3,6 +3,10 @@ import { type ButtonElementProps } from './Button';
 export type SumbitButtonProps = MOmit<ButtonElementProps, 'onClick'> & {
     onClick?: (e: React.MouseEvent<HTMLButtonElement, MouseEvent>) => Promise<void | boolean> | void;
 };
+/**
+ *
+ * 会自动添加loading 其余同button一致
+ */
 declare const SumbitButton: (props: SumbitButtonProps) => import("react/jsx-runtime").JSX.Element;
 declare const AsynchronousButton: (props: SumbitButtonProps) => import("react/jsx-runtime").JSX.Element;
 export { AsynchronousButton, SumbitButton };

package/fe/packages/ui/react/components/Button/SumbitButton.js

@@ -2,6 +2,10 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from '../../lib/utils';
 import { useState } from 'react';
 import { Button } from './Button';
+/**
+ *
+ * 会自动添加loading 其余同button一致
+ */
 const SumbitButton = (props) => {
     const { onClick, className, loading: loadingProp, ...bprops } = props;
     const [loading, uLoading] = useState(false);

package/fe/packages/ui/react/components/ConfirmDialog/ConfirmDialog.d.ts

@@ -1,11 +1,19 @@
 export interface ConfirmDialogProps {
+    /** 是否显示 */
     open: boolean;
+    /** 标题 */
     title?: string;
+    /** 内容 */
     content: string;
+    /** 确认按钮文本 */
     okText?: string;
+    /** 取消按钮文本 */
     cancelText?: string;
+    /** 确认按钮加载状态 */
     loading?: boolean;
+    /** 确认回调 */
     onOk: () => void | Promise<void>;
+    /** 取消回调 */
     onCancel: () => void;
 }
 export declare function ConfirmDialog({ open, title, content, okText, cancelText, loading, onOk, onCancel, }: ConfirmDialogProps): import("react/jsx-runtime").JSX.Element;

package/fe/packages/ui/react/components/DataTable/index.d.ts

@@ -9,10 +9,25 @@ type DataTableActionColumnOptions<T> = {
 };
 type TableColumnDef<T = Record<string, unknown>> = ColumnDef<T> & DataTableActionColumnOptions<T>;
 type RowSelection<T> = {
+    /**
+     * 受控用法：完全由外部维护选中 keys
+     */
     selectedRowKeys?: Array<string | number>;
+    /**
+     * 非受控用法：仅作为初始值，后续由内部维护
+     */
     defaultSelectedRowKeys?: Array<string | number>;
+    /**
+     * 选中项变化回调（受控/非受控都会触发）
+     */
     onChange?: (selectedRowKeys: Array<string | number>, selectedRows: T[], isAll: boolean) => void;
+    /**
+     * 全选 受控
+     */
     isAll?: boolean;
+    /**
+     * theader checkbox
+     */
     beforeCheckboxNode?: ReactNode;
 };
 interface DataTableProps<T = Record<string, unknown>> {
@@ -22,6 +37,10 @@ interface DataTableProps<T = Record<string, unknown>> {
     rowSelection?: RowSelection<T>;
     pagination?: PaginationProps;
     loading?: boolean;
+    /**
+     * 统一配置 column width 默认100px
+     * 会被columns[number].width覆盖
+     */
     defaultColumnWidth?: number;
 }
 export declare function DataTable<T = Record<string, unknown>>({ columns, data: pData, loading, rowKey, rowSelection, defaultColumnWidth, pagination: pPagination, }: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;

package/fe/packages/ui/react/components/DataTable/index.js

@@ -35,10 +35,12 @@ export function DataTable({ columns, data: pData, loading, rowKey = defaultRowKe
         let data = pData;
         let showPagination;
         let pageStartIndex = 0;
+        // 使用外部
         if (pPagination) {
             pagination = pPagination;
             showPagination = pagination.total > 0;
         }
+        // 使用内部
         else {
             pagination = {
                 onChange(v) {
@@ -82,8 +84,10 @@ export function DataTable({ columns, data: pData, loading, rowKey = defaultRowKe
             const pageKeySet = new Set(pageRowKeys);
             nextSelectedKeys = Array.from(new Set([
                 ...selectedRowKeys,
+                //
                 ...pageRowKeys.filter((key) => !selectedKeySet.has(key)),
             ]))
+                //
                 .filter((key) => pageKeySet.has(key) || selectedKeySet.has(key));
         }
         else {

package/fe/packages/ui/react/components/Date/Calendar.d.ts

@@ -5,7 +5,13 @@ export type DateRange = {
     to?: Date | undefined;
 };
 export type QuickRangePreset = {
+    /**
+     * 展示文案
+     */
     label: string;
+    /**
+     * 返回一个范围对象
+     */
     getRange: () => DateRange;
 };
 export interface CalendarProps {
@@ -15,7 +21,14 @@ export interface CalendarProps {
     disabledDate?: (date: Date) => boolean;
     showTime?: boolean;
     className?: string;
+    /**
+     * 自定义文案配置，会覆盖默认文案
+     */
     locale?: Partial<DateLocaleConfig>;
+    /**
+     * 范围模式下的快捷选择配置
+     * 不传则使用默认预设
+     */
     quickRanges?: QuickRangePreset[];
 }
 export declare function Calendar({ mode, value, onChange, disabledDate, showTime, className, locale: customLocale, quickRanges, }: CalendarProps): import("react/jsx-runtime").JSX.Element;

package/fe/packages/ui/react/components/Date/Calendar.js

@@ -11,7 +11,9 @@ import { TimePicker } from './TimePicker';
 export function Calendar({ mode = ModeType.Single, value, onChange, disabledDate, showTime, className, locale: customLocale, quickRanges, }) {
     const contextLocale = useDateLocale();
     const locale = useMemo(() => ({ ...contextLocale, ...customLocale }), [contextLocale, customLocale]);
+    // Pending value for showTime mode (confirmed on button click)
     const [pendingValue, setPendingValue] = useState(value ?? null);
+    // 当前显示的月份
     const [currentMonth, setCurrentMonth] = useState(() => {
         if (value instanceof Date)
             return value;
@@ -19,7 +21,9 @@ export function Calendar({ mode = ModeType.Single, value, onChange, disabledDate
             return value.from;
         return new Date();
     });
+    // 悬停日期（用于范围选择预览）
     const [hoverDate, setHoverDate] = useState(null);
+    // 生成日历网格数据
     const days = useMemo(() => {
         const monthStart = startOfMonth(currentMonth);
         const monthEnd = endOfMonth(monthStart);
@@ -107,6 +111,7 @@ export function Calendar({ mode = ModeType.Single, value, onChange, disabledDate
     const handleDateClick = (date) => {
         if (disabledDate?.(date))
             return;
+        // Preserve time when showTime is enabled
         let dateWithTime = date;
         if (showTime && pendingValue instanceof Date) {
             dateWithTime = new Date(date);
@@ -116,6 +121,7 @@ export function Calendar({ mode = ModeType.Single, value, onChange, disabledDate
             dateWithTime.setMilliseconds(0);
         }
         if (showTime) {
+            // In showTime mode, store in pending value
             if (mode === ModeType.Single) {
                 setPendingValue(dateWithTime);
             }
@@ -135,6 +141,7 @@ export function Calendar({ mode = ModeType.Single, value, onChange, disabledDate
             }
         }
         else {
+            // Without showTime, directly call onChange
             if (mode === ModeType.Single) {
                 onChange?.(dateWithTime);
             }
@@ -191,7 +198,9 @@ export function Calendar({ mode = ModeType.Single, value, onChange, disabledDate
                                     const isCurrentMonth = isSameMonth(date, currentMonth);
                                     const isDisabled = disabledDate?.(date);
                                     return (_jsx("div", { className: "flex justify-center p-0", children: _jsx(Button, { variant: "text", type: "button", onClick: () => handleDateClick(date), onMouseEnter: () => setHoverDate(date), disabled: isDisabled, className: cn('w-8 h-8 flex items-center justify-center rounded text-sm transition-colors relative z-10', !isCurrentMonth && 'text-muted-foreground/40', isCurrentMonth && !selected && !inRange && !isDisabled && 'text-foreground hover:bg-muted', selected && 'bg-theme text-theme-foreground hover:bg-theme/90', inRange && !selected && 'bg-theme/10 text-theme', !selected && !inRange && isToday && 'border border-theme text-theme', isDisabled && 'text-muted-foreground cursor-not-allowed hover:bg-transparent opacity-50'), children: format(date, 'd') }) }, i));
-                                }) })] }), showTime && (_jsx("div", { className: "flex flex-col border-l border-border pl-4", children: mode === ModeType.Single ? (_jsxs("div", { className: "flex flex-col justify-center h-full", children: [_jsx("div", { className: "text-xs font-medium text-muted-foreground mb-3 text-center", children: locale.selectTime }), _jsx(TimePicker, { value: pendingValue instanceof Date ? pendingValue : undefined, onChange: handleTimeChangeInternal, className: "border-0" })] })) : (_jsxs("div", { className: "space-y-4 flex flex-col justify-center h-full", children: [_jsxs("div", { children: [_jsx("div", { className: "text-xs font-medium text-muted-foreground mb-2 text-center", children: locale.startTime }), _jsx(TimePicker, { value: pendingValue && 'from' in pendingValue && pendingValue.from ? pendingValue.from : undefined, onChange: (newDate) => {
+                                }) })] }), showTime && (_jsx("div", { className: "flex flex-col border-l border-border pl-4", children: mode === ModeType.Single ? (_jsxs("div", { className: "flex flex-col justify-center h-full", children: [_jsx("div", { className: "text-xs font-medium text-muted-foreground mb-3 text-center", children: locale.selectTime }), _jsx(TimePicker, { value: pendingValue instanceof Date ? pendingValue : undefined, onChange: handleTimeChangeInternal, className: "border-0" })] })) : (
+                        // Range mode: show two time pickers
+                        _jsxs("div", { className: "space-y-4 flex flex-col justify-center h-full", children: [_jsxs("div", { children: [_jsx("div", { className: "text-xs font-medium text-muted-foreground mb-2 text-center", children: locale.startTime }), _jsx(TimePicker, { value: pendingValue && 'from' in pendingValue && pendingValue.from ? pendingValue.from : undefined, onChange: (newDate) => {
                                                 const range = pendingValue;
                                                 setPendingValue({
                                                     from: newDate,

package/fe/packages/ui/react/components/Date/Date.d.ts

@@ -9,6 +9,9 @@ export type DatePickerProps = {
     mode?: ModeType;
     value?: DateValue;
     defaultValue?: DateValue;
+    /**
+     * @default 'yyyy-MM-dd'
+     */
     format?: string;
     placeholder?: string;
     disabled?: boolean;
@@ -17,8 +20,16 @@ export type DatePickerProps = {
     onChange?: (value?: DateChangeStrValue, date?: Dates) => void;
     disabledDate?: (current: Date) => boolean;
     className?: string;
+    /**
+     * 自定义文案配置，会覆盖默认文案
+     */
     locale?: Partial<DateLocaleConfig>;
+    /**
+     * 范围模式下的快捷选择配置
+     * 不传则使用默认预设
+     */
     quickRanges?: QuickRangePreset[];
+    /** 自定义弹出容器，不传则默认挂载到 document.body */
     getPopupContainer?: () => HTMLElement;
 };
 declare const DatePicker: import("react").ForwardRefExoticComponent<DatePickerProps & import("react").RefAttributes<HTMLDivElement>>;

package/fe/packages/ui/react/components/Date/Date.js

@@ -29,6 +29,9 @@ const formatValue = (val, format) => {
 const formatDateValue = (val, format) => {
     if (!val)
         return "";
+    /**
+     * 将 DateBaseValue  转为  yyyy-MM-dd | [yyyy-MM-dd, yyyy-MM-dd]
+     */
     if (val instanceof Date)
         return formatDate(val, format);
     if ("from" in val) {
@@ -43,6 +46,7 @@ const DatePicker = forwardRef((props, ref) => {
     const isControlled = Object.prototype.hasOwnProperty.call(props, "value");
     const contextLocale = useDateLocale();
     const locale = { ...contextLocale, ...customLocale };
+    // 如果没有传入 placeholder，根据模式自动选择
     const finalPlaceholder = placeholder ||
         (showTime
             ? mode === ModeType.Range
@@ -51,15 +55,22 @@ const DatePicker = forwardRef((props, ref) => {
             : mode === ModeType.Range
                 ? locale.placeholderRange
                 : locale.placeholder);
+    // Auto-adjust format based on showTime
     const format = customFormat || (showTime ? "yyyy-MM-dd HH:mm" : "yyyy-MM-dd");
     const { value, defaultValue } = useMemo(() => {
+        /**
+         * 将 DateChangeStrValue 转为 Dates
+         */
         const convertValue = (val) => {
             if (!val)
                 return undefined;
+            // Already a Date object
             if (val instanceof Date)
                 return val;
+            // Already a DateRange object
             if (typeof val === "object" && "from" in val)
                 return val;
+            // String value - single date
             if (typeof val === "string") {
                 try {
                     const parsed = parse(val, format, new Date());
@@ -69,7 +80,9 @@ const DatePicker = forwardRef((props, ref) => {
                     return undefined;
                 }
             }
+            // date range
             if (Array.isArray(val)) {
+                // string
                 if (typeof val[0] === "string" && typeof val[1] === "string") {
                     try {
                         const from = parse(val[0], format, new Date());
@@ -109,6 +122,7 @@ const DatePicker = forwardRef((props, ref) => {
         matchAnchorWidth: false,
         strategy: getDatePickerDropdownPosition,
     });
+    // 同步外部 value 变化
     useEffect(() => {
         if (!isControlled)
             return;
@@ -124,13 +138,17 @@ const DatePicker = forwardRef((props, ref) => {
     const handleSelect = (date) => {
         const newDate = date;
         if (mode === ModeType.Range) {
+            // 如果是范围选择，只有当 from 和 to 都存在时才关闭
             if (date && "from" in date && "to" in date && date.from && date.to) {
                 setIsOpen(false);
             }
         }
         else {
+            // Single mode: always close popup when onChange is triggered
+            // (In showTime mode, this only happens when user clicks confirm button)
             setIsOpen(false);
         }
+        // range 选择需要保留内部草稿态，避免受控 value 把第一步点击抹掉
         if (mode === ModeType.Range || !isControlled) {
             setSelectedDate(newDate);
             setInputValue(formatValue(newDate, format));
@@ -164,6 +182,7 @@ const DatePicker = forwardRef((props, ref) => {
                 }
             }
             catch {
+                // ignore invalid date
             }
         }
     };

package/fe/packages/ui/react/components/Date/LocaleContext.d.ts

@@ -1,2 +1,6 @@
+/**
+ * Hook for accessing the current Date component locale.
+ * Backed by Zustand, so no React Context is required.
+ */
 export declare const useDateLocale: () => import("./locales").DateLocaleConfig;
 //# sourceMappingURL=LocaleContext.d.ts.map

package/fe/packages/ui/react/components/Date/LocaleContext.js

@@ -1,4 +1,8 @@
 import { useDateLocaleStore } from './dateLocaleStore';
+/**
+ * Hook for accessing the current Date component locale.
+ * Backed by Zustand, so no React Context is required.
+ */
 export const useDateLocale = () => {
     return useDateLocaleStore((state) => state.locale);
 };

package/fe/packages/ui/react/components/Date/LocaleProvider.d.ts

@@ -4,5 +4,16 @@ export interface DateLocaleProviderProps {
     locale?: DateLocaleConfig;
     children: ReactNode;
 }
+/**
+ * Date 组件文案配置 Provider
+ * 用于全局设置 Date 组件的文案
+ *
+ * @example
+ * ```tsx
+ * <DateLocaleProvider locale={customLocale}>
+ *   <App />
+ * </DateLocaleProvider>
+ * ```
+ */
 export declare function DateLocaleProvider({ locale, children }: DateLocaleProviderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=LocaleProvider.d.ts.map

package/fe/packages/ui/react/components/Date/LocaleProvider.js

@@ -2,6 +2,17 @@ import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 import { useEffect } from 'react';
 import { useDateLocaleStore } from './dateLocaleStore';
 import { defaultLocale } from './locales';
+/**
+ * Date 组件文案配置 Provider
+ * 用于全局设置 Date 组件的文案
+ *
+ * @example
+ * ```tsx
+ * <DateLocaleProvider locale={customLocale}>
+ *   <App />
+ * </DateLocaleProvider>
+ * ```
+ */
 export function DateLocaleProvider({ locale = defaultLocale, children }) {
     const replaceLocale = useDateLocaleStore((state) => state.replaceLocale);
     const resetLocale = useDateLocaleStore((state) => state.resetLocale);

package/fe/packages/ui/react/components/Date/TimePicker.js

@@ -4,6 +4,7 @@ import { ChevronDown, ChevronUp } from 'lucide-react';
 import { Button } from '../Button';
 import { Input } from '../Input';
 export function TimePicker({ value, onChange, className }) {
+    // Derive time from value prop directly
     const hours = value?.getHours() ?? 0;
     const minutes = value?.getMinutes() ?? 0;
     const handleTimeChange = (newHours, newMinutes) => {

package/fe/packages/ui/react/components/Date/dateLocaleStore.d.ts

@@ -1,7 +1,13 @@
 import { type DateLocaleConfig } from './locales';
 type DateLocaleState = {
     locale: DateLocaleConfig;
+    /**
+     * Merge partial updates into the current locale.
+     */
     setLocale: (patch: Partial<DateLocaleConfig>) => void;
+    /**
+     * Replace the locale entirely.
+     */
     replaceLocale: (nextLocale: DateLocaleConfig) => void;
     resetLocale: () => void;
 };

package/fe/packages/ui/react/components/Date/locales.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Date 组件文案配置
+ * 支持外部修改文案内容
+ */
 export interface DateLocaleConfig {
     placeholder: string;
     placeholderDateTime: string;
@@ -9,7 +13,13 @@ export interface DateLocaleConfig {
     endTime: string;
     confirm: string;
     monthFormat: string;
+    /**
+     * 范围模式 - 快捷选择面板标题
+     */
     quickRanges: string;
+    /**
+     * 范围模式 - 各快捷范围文案
+     */
     quickRangeToday: string;
     quickRangeYesterday: string;
     quickRangeLast7Days: string;
@@ -18,7 +28,16 @@ export interface DateLocaleConfig {
     quickRangeLastYear: string;
     clear: string;
 }
+/**
+ * 默认中文文案
+ */
 export declare const zhCNLocale: DateLocaleConfig;
+/**
+ * 默认英文文案
+ */
 export declare const enUSLocale: DateLocaleConfig;
+/**
+ * 默认使用中文文案
+ */
 export declare const defaultLocale: DateLocaleConfig;
 //# sourceMappingURL=locales.d.ts.map

package/fe/packages/ui/react/components/Date/locales.js

@@ -1,12 +1,21 @@
 import { defaultEnglishResources, defaultLanguageResources } from '../../../../common/i18n';
 const dateDefaultLocale = defaultLanguageResources.components.date;
 const dateDefaultEnglishLocale = defaultEnglishResources.components.date;
+/**
+ * 默认中文文案
+ */
 export const zhCNLocale = {
     ...dateDefaultLocale,
     weekDays: [...dateDefaultLocale.weekDays],
 };
+/**
+ * 默认英文文案
+ */
 export const enUSLocale = {
     ...dateDefaultEnglishLocale,
     weekDays: [...dateDefaultEnglishLocale.weekDays],
 };
+/**
+ * 默认使用中文文案
+ */
 export const defaultLocale = zhCNLocale;

package/fe/packages/ui/react/components/Drawer/Drawer.d.ts

@@ -16,7 +16,13 @@ export type DrawerProps = {
     width?: number | string;
     height?: number | string;
     zIndex?: number;
+    /**
+     * @default document.body
+     */
     renderNode?: HTMLElement | (() => HTMLElement);
+    /**
+     * 是否支持键盘关闭 默认开启
+     */
     keyboard?: boolean;
 };
 export declare function Drawer({ open, onClose, title, children, footer, className, contentClassName, mask, maskClosable, lockScroll, closable, placement, width, height, renderNode, keyboard, zIndex, }: DrawerProps): import("react/jsx-runtime").JSX.Element;

package/fe/packages/ui/react/components/Dropdown/Dropdown.d.ts

@@ -18,6 +18,7 @@ export interface DropdownProps {
     children: ReactNode;
     className?: string;
     placement?: 'bottom-end' | 'bottom-start';
+    /** 自定义弹出容器，不传则默认挂载到 document.body */
     getPopupContainer?: () => HTMLElement;
 }
 export declare function Dropdown({ items, children, className, placement, getPopupContainer }: DropdownProps): import("react/jsx-runtime").JSX.Element;

package/fe/packages/ui/react/components/Form/Form.d.ts

@@ -1,7 +1,13 @@
 import type { FormProps as RcFormProps } from 'rc-field-form';
 import type { ReactNode } from 'react';
 export interface FormProps<T> extends Omit<RcFormProps<T>, 'component'> {
+    /**
+     * 表单类名
+     */
     className?: string;
+    /**
+     * 表单内容
+     */
     children?: ReactNode;
 }
 declare const Form: {

package/fe/packages/ui/react/components/Form/FormItem.d.ts

@@ -3,15 +3,36 @@ import type { ReactNode } from 'react';
 import { type LabelLayout } from '../Label';
 type FieldProps = Parameters<typeof Field>[0];
 export interface FormItemProps<T = any> extends Omit<FieldProps, 'children'> {
+    /**
+     * 表单项类名
+     */
     className?: string;
+    /**
+     * 标签文本
+     */
     label?: ReactNode;
+    /**
+     * 标签类名
+     */
     labelClassName?: string;
+    /**
+     * 是否必填（仅用于显示，实际验证通过 rules 配置）
+     */
     required?: boolean;
+    /**
+     * 表单项内容
+     */
     children?: ReactNode | ((value: T, onChange: (value: T) => void, meta: {
         errors: string[];
         warnings: string[];
     }) => ReactNode);
+    /**
+     * 错误信息类名
+     */
     errorClassName?: string;
+    /**
+     * 是否显示错误信息
+     */
     showError?: boolean;
     layout?: Required<LabelLayout>['layout'];
 }

package/fe/packages/ui/react/components/Form/FormItem.js

@@ -4,23 +4,30 @@ import { Field } from 'rc-field-form';
 import React, { forwardRef } from 'react';
 import Label from '../Label';
 const FormItemFN = forwardRef(({ className, label, labelClassName, required, children, errorClassName, showError = true, name, rules, layout, ...props }, ref) => {
-    return (_jsx(Field, { name: name, rules: rules, ...props, children: (control, meta) => {
+    return (_jsx(Field, { name: name, rules: rules, ...props, children: (control, meta /** form */) => {
             const { value, onChange, ...restControl } = control;
             const { errors, warnings } = meta;
             const hasError = errors.length > 0;
             const hasWarning = warnings.length > 0;
+            // 如果 children 是函数，调用它并传入 value、onChange 和 meta
             const childNode = typeof children === 'function' ? children(value, onChange, meta) : children;
+            // 克隆子元素并注入 value 和 onChange
             const childWithProps = childNode && typeof childNode === 'object' && 'props' in childNode
                 ? React.cloneElement(childNode, {
                     value: value,
                     onChange: (val) => {
+                        // 兼容 Input 组件的 onChange(value, event) 格式
+                        // Input 组件的 onChange 签名是: (value: string, event: ChangeEvent) => void
                         if (typeof val === 'string') {
+                            // 如果第一个参数是字符串，说明是 Input 组件的格式
                             onChange(val);
                         }
                         else if (val?.target?.value !== undefined) {
+                            // 原生 input 的 onChange 事件格式
                             onChange(val.target.value);
                         }
                         else {
+                            // 其他情况直接使用值
                             onChange(val);
                         }
                     },

package/fe/packages/ui/react/components/Form/SchemaForm/data.js

@@ -9,6 +9,7 @@ const baseComponentsMap = {
     date: React.lazy(async () => ({ default: (await import('../../Date')).DatePicker })),
     checkbox: React.lazy(async () => ({ default: (await import('../../Checkbox')).Checkbox })),
 };
+// componentsMap 合并内置 + 业务层扩展，支持动态注册新字段类型
 export const componentsMap = {
     ...baseComponentsMap,
     ...businessComponentsMap,