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

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

@@ -10,19 +10,52 @@ export type { FieldProps, SchemaFormComponentPropsMap, SchemaFormFieldType, Sche
 export type FormFieldType = SchemaFormAllFieldType;
 type BaseField<T> = {
     [K in keyof T]: {
+        /**
+         * 字段名
+         */
         key: K | number | (K | number)[];
+        /**
+         * 标签文本
+         */
         label?: ReactNode;
+        /**
+         * 验证规则
+         */
         rules?: Rule[];
+        /**
+         * 是否必填（仅用于显示，实际验证通过 rules 配置）
+         */
         required?: boolean;
+        /**
+         * 表单项类名
+         */
         className?: string;
+        /**
+         * 标签类名
+         */
         labelClassName?: string;
+        /**
+         * 错误信息类名
+         */
         errorClassName?: string;
+        /**
+         * 是否显示错误信息
+         */
         showError?: boolean;
+        /**
+         * 自定义渲染函数
+         */
         render?: (value: T[K], onChange: (value: T[K]) => void, meta: {
             errors: string[];
             warnings: string[];
         }) => ReactNode;
+        /**
+         * field label 布局方向
+         */
         layout?: Required<LabelLayout>['layout'];
+        /**
+         * 插入到控件后边
+         */
         affterNode?: ReactNode;
     };
 }[keyof T];
@@ -34,22 +67,82 @@ type GroupField<T> = {
 type NotGroupField<T> = FieldProps & BaseField<T>;
 export type FormFieldSchema<T> = GroupField<T> | NotGroupField<T>;
 export interface SchemaFormProps<T = object> extends MOmit<FormProps<T>, 'initialValues' | 'children' | 'preserve'> {
+    /**
+     * 表单实例
+     */
     form?: FormInstance<T>;
+    /**
+     * 获取当前使用的form实例  只有挂载后会调用一次
+     */
     getForm?: (formInstance: FormInstance<T>) => void;
+    /**
+     * 表单配置方案
+     */
     schemas: FormFieldSchema<T>[];
+    /**
+     * 表单类名
+     */
     className?: string;
+    /**
+     * 提交回调
+     */
     onFinish?: (values: T) => void;
+    /**
+     * 提交失败回调
+     */
     onFinishFailed?: (errorInfo: any) => void;
+    /**
+     * 初始值
+     */
     initialValues?: T;
+    /**
+     * form 布局方向
+     *
+     * tips: horizontal 需自行实现提交按钮
+     */
     layout?: Required<LabelLayout>['layout'];
+    /**
+     * 统一配置 field layout
+     */
     fieldLayout?: Required<LabelLayout>['layout'];
+    /**
+     * - 是否显示提交和取消按钮
+     * - 或自定义按钮
+     * - tips button type submit 可直接触发提交
+     * @default true
+     */
     footerButtons?: boolean | ReactNode;
+    /**
+     * 提交按钮文本
+     * @default '提交'
+     */
     submitText?: ReactNode;
+    /**
+     * 取消按钮文本
+     * @default '取消'
+     */
     cancelText?: ReactNode;
+    /**
+     * 取消按钮回调
+     */
     onCancel?: () => void;
+    /**
+     * 按钮容器类名
+     */
     buttonClassName?: string;
+    /**
+     * 提交按钮属性
+     */
     submitButtonProps?: Omit<ButtonElementProps, 'type' | 'onClick' | 'children'>;
+    /**
+     * 取消按钮属性
+     */
     cancelButtonProps?: Omit<ButtonElementProps, 'onClick' | 'children'>;
+    /**
+     * 移除字段时保留值
+     *
+     * @default false
+     */
     preserve?: boolean;
 }
 export declare const SchemaForm: {

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

@@ -8,6 +8,7 @@ import { Skeleton } from '../../Skeleton';
 import { componentsMap } from './data';
 const renderField = (schema) => {
     return (value, onChange, meta) => {
+        // 如果提供了自定义渲染函数，优先使用
         if (schema.render) {
             return schema.render(value, onChange, meta);
         }
@@ -22,7 +23,9 @@ const renderField = (schema) => {
         return (_jsxs(Suspense, { fallback: _jsx(Skeleton, { mode: "componentsloading", rows: 2 }), children: [_jsx(ComponentRenderer, { value: value, onChange: onChange, ...fieldProps }), schema.affterNode] }));
     };
 };
-export const SchemaForm = ({ form, getForm, schemas, className, onFinish, onFinishFailed, initialValues, footerButtons = true, submitText, cancelText, onCancel, buttonClassName, submitButtonProps, layout = 'vertical', fieldLayout = 'vertical', cancelButtonProps, ...formProps }) => {
+export const SchemaForm = ({ form, getForm, schemas, className, onFinish, onFinishFailed, initialValues, footerButtons = true, submitText, cancelText, onCancel, buttonClassName, submitButtonProps, layout = 'vertical', fieldLayout = 'vertical', cancelButtonProps, 
+// preserve = false,
+...formProps }) => {
     const t = useI18n();
     const [f] = useForm();
     const getFormRef = useRef(getForm);
@@ -36,6 +39,7 @@ export const SchemaForm = ({ form, getForm, schemas, className, onFinish, onFini
             onCancel();
         }
         else {
+            // 如果没有提供 onCancel，默认重置表单
             usedForm?.resetFields();
         }
     };

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

@@ -126,12 +126,20 @@ function PreviewCore({ images, initialIndex, onClose }) {
                             if (!imgRef.current)
                                 return;
                             const { naturalWidth, naturalHeight, clientWidth, clientHeight } = imgRef.current;
+                            // 如果 lastScaleBeforeNatural 无值
+                            //  第一次点击
+                            //  将 scaleRef 复制给 lastScaleBeforeNatural
+                            //  正常赋值
+                            // 如果 lastScaleBeforeNatural 有值
+                            //  则使用 lastScaleBeforeNatural
+                            //  再清除 lastScaleBeforeNatural
                             if (lastScaleBeforeNatural.current === null) {
                                 const scaleToNatural = Math.max(naturalWidth / Math.max(clientWidth, 1), naturalHeight / Math.max(clientHeight, 1), 1);
                                 lastScaleBeforeNatural.current = scaleRef.current;
                                 setScale(scaleToNatural);
                             }
                             else {
+                                //
                                 setScale(lastScaleBeforeNatural.current);
                                 lastScaleBeforeNatural.current = null;
                             }

package/fe/packages/ui/react/components/ImagePreview/PreviewImage.d.ts

@@ -1,6 +1,9 @@
 import type { MOmit } from '../../types';
 import { type ImagePreviewControllerProps } from './ImagePreview';
 export type PreviewImageProps = MOmit<ImagePreviewControllerProps, 'open' | 'onClose'> & Pick<Partial<ImagePreviewControllerProps>, 'onClose'> & {
+    /**
+     * 缩略图边长，默认 80px
+     */
     thumbSize?: number | string;
     direction?: 'horizontal' | 'vertical';
 };

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

@@ -1,22 +1,44 @@
 import type { ChangeEvent, InputHTMLAttributes, ReactNode } from 'react';
 export type InputProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'defaultValue'> & {
     value?: string;
+    /**
+     *
+     * @param v input value
+     * @param e changeEvent
+     */
     onChange?: (v: string, e: ChangeEvent<HTMLInputElement>) => void;
+    /**
+     * 只有初始化时会使用
+     * 如果会改变请使用value
+     */
     defaultValue?: string;
     allowClear?: boolean | {
         clearIcon: ReactNode;
     };
+    /** 输入框内部右侧按钮 */
     addonAfter?: ReactNode;
+    /** 原生 input 节点的自定义 className */
     inputClassName?: string;
 };
 declare const Input: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange"> & {
     value?: string;
+    /**
+     *
+     * @param v input value
+     * @param e changeEvent
+     */
     onChange?: (v: string, e: ChangeEvent<HTMLInputElement>) => void;
+    /**
+     * 只有初始化时会使用
+     * 如果会改变请使用value
+     */
     defaultValue?: string;
     allowClear?: boolean | {
         clearIcon: ReactNode;
     };
+    /** 输入框内部右侧按钮 */
     addonAfter?: ReactNode;
+    /** 原生 input 节点的自定义 className */
     inputClassName?: string;
 } & import("react").RefAttributes<HTMLInputElement>>;
 export { Input };

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

@@ -10,6 +10,8 @@ const Input = forwardRef(({ className, inputClassName, type, value: controlledVa
         ref,
     });
     const isFileInput = type === 'file';
+    // 在change恒定时 不重复生成 fn
+    // isControlledRef setInternalValue 都是不会变的值
     const handleChange = useCallback((e) => {
         const newValue = e.target.value;
         if (!isFileInput && !isControlledRef.current) {
@@ -20,6 +22,7 @@ const Input = forwardRef(({ className, inputClassName, type, value: controlledVa
     const handleClear = useCallback((e) => {
         e.preventDefault();
         e.stopPropagation();
+        // 非受控时更新内部状态
         if (!isControlledRef.current) {
             setInternalValue('');
         }

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

@@ -9,6 +9,7 @@ export type InputNumberProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'defa
     };
     addonAfter?: ReactNode;
     allowStep?: boolean;
+    /** 原生 input 节点的自定义 className */
     inputClassName?: string;
 };
 declare const InputNumber: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "type" | "defaultValue" | "onChange" | "step"> & InputNumberConstraints & {
@@ -20,6 +21,7 @@ declare const InputNumber: import("react").ForwardRefExoticComponent<Omit<InputH
     };
     addonAfter?: ReactNode;
     allowStep?: boolean;
+    /** 原生 input 节点的自定义 className */
     inputClassName?: string;
 } & import("react").RefAttributes<HTMLInputElement>>;
 export { InputNumber };

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

@@ -4,17 +4,46 @@ type VerticalLayout = {
 };
 type HorizontalLayout = {
     layout?: 'horizontal';
+    /**
+     * 标签宽度
+     * @default 'auto'
+     */
     labelWidth?: string | number;
+    /**
+     * 标签对齐方式
+     * @default 'left'
+     */
     labelAlign?: 'left' | 'right' | 'center';
 };
 export type LabelLayout = HorizontalLayout | VerticalLayout;
 export type LabelProps = {
+    /**
+     * 标签文本
+     */
     label: ReactNode;
+    /**
+     * 标签内容
+     */
     children: ReactNode;
+    /**
+     * 是否必填（显示红色星号）
+     */
     required?: boolean;
+    /**
+     * 标签的 htmlFor 属性
+     */
     htmlFor?: string;
+    /**
+     * 容器类名
+     */
     className?: string;
+    /**
+     * 标签类名
+     */
     labelClassName?: string;
+    /**
+     * 内容区域类名
+     */
     contentClassName?: string;
 } & LabelLayout;
 declare const Label: import("react").ForwardRefExoticComponent<LabelProps & import("react").RefAttributes<HTMLDivElement>>;

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

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cn } from '../../lib/utils';
 import { forwardRef, useMemo } from 'react';
+// 标签对齐样式
 const labelAlignStyles = {
     left: 'text-left',
     right: 'text-right',
@@ -9,6 +10,7 @@ const labelAlignStyles = {
 const Label = forwardRef((props, ref) => {
     const { label, children, layout = 'vertical', required = false, htmlFor, className, labelClassName, contentClassName, } = props;
     const isVertical = layout === 'vertical';
+    // 标签样式
     const labelStyles = cn('text-sm font-medium text-foreground', required && "before:content-['*'] before:pt-1 before:mr-0.5 before:text-destructive", labelClassName);
     const { usedClassName, labelWidth } = useMemo(() => {
         let usedLabelWidth;

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

@@ -19,6 +19,10 @@ export const CollapseToggle = forwardRef(({ className }, ref) => {
     const onCollapse = useMenuStore((s) => s.onCollapse);
     const propsCollapsed = useMenuStore((s) => s.propsCollapsed);
     const shouldShowCollapseToggle = () => {
+        /**
+         * 传入 collapsed 且没有 onCollapse 时，表示折叠状态完全由外部控制。
+         * 内部控制器无法改变状态，因此不渲染。
+         */
         if (typeof propsCollapsed !== "undefined" &&
             typeof onCollapse === "undefined") {
             return false;

package/fe/packages/ui/react/components/Menu/SubMenu.d.ts

@@ -1,3 +1,10 @@
 import type { SubMenuProps } from "./menuTypes";
+/**
+ * 渲染带子菜单的 Menu 项。
+ *
+ * 根据当前 menu mode、收起状态、是否在弹出层内，决定子菜单是内嵌展开还是 Popup 弹出。
+ *
+ * @returns SubMenu 完整节点，包含触发区域和子菜单内容。
+ */
 export declare function SubMenu({ eventKey, label, icon, disabled, popup: forcePopup, parentKey, children, }: SubMenuProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=SubMenu.d.ts.map

package/fe/packages/ui/react/components/Menu/SubMenu.js

@@ -7,6 +7,11 @@ import { CollapsedContext, useMenuStore } from "./MenuContext";
 import { getFirstChar } from "./utils";
 const SUBMENU_POPUP_OFFSET = 12;
 const SubMenuLevelContext = createContext(0);
+/**
+ * 计算 top 模式下，二级及更深层 submenu 的弹出位置。
+ *
+ * @returns 优先放在右侧；右侧空间不够时，改放到左侧。
+ */
 const getTopNestedSubMenuPosition = ({ anchorRect, contentRect, viewportWidth, offset, matchAnchorWidth, }) => {
     const width = contentRect?.width ?? 0;
     const rightLeft = anchorRect.right + offset;
@@ -19,11 +24,25 @@ const getTopNestedSubMenuPosition = ({ anchorRect, contentRect, viewportWidth, o
         width: matchAnchorWidth ? anchorRect.width : undefined,
     };
 };
+/**
+ * 判断当前 SubMenu 的子节点里，有没有选中的菜单项。
+ *
+ * @param children SubMenu 下面渲染出来的菜单节点。
+ * @param targetKey 当前选中的 key。
+ * @returns 子孙节点里命中选中 key 时返回 true。
+ */
 function hasDescendantSelected(children, targetKey) {
     if (!targetKey)
         return false;
     return walkReactChildren(children, targetKey);
 }
+/**
+ * 递归遍历 React children，查找指定 eventKey。
+ *
+ * @param node 当前要检查的 React 节点。
+ * @param targetKey 要查找的 eventKey。
+ * @returns 当前节点或子孙节点命中时返回 true。
+ */
 function walkReactChildren(node, targetKey) {
     if (!node)
         return false;
@@ -38,6 +57,11 @@ function walkReactChildren(node, targetKey) {
     }
     return false;
 }
+/**
+ * 渲染 SubMenu 的触发区域，也就是能点击/hover 的那一行。
+ *
+ * @returns SubMenu trigger 节点。
+ */
 function SubMenuItem({ triggerRef, onClick, icon, label, disabled, collapsed, descendantSelected, ArrowIcon, showArrow, setPopupContentRef, mode, }) {
     const collapsedLabelTooltip = useMenuStore((s) => s.collapsedLabelTooltip);
     return (_jsxs("div", { ref: triggerRef, onClick: onClick, className: cn("subMenuItem group relative flex items-center rounded-lg text-sm transition-all", "select-none", mode === "top" &&
@@ -50,6 +74,13 @@ function SubMenuItem({ triggerRef, onClick, icon, label, disabled, collapsed, de
                     ? "bg-theme/10 text-theme"
                     : "text-muted-foreground group-hover:text-foreground"), children: icon })), !collapsed && _jsx("span", { className: "min-w-0 flex-1 truncate", children: label }), collapsed && !icon && collapsedLabelTooltip && (_jsx("span", { className: "absolute left-0 right-0 top-0 flex h-full items-center justify-center text-[10px]", children: getFirstChar(label) })), !collapsed && showArrow && (_jsx(ArrowIcon, { className: "h-4 w-4 flex-shrink-0 text-muted-foreground transition-transform group-hover:text-foreground" })), _jsx("div", { ref: setPopupContentRef })] }));
 }
+/**
+ * 渲染带子菜单的 Menu 项。
+ *
+ * 根据当前 menu mode、收起状态、是否在弹出层内，决定子菜单是内嵌展开还是 Popup 弹出。
+ *
+ * @returns SubMenu 完整节点，包含触发区域和子菜单内容。
+ */
 export function SubMenu({ eventKey, label, icon, disabled, popup: forcePopup, parentKey, children, }) {
     const mode = useMenuStore((s) => s.mode);
     const expandTrigger = useMenuStore((s) => s.expandTrigger);
@@ -64,7 +95,9 @@ export function SubMenu({ eventKey, label, icon, disabled, popup: forcePopup, pa
     const popupContentRef = useRef(null);
     const [popupContainer, setPopupContainer] = useState(undefined);
     const [popupOpen, setPopupOpen] = useState(false);
+    // 处于弹出层内：store 已收起但 context 被覆盖为 false
     const isInsidePopup = storeCollapsed && !collapsed;
+    // mode=top always popup; left+collapsed always popup; inside popup -> popup; else check popup flag
     const usePopup = mode === "top" ||
         (mode === "left" && collapsed) ||
         isInsidePopup ||
@@ -119,6 +152,18 @@ export function SubMenu({ eventKey, label, icon, disabled, popup: forcePopup, pa
     const popupPlacement = mode === "top" && level === 0 ? "bottom-start" : "right-start";
     const popupStrategy = mode === "top" && level > 0 ? getTopNestedSubMenuPosition : undefined;
     const hoverBridgePlacement = mode === "top" && level > 0 ? "horizontal" : "auto";
-    const subMenuContent = (_jsx("div", { className: cn(" rounded-xl bg-muted p-2 shadow-[0_18px_44px_rgba(15,23,42,0.14),0_4px_12px_rgba(15,23,42,0.08)]"), children: _jsx(SubMenuLevelContext.Provider, { value: level + 1, children: _jsx("div", { className: "flex flex-col gap-1", children: children }) }) }));
+    const subMenuContent = (_jsx("div", { className: cn(
+        // "min-w-[180px]",
+        " rounded-xl bg-muted p-2 shadow-[0_18px_44px_rgba(15,23,42,0.14),0_4px_12px_rgba(15,23,42,0.08)]"), children: _jsx(SubMenuLevelContext.Provider, { value: level + 1, children: _jsx("div", { className: "flex flex-col gap-1", children: children }) }) }));
+    /**
+     *
+     * submenu  生成的节点是  1 menuItem
+     *                        submenu「
+     *                          1-1
+     *                          1-2
+     *                        」
+     *
+     * 所以判断鼠标是否在区域内应该是 监听 submenu 的根节点
+     */
     return (_jsxs("div", { className: "submenu", onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, children: [_jsx(SubMenuItem, { triggerRef: triggerRef, onClick: handleTriggerClick, icon: icon, label: label, disabled: disabled, collapsed: collapsed, descendantSelected: descendantSelected, ArrowIcon: ArrowIcon, showArrow: showArrow, setPopupContentRef: setPopupContentRef, mode: mode }), usePopup ? (_jsx(Popup, { open: popupOpen, anchorRef: triggerRef, placement: popupPlacement, offset: SUBMENU_POPUP_OFFSET, hoverBridge: SUBMENU_POPUP_OFFSET, onOpenChange: setPopupOpen, container: popupContainer, strategy: popupStrategy, hoverBridgePlacement: hoverBridgePlacement, className: "border-0 bg-transparent p-0 shadow-none", children: _jsx(CollapsedContext.Provider, { value: false, children: subMenuContent }) })) : (isOpen && (_jsx("div", { className: "ml-4 pl-2 pt-1", children: _jsx(SubMenuLevelContext.Provider, { value: level + 1, children: _jsx("div", { className: "flex flex-col gap-1", children: children }) }) })))] }));
 }

package/fe/packages/ui/react/components/Menu/menuTypes.d.ts

@@ -28,6 +28,7 @@ export interface MenuProps {
     defaultCollapsed?: boolean;
     onCollapse?: (collapsed: boolean) => void;
     collapsedWidth?: number;
+    /** 收起时无 icon 的项是否通过 tooltip 显示完整名称，默认 true */
     collapsedLabelTooltip?: boolean;
 }
 export interface SubMenuProps {

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

@@ -4,8 +4,15 @@ export type MessageProps = {
     type?: MessageType;
     content?: ReactNode;
     children?: ReactNode;
+    /**
+     * 存在时间
+     * @default 3000ms
+     */
     duration?: number;
     onClose?: () => void;
+    /**
+     * 可手动关闭
+     */
     closable?: boolean;
     className?: string;
 };

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

@@ -33,10 +33,12 @@ export function Message({ type = 'info', content, children, duration = DEFAULT_D
     const iconColor = typeConfig[type].color;
     const handleClose = () => {
         setVisible(false);
+        // 等待动画完成后再调用 onClose
         setTimeout(() => {
             onClose?.();
         }, 200);
     };
+    // 自动关闭
     useEffect(() => {
         if (duration > 0) {
             timerRef.current = setTimeout(() => {
@@ -48,6 +50,7 @@ export function Message({ type = 'info', content, children, duration = DEFAULT_D
                 clearTimeout(timerRef.current);
             }
         };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [duration]);
     if (!visible)
         return null;

package/fe/packages/ui/react/components/Message/MessageManager.js

@@ -12,17 +12,20 @@ class MessageManagerClass {
     init() {
         if (typeof document === 'undefined' || this.container)
             return;
+        // 可见消息容器
         this.container = document.createElement('div');
         this.container.id = 'message-container';
         this.container.className = 'fixed top-4 left-1/2 z-[10000] flex flex-col items-center gap-2 pointer-events-none';
         this.container.style.transform = 'translateX(-50%)';
         document.body.appendChild(this.container);
+        // 屏幕外消息容器 保留回调触发
         this.offScreenContainer = document.createElement('div');
         this.offScreenContainer.id = 'message-offscreen-container';
         this.offScreenContainer.className =
             'fixed -left-[9999px] top-0 z-[10000] flex flex-col items-center gap-2 pointer-events-none';
         this.offScreenContainer.setAttribute('aria-hidden', 'true');
         document.body.appendChild(this.offScreenContainer);
+        // 创建 React 根节点
         this.root = createRoot(this.container);
         this.offScreenRoot = createRoot(this.offScreenContainer);
         this.render();
@@ -32,13 +35,17 @@ class MessageManagerClass {
             return;
         const messages = Array.from(this.messages.values());
         const totalCount = messages.length;
+        // 可见消息：最后 maxCount 条
         const displayMessages = totalCount > this.maxCount ? messages.slice(-this.maxCount) : messages;
+        // 屏幕外消息：除了最后 maxCount 条之外的所有消息
         const offScreenMessages = totalCount > this.maxCount ? messages.slice(0, -this.maxCount) : [];
         const now = Date.now();
+        // 渲染可见消息
         this.root.render(_jsx(_Fragment, { children: displayMessages.map((message) => (_jsx(Message, { ...message, duration: message.expirationTime - now, content: message.content, onClose: () => {
                     message.onClose?.();
                     this.close(message.id);
                 } }, message.id))) }));
+        // 渲染屏幕外消息
         this.offScreenRoot.render(_jsx(_Fragment, { children: offScreenMessages.map((message) => (_jsx(Message, { ...message, duration: message.expirationTime - now, content: message.content, onClose: () => {
                     message.onClose?.();
                     this.close(message.id);
@@ -70,6 +77,7 @@ class MessageManagerClass {
         this.maxCount = count;
     }
 }
+// 单例模式
 export const messageManager = new MessageManagerClass();
 export const message = {
     success: (content, config) => messageManager.show({ content, ...config }, 'success'),

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

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

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

@@ -6,6 +6,7 @@ import { Button } from '../Button';
 import { Overlay } from '../Overlay';
 export function Modal({ open = false, onClose, title, children, footer, className, contentClassName, mask = true, maskClosable = true, lockScroll = true, closable = true, width = 520, centered = true, renderNode, keyboard = true, zIndex = 1000, }) {
     const t = useI18n();
+    // 点击内容区域阻止冒泡
     const handleContentClick = (e) => {
         e.stopPropagation();
     };

package/fe/packages/ui/react/components/Modal/ModalManager.d.ts

@@ -22,22 +22,34 @@ declare class ModalManagerClass {
 }
 type OpenModalConfig = Omit<ModalConfig, 'id'>;
 export declare const openConfirmModal: (pConfig: Pick<OpenModalConfig, "content"> & {
+    /** 标题 */
     title?: ReactNode;
+    /** 内容 */
     content: ReactNode;
+    /** 确认按钮文本 */
     okText?: string;
+    /** 取消按钮文本 */
     cancelText?: string;
+    /** 确认回调 */
     onOk?: SumbitButtonProps["onClick"];
+    /** 取消回调 */
     onCancel?: () => void;
 }) => string;
 export declare const modalManager: ModalManagerClass;
 export declare const modal: {
     open: (config: OpenModalConfig) => string;
     confirm: (pConfig: Pick<OpenModalConfig, "content"> & {
+        /** 标题 */
         title?: ReactNode;
+        /** 内容 */
         content: ReactNode;
+        /** 确认按钮文本 */
         okText?: string;
+        /** 取消按钮文本 */
         cancelText?: string;
+        /** 确认回调 */
         onOk?: SumbitButtonProps["onClick"];
+        /** 取消回调 */
         onCancel?: () => void;
     }) => string;
     close: (id: string) => void;

package/fe/packages/ui/react/components/Modal/ModalManager.js

@@ -14,6 +14,7 @@ class ModalManagerClass {
         this.container = document.createElement('div');
         this.container.id = 'modal-container';
         document.body.appendChild(this.container);
+        // 创建 React 根节点
         this.root = createRoot(this.container);
         this.render();
     }
@@ -28,7 +29,7 @@ class ModalManagerClass {
         };
     }
     open(config) {
-        this.init();
+        this.init(); // 确保已初始化
         const id = `modal-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
         const modalConfig = {
             ...config,
@@ -78,7 +79,9 @@ export const openConfirmModal = (pConfig) => {
     const currentModalId = modalManager.open(config);
     return currentModalId;
 };
+// 单例模式
 export const modalManager = new ModalManagerClass();
+// 函数式 API
 export const modal = {
     open: (config) => modalManager.open(config),
     confirm: openConfirmModal,

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

@@ -14,6 +14,9 @@ export type OverlayProps = {
     closable?: boolean;
     onClose?: () => void;
     onClick?: (e: MouseEvent<HTMLDivElement>) => void;
+    /**
+     * @default document.body
+     */
     renderNode?: HTMLElement | (() => HTMLElement);
 };
 export declare function Overlay({ open, visible, children, className, style, zIndex, mask, maskClosable, lockScroll, keyboard, closable, onClose, onClick, renderNode, }: OverlayProps): import("react").ReactPortal | null;