fat-design 0.0.3 → 0.0.4

package/types/0buildTypes/table-pro/index.d.ts

@@ -1,25 +1,150 @@
 import React from "react";
 import { TableProProps, ICellRenderFunc, IUseTableProFunc, IGetTableColumnsBySettingFunc, OperationsProps, TableToolbarProps, IRenderTableToolbar, IRenderOperationCell, IRenderMultiFieldCell } from "./types";
 declare class TablePro extends React.Component<TableProProps, any> {
+    /**
+     * 表格操作按钮组件
+     * 用于渲染表格工具栏中的操作按钮组，支持普通按钮、下拉菜单按钮、带图标按钮等
+     * @example <TablePro.TableOperations buttons={[{text: '新增', onClick: handleAdd}]} />
+     */
     static TableOperations: React.FC<OperationsProps>;
+    /**
+     * 表格工具栏组件
+     * 包含标题、数据总数、筛选器和操作按钮区域，用于表格顶部的综合工具栏
+     * @example <TablePro.TableToolbar title="用户列表" totalCount={100} operationProps={...} />
+     */
     static TableToolbar: React.FC<TableToolbarProps>;
+    /**
+     * 表格状态管理 Hook
+     * 用于管理表格的查询、分页、筛选、行选择等状态，返回 formProps、tableProps、paginationProps 等配置对象
+     * @param params 配置参数，包括 onQuery 查询函数、autoFirstQuery 是否自动首次查询等
+     * @returns {formProps, tableProps, paginationProps, filterProps, operationProps, actions}
+     * @example const { tableProps, actions } = TablePro.useTablePro({ onQuery: fetchData });
+     */
     static useTablePro: IUseTableProFunc;
+    /**
+     * 根据用户设置的列配置获取表格列
+     * 从本地存储读取用户对列的显示/隐藏、排序、锁定等设置，返回处理后的列配置
+     * @param tableProProps TablePro 组件的 props
+     * @returns 处理后的列配置数组
+     * @example const columns = await TablePro.getTableColumnsBySetting(props);
+     */
     static getTableColumnsBySetting: IGetTableColumnsBySettingFunc;
+    /**
+     * 渲染表格工具栏
+     * 函数式渲染表格工具栏组件，等同于 <TablePro.TableToolbar />
+     * @param props 工具栏配置属性
+     * @returns React 元素
+     */
     static renderTableToolbar: IRenderTableToolbar;
+    /**
+     * 渲染操作列单元格
+     * 用于表格操作列，支持权限过滤、超出数量自动收起到"更多"下拉菜单
+     * @param operationItems 操作按钮配置数组
+     * @param others 其他配置，如 max 最大显示数量、operationPerms 权限列表
+     * @returns React 元素
+     * @example TablePro.renderOperationCell([{title: '编辑', onClick: handleEdit}, {title: '删除', onClick: handleDelete}])
+     */
     static renderOperationCell: IRenderOperationCell;
+    /**
+     * 渲染多字段单元格
+     * 在一个单元格中显示多个字段内容，支持标题和内容的组合显示
+     * @param itemList 字段项数组，每项可包含 title、content、display 属性
+     * @returns React 元素
+     * @example TablePro.renderMultiFieldCell([{title: '姓名', content: '张三'}, {title: '年龄', content: 25}])
+     */
     static renderMultiFieldCell: IRenderMultiFieldCell;
+    /**
+     * 渲染 JSON 格式数据
+     * 将对象或 JSON 字符串格式化为缩进的 JSON 显示，用于展示复杂数据结构
+     * @param value 要渲染的值，支持对象或 JSON 字符串
+     * @returns 格式化的 <pre> 元素
+     */
     static renderJSON: ICellRenderFunc;
+    /**
+     * 渲染字符串
+     * 将各种类型的值转换为字符串显示，支持数字、字符串、数组、对象等类型
+     * @param value 要渲染的值
+     * @returns 字符串或占位符
+     */
     static renderString: ICellRenderFunc;
+    /**
+     * 渲染日期（YYYY-MM-DD）
+     * 将时间戳或日期字符串格式化为日期显示，支持单个值、数组、JSON 字符串
+     * @param value 时间戳、日期字符串或日期数组
+     * @returns 格式化的日期字符串
+     */
     static renderDay: ICellRenderFunc;
+    /**
+     * 渲染日期（YYYY-MM-DD），自动识别秒级时间戳
+     * 与 renderDay 类似，但会自动判断时间戳是秒级还是毫秒级
+     * @param value 时间戳、日期字符串或日期数组
+     * @returns 格式化的日期字符串
+     */
     static renderDayAuto: ICellRenderFunc;
+    /**
+     * 渲染日期时间（YYYY-MM-DD HH:mm:ss）
+     * 将时间戳或日期字符串格式化为完整日期时间显示
+     * @param value 时间戳、日期字符串或日期数组
+     * @returns 格式化的日期时间字符串
+     */
     static renderTime: ICellRenderFunc;
+    /**
+     * 渲染日期时间（YYYY-MM-DD HH:mm:ss），自动识别秒级时间戳
+     * 与 renderTime 类似，但会自动判断时间戳是秒级还是毫秒级
+     * @param value 时间戳、日期字符串或日期数组
+     * @returns 格式化的日期时间字符串
+     */
     static renderTimeAuto: ICellRenderFunc;
+    /**
+     * 渲染千分位数字
+     * 将数字格式化为带千分位分隔符的字符串，默认保留2位小数
+     * @param value 数字或数字字符串
+     * @returns 格式化的千分位字符串，如 "1,234.00"
+     */
     static renderThousands: ICellRenderFunc;
+    /**
+     * 渲染 HTML 内容
+     * 将字符串作为 HTML 直接渲染，用于显示富文本内容
+     * @param value HTML 字符串
+     * @returns 包含 HTML 内容的元素
+     * @warning 注意 XSS 安全风险，确保内容来源可信
+     */
     static renderHTML: ICellRenderFunc;
+    /**
+     * 渲染布尔值
+     * 将布尔值或相关值转换为"是/否"显示
+     * @param value 布尔值、Y/N、YES/NO、1/0 等
+     * @returns "是" 或 "否"
+     */
     static renderBoolean: ICellRenderFunc;
+    /**
+     * 渲染相对时间
+     * 将日期时间转换为相对时间描述，如"3天前"、"2小时前"
+     * @param value 时间戳或日期字符串
+     * @returns 相对时间字符串
+     */
     static renderRelativeTime: ICellRenderFunc;
+    /**
+     * 渲染文件下载链接
+     * 将文件 URL 渲染为可点击的下载链接
+     * @param value 文件 URL 或文件信息对象
+     * @returns 下载链接元素
+     */
     static renderFileDownload: ICellRenderFunc;
+    /**
+     * 渲染文件图片预览
+     * 将图片 URL 渲染为可预览的缩略图
+     * @param value 图片 URL 或图片信息对象
+     * @returns 图片预览元素
+     */
     static renderFileImage: ICellRenderFunc;
+    /**
+     * 渲染枚举标签
+     * 将枚举值渲染为带颜色的标签（Tag），用于状态、类型等枚举字段展示
+     * @param value 枚举对象（包含 label 和 style）或枚举数组
+     * @returns Tag 组件或标签数组
+     * @example TablePro.renderEnumTag({label: '启用', style: 'green'})
+     */
     static renderEnumTag: ICellRenderFunc;
     render(): React.JSX.Element;
 }

package/types/0buildTypes/table-pro/types.d.ts

@@ -43,6 +43,7 @@ export interface OperationBtnItem {
     tooltip?: any;
     onClick?: any | string;
     children?: OperationBtnItem[];
+    disabled?: boolean;
 }
 export interface OperationsProps {
     prefix: string;

package/types/0buildTypes/table-pro/widget/column-setting.d.ts

@@ -1,5 +1,108 @@
+/**
+ * 列设置模块
+ *
+ * 提供表格列的自定义配置功能，包括：
+ * - 列的显示/隐藏
+ * - 列的排序（拖拽调整顺序）
+ * - 列的锁定（左锁列/右锁列）
+ *
+ * ## 如何开启列设置功能
+ *
+ * ### 方式一：使用 useTablePro Hook（推荐）
+ * ```tsx
+ * function MyTable() {
+ *   const { tableProps, actions } = TablePro.useTablePro({
+ *     onQuery: fetchData,
+ *   });
+ *
+ *   // 在工具栏添加"列设置"按钮
+ *   const operationProps = {
+ *     buttons: [
+ *       {
+ *         text: '列设置',
+ *         icon: 'set',
+ *         onClick: () => showColumnSettingDialog({ actions }),
+ *       },
+ *     ],
+ *   };
+ *
+ *   return (
+ *     <TablePro
+ *       settingName="my-table-column-setting-unique-id"  // 必填，长度需 > 10，用于本地存储标识
+ *       tableProps={tableProps}
+ *       operationProps={operationProps}
+ *       // ... 其他 props
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * ### 方式二：手动应用列设置
+ * ```tsx
+ * async function MyTable() {
+ *   const columns = await TablePro.getTableColumnsBySetting({
+ *     settingName: 'my-table-column-setting-unique-id',
+ *     tableProps: { columns: originalColumns },
+ *     actions: tableActions,
+ *   });
+ *
+ *   // 使用处理后的 columns 渲染表格
+ * }
+ * ```
+ *
+ * ## 注意事项
+ * - settingName 必须是长度 > 10 的唯一字符串，用于区分不同表格的列设置
+ * - 用户设置会保存在浏览器本地存储（localForage）中
+ * - 可通过 column.display = false 设置某列默认不显示
+ *
+ * @module column-setting
+ */
 import { TableProProps } from "../types";
+/**
+ * 验证 settingName 是否有效
+ * settingName 必须是长度 > 10 的字符串，用于确保本地存储的唯一性
+ * @param settingName 设置名称
+ * @returns 是否有效
+ */
 declare function isSettingNameValid(settingName: any): boolean;
+/**
+ * 显示列设置对话框
+ * 打开一个右侧抽屉，让用户可以配置列的显示、隐藏、排序和锁定
+ *
+ * @param params 参数对象
+ * @param params.actions useTablePro 返回的 actions 对象，包含 getSettingName、getTableProps、updateColumns 等方法
+ *
+ * @example
+ * // 在操作按钮中调用
+ * const operationProps = {
+ *   buttons: [
+ *     {
+ *       text: '列设置',
+ *       icon: 'set',
+ *       onClick: () => showColumnSettingDialog({ actions }),
+ *     },
+ *   ],
+ * };
+ */
 declare function showColumnSettingDialog({ actions }: any): Promise<void>;
+/**
+ * 根据用户设置获取表格列配置
+ * 从本地存储读取用户的列设置，过滤隐藏列，应用锁定配置
+ *
+ * 此函数通常在表格初始化时调用，用于应用用户之前保存的列设置
+ *
+ * @param tableProProps TablePro 组件的 props
+ * @param tableProProps.actions useTablePro 返回的 actions 对象
+ * @param tableProProps.tableProps 包含 columns 的表格属性
+ * @returns 处理后的列配置数组（已过滤隐藏列，已应用锁定设置）
+ *
+ * @example
+ * // 在组件中使用
+ * const columns = await TablePro.getTableColumnsBySetting({
+ *   settingName: 'my-table-columns',
+ *   tableProps: { columns: originalColumns },
+ *   actions: tableActions,
+ * });
+ */
 declare function getTableColumnsBySetting(tableProProps: TableProProps): Promise<any[]>;
 export { isSettingNameValid, showColumnSettingDialog, getTableColumnsBySetting };

package/types/button/index.d.ts

@@ -73,6 +73,11 @@ export interface ButtonProps extends HTMLAttributesWeak, CommonProps {
      */
     disabled?: boolean;
 
+    /**
+     * 禁用（disabled为true）时点击可触发气泡提示，用于解释按钮为何禁用
+     */
+    tooltip?: React.ReactNode;
+
     /**
      * 点击按钮的回调
      */