diff --git a/UI_LIBRARY_DOCS.md b/UI_LIBRARY_DOCS.md new file mode 100644 index 0000000..09136d9 --- /dev/null +++ b/UI_LIBRARY_DOCS.md @@ -0,0 +1,1551 @@ +# zy-react-library 组件库文档 + +## 快速开始 + +### 安装 + +```bash +yarn add zy-react-library +``` + +### 使用方式 + +组件、Hooks、枚举、工具函数均按目录引入： + +```tsx +import Table from "zy-react-library/components/Table"; +import Search from "zy-react-library/components/Search"; +import useTable from "zy-react-library/hooks/useTable"; +import { FORM_ITEM_RENDER_ENUM } from "zy-react-library/enum/formItemRender"; +``` + +## 说明 + +- 本文档根据当前包内 `.d.ts` 类型声明整理。 +- 继承自 `antd`、`@ant-design/pro-components`、`ahooks` 的原生属性不逐项展开，文档会说明继承关系；库自身新增的参数逐项列出。 +- `css`、`json`、除 `formItemRender` 外的枚举仅做简要说明。 +- 参数表中的 `-` 表示源码未设置显式默认值；`undefined` 表示源码显式传入或保留为 `undefined`。 + +## 基础样式 + +### common.less + +```tsx +import "zy-react-library/css/common.less"; +``` + +`common.less` 提供组件库通用样式，适合在应用入口统一引入。 + +## 静态 JSON + +| 文件 | 引入路径 | 简要说明 | +| --- | --- | --- | +| `area.json` | `zy-react-library/json/area.json` | 行政区域树形数据，供地区级联、地区树选择使用。 | +| `industry.json` | `zy-react-library/json/industry.json` | 行业分类树形数据，供行业级联、行业树选择使用。 | +| `nation.json` | `zy-react-library/json/nation.json` | 民族数据列表。 | + +## 枚举 + +### FORM_ITEM_RENDER_ENUM + +引入： + +```tsx +import { FORM_ITEM_RENDER_ENUM } from "zy-react-library/enum/formItemRender"; +``` + +用于 `FormBuilder`、`Search` 的 `options[].render`，决定表单项渲染成什么控件。 + +| 枚举键 | 值 | 映射控件 | `componentProps` 类型 | +| --- | --- | --- | --- | +| `INPUT` | `"input"` | `antd Input` | `InputProps` | +| `TEXTAREA` | `"textarea"` | `antd Input.TextArea` | `TextAreaProps` | +| `INPUT_NUMBER` | `"inputNumber"` | `antd InputNumber` | `InputNumberProps` | +| `NUMBER` | `"number"` | `antd InputNumber` | `InputNumberProps` | +| `INTEGER` | `"integer"` | `antd InputNumber` | `InputNumberProps` | +| `SELECT` | `"select"` | `antd Select` | `SelectProps` | +| `RADIO` | `"radio"` | `antd Radio.Group` | `RadioProps` | +| `CHECKBOX` | `"checkbox"` | `antd Checkbox.Group` | `CheckboxProps` | +| `DATE` | `"date"` | `antd DatePicker` | `DatePickerProps` | +| `DATE_MONTH` | `"dateMonth"` | `antd DatePicker.MonthPicker` | `MonthPickerProps` | +| `DATE_YEAR` | `"dateYear"` | `antd DatePicker` 年选择 | `DatePickerProps` | +| `DATE_WEEK` | `"dateWeek"` | `antd DatePicker.WeekPicker` | `WeekPickerProps` | +| `DATE_RANGE` | `"dateRange"` | `antd DatePicker.RangePicker` | `RangePickerProps` | +| `DATETIME` | `"datetime"` | `antd DatePicker` 日期时间 | `DatePickerProps` | +| `DATETIME_RANGE` | `"datetimeRange"` | `antd DatePicker.RangePicker` 日期时间范围 | `RangePickerProps` | +| `DIVIDER` | `"divider"` | `antd Divider` | `DividerProps` | +| `FORM_LIST` | `"formList"` | `antd Form.List` | `FormListProps` | + +### 其他枚举 + +| 枚举 | 引入路径 | 简要说明 | +| --- | --- | --- | +| `DICTIONARY_APP_KEY_ENUM` | `zy-react-library/enum/dictionary` | 字典接口使用的 `appKey` 常量，包含 `DEFAULT`、`GWJ`。 | +| `HIDDEN_SOURCE_ENUM` | `zy-react-library/enum/hidden/gwj` | 隐患来源选项列表。 | +| `HIDDEN_STATE_ENUM` | `zy-react-library/enum/hidden/gwj` | 隐患状态选项列表。 | +| `HIDDEN_RECTIFICATION_TYPE_ENUM` | `zy-react-library/enum/hidden/gwj` | 隐患整改类型选项列表。 | +| `UPLOAD_FILE_TYPE_ENUM` | `zy-react-library/enum/uploadFile/gwj` | 文件上传类型编码枚举。 | +| `UPLOAD_FILE_PATH_ENUM` | `zy-react-library/enum/uploadFile/gwj` | 文件上传类型编码到服务端路径标识的映射。 | + +## 表单配置类型 + +`FormBuilder` 和 `Search` 共用 `FormOption` 配置。 + +### FormOption 通用参数 + +| 参数 | 类型 | 必填 | 默认值 | 适用范围 | 说明 | +| --- | --- | --- | --- | --- | --- | +| `key` | `string` | 否 | `name` 拼接值或数组索引 | 全部 | React 列表渲染用 key。没有稳定 `name` 时可传。 | +| `name` | `NamePath` | 否 | - | 除纯展示分割线外按需使用 | 表单字段名，支持字符串、数组等 antd `NamePath`。 | +| `label` | `ReactNode` | 否 | - | 全部 | 表单项标签。 | +| `span` | `number` | 否 | 外层 `span`；`divider` 固定为 `24` | 除 `onlyForLabel` 外 | 栅格占位。 | +| `required` | `boolean \| ((formValues) => boolean)` | 否 | `true` | 非 `onlyForLabel`、非自定义渲染 | 是否必填，支持按当前表单值动态计算；`useAutoGenerateRequired=false` 时不自动生成必填规则。 | +| `rules` | `Rule \| Rule[]` | 否 | - | 非 `onlyForLabel`、非自定义渲染 | antd `Form.Item` 校验规则。 | +| `useConstraints` | `boolean` | 否 | `true` | `input`、`textarea`、`inputNumber`、`number`、`integer` | 是否启用内置长度/数字格式校验限制。 | +| `placeholder` | `ReactNode` | 否 | 根据 `render` 和 `label` 自动生成 | 内置控件 render | 占位文案；输入类默认为“请输入 + label”，选择类默认为“请选择 + label”。 | +| `tip` | `ReactNode` | 否 | - | 非 `onlyForLabel` | 标签旁的提示内容。 | +| `hidden` | `boolean \| ((formValues) => boolean)` | 否 | `false` | 非 `onlyForLabel` | 是否隐藏，支持动态计算。 | +| `customizeRender` | `boolean` | 否 | `false` | 自定义 ReactNode render | 是否完全自定义渲染；为 `true` 时不再包内置 `Form.Item` 控件逻辑。 | +| `formItemProps` | `FormItemProps \| ((formValues) => FormItemProps)` | 否 | `{}` | 非 `onlyForLabel`、非自定义渲染 | 透传给 `Form.Item` 的属性，支持动态计算。日期类会自动合并日期格式化相关配置。 | +| `labelCol` | `ColProps` | 否 | 当前项 `span=24` 时为外层 `labelCol.span / 2`，否则继承外层 `labelCol` | 非 `onlyForLabel`、非自定义渲染 | 当前项标签栅格配置。 | +| `wrapperCol` | `ColProps` | 否 | `{ span: 24 - labelCol.span }` | 非 `onlyForLabel`、非自定义渲染 | 当前项控件栅格配置。 | +| `shouldUpdate` | `boolean \| ((prevValues, nextValues, info) => boolean)` | 否 | - | 非 `onlyForLabel`、非自定义渲染 | 表单联动更新条件。 | +| `dependencies` | `NamePath[]` | 否 | - | 非 `onlyForLabel`、非自定义渲染 | 表单联动依赖字段。 | +| `onlyForLabel` | `boolean` | 否 | `false` | 全部 | 仅在表单中保留隐藏字段，不渲染可见控件。 | +| `colStyle` | `CSSProperties \| ((formValues) => CSSProperties)` | 否 | - | 可见项 | 外层 `Col` 样式，支持动态计算。 | +| `colTitle` | `ReactNode \| ((formValues) => ReactNode)` | 否 | - | 可见项 | `Col` 内、`Form.Item` 前渲染的标题节点。 | + +### 按 render 扩展参数 + +| 参数 | 类型 | 必填 | 默认值 | 只在这些 render 可用 | 不可用说明 | +| --- | --- | --- | --- | --- | --- | +| `render` | `keyof FORM_ITEM_RENDER_TYPE_MAP \| ReactNode` | 否 | `"input"` | 全部 | 传 ReactNode 时属于自定义渲染，不使用内置控件参数。 | +| `componentProps` | `FORM_ITEM_RENDER_TYPE_MAP[render] \| ((formValues) => FORM_ITEM_RENDER_TYPE_MAP[render])` | 否 | `{}` | 内置控件 render、`divider`、`formList` | `customizeRender=true` 或 `render` 为 ReactNode 自定义渲染时不可用。 | +| `items` | `OptionItem[]` | 否 | `[]` | `select`、`radio`、`checkbox` | 其他 render 不可用。 | +| `itemsField` | `ItemsFieldConfig` | 否 | `{ valueKey: "bianma", labelKey: "name" }` | `select`、`radio`、`checkbox` | 其他 render 不可用。 | +| `checkboxCol` | `number` | 否 | - | `checkbox` | 其他 render 不可用；不传时 checkbox 不使用栅格布局。 | +| `formListUniqueProps` | `FormListUniqueProps \| ((formValues) => FormListUniqueProps)` | 否 | 见 `FormListUniqueProps` 默认值 | `formList` | 其他 render 不可用。 | +| `rowStyle` | `CSSProperties \| ((field, fieldIndex) => CSSProperties)` | 否 | - | `formList` | 其他 render 不可用。 | +| `rowTitle` | `ReactNode \| ((field, fieldIndex) => ReactNode)` | 否 | - | `formList` | 其他 render 不可用。 | + +### render 可用性矩阵 + +| render | 可用参数 | 不可用参数 | 内置默认值 | +| --- | --- | --- | --- | +| `input` | 通用参数、`componentProps` | `items`、`itemsField`、`checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle` | `maxLength: 50`，关闭约束时 `maxLength: 9999` | +| `textarea` | 通用参数、`componentProps` | `items`、`itemsField`、`checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle` | `maxLength: 500`、`showCount: true`、`rows: 3`；关闭约束时 `maxLength: 9999` | +| `inputNumber` / `number` | 通用参数、`componentProps` | `items`、`itemsField`、`checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle` | `style: { width: "100%" }`，默认校验最多两位小数且绝对值不超过 `999999999` | +| `integer` | 通用参数、`componentProps` | `items`、`itemsField`、`checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle` | `style: { width: "100%" }`，默认校验整数且绝对值不超过 `999999999` | +| `select` | 通用参数、`componentProps`、`items`、`itemsField` | `checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle` | `allowClear: true`、`showSearch: { optionFilterProp: "children" }` | +| `radio` | 通用参数、`componentProps`、`items`、`itemsField` | `checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle` | 选项来自 `items` | +| `checkbox` | 通用参数、`componentProps`、`items`、`itemsField`、`checkboxCol` | `formListUniqueProps`、`rowStyle`、`rowTitle` | 传 `checkboxCol` 时每个选项包一层 `Col` | +| `date` | 通用参数、`componentProps` | `items`、`itemsField`、`checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle` | `format: "YYYY-MM-DD"`、`style: { width: "100%" }` | +| `dateMonth` | 通用参数、`componentProps` | 同 `date` | `picker: "month"`、`format: "YYYY-MM"`、`style: { width: "100%" }` | +| `dateYear` | 通用参数、`componentProps` | 同 `date` | `picker: "year"`、`format: "YYYY"`、`style: { width: "100%" }` | +| `dateWeek` | 通用参数、`componentProps` | 同 `date` | `picker: "week"`、`format: "YYYY-wo"`、`style: { width: "100%" }` | +| `dateRange` | 通用参数、`componentProps` | 同 `date` | `format: "YYYY-MM-DD"`、`style: { width: "100%" }`，默认开始/结束占位文案 | +| `datetime` | 通用参数、`componentProps` | 同 `date` | `showTime: true`、`format: "YYYY-MM-DD HH:mm:ss"`、`style: { width: "100%" }` | +| `datetimeRange` | 通用参数、`componentProps` | 同 `date` | `showTime: true`、`format: "YYYY-MM-DD HH:mm:ss"`、`style: { width: "100%" }`，默认开始/结束占位文案 | +| `divider` | `label`、`span`、`componentProps`、`colStyle` | `name`、`required`、`rules`、`placeholder`、`items`、`itemsField`、`checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle` | `span: 24`，渲染 `Divider`，`orientation: "left"` | +| `formList` | 通用布局参数、`componentProps`、`formListUniqueProps`、`rowStyle`、`rowTitle` | 当前层的 `items`、`itemsField`、`checkboxCol` | 子项通过 `formListUniqueProps.options(field, fieldIndex, operations)` 返回 | +| ReactNode 自定义渲染 | `render`、`customizeRender`、`span`、`colStyle` | `componentProps`、`items`、`itemsField`、`checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle`、内置校验相关参数 | `customizeRender=true` 时直接渲染传入节点 | +| `onlyForLabel=true` | `name`、`onlyForLabel` | `span`、`required`、`rules`、`componentProps`、`items`、`itemsField`、`checkboxCol`、`formListUniqueProps`、`rowStyle`、`rowTitle` | 渲染隐藏 `input`，不显示到页面 | + +### OptionItem + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `bianma` | `any` | 否 | 默认选项值字段。 | +| `name` | `string \| ReactNode` | 否 | 默认选项标签字段。 | +| `disabled` | `boolean` | 否 | 是否禁用当前选项。 | +| `[key: string]` | `any` | 否 | 允许携带业务自定义字段。 | + +### ItemsFieldConfig + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `valueKey` | `string` | 否 | 选项值字段名，默认使用 `bianma`。 | +| `labelKey` | `string \| ((item) => ReactNode)` | 否 | 选项标签字段名或自定义标签渲染函数，默认使用 `name`。 | + +### FormListUniqueProps + +| 参数 | 类型 | 必填 | 默认值 | 说明 | +| --- | --- | --- | --- | --- | +| `showAddButton` | `boolean` | 否 | `true` | 是否显示新增按钮。 | +| `showRemoveButton` | `boolean` | 否 | `true` | 是否显示删除按钮。 | +| `addButtonText` | `string` | 否 | `"添加"` | 新增按钮文案。 | +| `removeButtonText` | `string` | 否 | `"删除"` | 删除按钮文案。 | +| `options` | `(field, fieldIndex, operations) => FormListOption[]` | 是 | `[]` | 当前行的表单项配置函数。 | +| `addDefaultValue` | `DeepPartial` | 否 | `{}` | 点击新增时插入的默认值。 | +| `addInsertIndex` | `number` | 否 | `undefined` | 点击新增时插入的位置。 | + +### FormListOperations + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `field` | `FormListFieldData` | 当前行字段信息。 | +| `fieldIndex` | `number` | 当前行索引。 | +| `add` | `(defaultValue?, insertIndex?) => void` | 新增一行。 | +| `remove` | `(index: number \| number[]) => void` | 删除一行或多行。 | +| `move` | `(from: number, to: number) => void` | 移动行位置。 | + +## 组件 + +### 默认值速查 + +以下默认值来自当前组件实现；没有列出的参数一般没有源码层面的显式默认值，或直接透传给底层 antd 组件。 + +| 组件 | 默认值 | +| --- | --- | +| `Table` | `columns=[]`、`showIndexColumn=true`、`ellipsis=true`、`align="center"`、`indexColumnFixed="left"`、`rowKey="id"`、`disabledResizer=false`、`height` 不传时自动计算。 | +| `Search` | `labelCol={ span: 6 }`、`options=[]`、`values={}`、`searchText="搜索"`、`resetText="重置"`、`showSearchButton=true`、`showResetButton=true`、表单项默认 `span=6`、默认折叠。 | +| `FormBuilder` | `gutter=24`、`span=12`、`labelCol={ span: 4 }`、`wrapperCol={ span: 20 }`、`scrollToFirstError=true`、`useAutoGenerateRequired=true`、`showActionButtons=true`、`submitButtonText="提交"`、`cancelButtonText="取消"`、`showSubmitButton=true`、`showCancelButton=true`、`loading=false`。 | +| `FormItemsRenderer` | `gutter=24`、`span=12`、`collapse=false`、`useAutoGenerateRequired=true`。 | +| `Page` | `isShowHeader=true`、`headerPrevious=true`、`isShowFooter=true`、`isShowAllAction=true`、`loading=false`、`backButtonText="关闭"`、`contentPadding="20px"`。 | +| `HeaderBack` | `previous=true`。 | +| `Upload` | `value=[]`、`ratio=""`、`showTip=true`、`multiple=true`；未传 `fileType` 时根据 `accept` 推断，默认按图片；图片默认 `accept=".jpg,.jpeg,.png"`、`maxCount=4`、`size=10`；视频默认 `accept=".mp4"`、`maxCount=1`、`size=100`；文档默认 `accept=".pdf,.doc,.docx"`、`maxCount=4`、`size=10`。 | +| `ImportFile` | `title="导入"`、`labelCol={ span: 4 }`、`exportTemplateButtonText="导出模板"`；弹窗宽度 `600`，内置附件上传 `accept=".xls,.xlsx"`、`listType="text"`、`maxCount=1`。 | +| `Pdf` | `visible=false`、`inline=false`、`title="PDF预览"`、`style={}`。 | +| `TooltipPreviewImg` | `files=[]`、`fileUrlKey="filePath"`。 | +| `BasicSelect` | `placeholder=""`、`data=[]`、`nameKey="name"`、`idKey="id"`，内置 `showSearch=true`、`allowClear=true`、`optionFilterProp="children"`。 | +| `DictionarySelect` | `appKey=DICTIONARY_APP_KEY_ENUM.DEFAULT`、`dictValue=""`、`nameKey="dictLabel"`、`idKey="dictValue"`。 | +| `PersonnelSelect` | `params={}`、`placeholder="人员"`、`isNeedCorpInfoId=false`、`isNeedDepartmentId=true`、`isNeedPostId=false`、`extraParams={}`，内部默认额外参数 `{ noMain: "", eqEmploymentFlag: 1 }`。 | +| `BasicSelectTree` | `getNodePathsIsIncludeOneself=true`、`placeholder=""`、`treeData=[]`、`nameKey="name"`、`idKey="id"`、`childrenKey="children"`、`onlyLastLevel=false`，内置 `showSearch=true`、`allowClear=true`、`style={ width: "100%" }`。 | +| `DictionarySelectTree` | `appKey=DICTIONARY_APP_KEY_ENUM.DEFAULT`、`dictValue=""`、`nameKey="dictLabel"`、`idKey="dictValue"`。 | +| `HiddenLevelSelectTree` | `isShowNeglect=true`、`isShowLarger=true`、`isShowMajor=true`，内部固定 `placeholder="隐患级别"`、`onlyLastLevel=true`、`nameKey="dictLabel"`、`idKey="dictValue"`。 | +| `BasicCascader` | `getNodePathsIsIncludeOneself=true`、`placeholder=""`、`data=[]`、`nameKey="name"`、`idKey="id"`、`childrenKey="children"`。 | +| `AreaCascader` | 内部使用 `area.json`，默认 `nameKey="label"`、`idKey="value"`。 | +| `IndustryCascader` | 内部使用 `industry.json`，默认 `nameKey="dict_label"`、`idKey="dict_value"`、`childrenKey="childrenList"`。 | +| `DictionaryCascader` | `appKey=DICTIONARY_APP_KEY_ENUM.DEFAULT`、`dictValue=""`、`nameKey="dictLabel"`、`idKey="dictValue"`。 | +| `BasicLeftTree` | `getNodePathsIsIncludeOneself=true`、`treeData=[]`、`nameKey="name"`、`idKey="id"`、`childrenKey="children"`，搜索框固定宽度容器 `300`。 | +| `Map` | `longitudeProps="longitude"`、`latitudeProps="latitude"`、`required=true`、`area=""`、`showArea=false`、`disable=false`、`type="baidu"`。 | +| `MapSelector` | `area=""`、`showArea=false`、`disable=false`、`type="baidu"`；弹窗宽度 `1000`、`maskClosable=false`、地图容器高度 `500px`。 | +| `HiddenInfo` | `id=""`、`idKey="id"`、`hiddenId=""`、`hiddenIdKey="hiddenId"`、`history=false`。 | + +### Table + +引入： + +```tsx +import Table from "zy-react-library/components/Table"; +``` + +基于 `antd Table` 和 `ProTable` 扩展。继承 `Omit` 与 `ProTableProps`。 + +| 参数 | 类型 | 必填 | 默认值 | 说明 | +| --- | --- | --- | --- | --- | +| `storeIndex` | `string` | 否 | `""` | 多表格页面的唯一缓存索引；不传时使用默认索引，可能覆盖同路由下其他表格缓存。 | +| `disabledResizer` | `boolean` | 否 | `false` | 是否禁用内容区滚动处理。 | +| `showIndexColumn` | `boolean` | 否 | `true` | 是否显示内置序号列。 | +| `indexColumnFixed` | `"left" \| "right" \| boolean` | 否 | `"left"` | 序号列固定方向。 | +| `align` | `"left" \| "right" \| "center"` | 否 | `"center"` | 表格列默认对齐方式。 | +| `ellipsis` | `boolean` | 否 | `true` | 内容超出宽度时是否省略。 | +| `height` | `number` | 否 | 自适应高度 | 表格高度；不传时根据内容区域自动计算。 | + +### Search + +引入： + +```tsx +import Search from "zy-react-library/components/Search"; +``` + +搜索表单组件，继承 `Omit`。组件上挂载 `Search.useForm`、`Search.useWatch`。 + +| 参数 | 类型 | 必填 | 默认值 | 说明 | +| --- | --- | --- | --- | --- | +| `options` | `FormOption[]` | 是 | `[]` | 搜索项配置数组。 | +| `values` | `DeepPartial` | 否 | `{}` | 表单值。 | +| `onFinish` | `(values: Values, type: "submit" \| "reset") => void` | 否 | - | 搜索和重置都会触发的回调，`type` 标识触发来源。 | +| `onSubmit` | `(values: Values) => void` | 否 | - | 点击搜索时触发。 | +| `onReset` | `(values: Values) => void` | 否 | - | 点击重置时触发。 | +| `searchText` | `string` | 否 | `"搜索"` | 搜索按钮文案。 | +| `resetText` | `string` | 否 | `"重置"` | 重置按钮文案。 | +| `showSearchButton` | `boolean` | 否 | `true` | 是否显示搜索按钮。 | +| `showResetButton` | `boolean` | 否 | `true` | 是否显示重置按钮。 | +| `extraButtons` | `ReactNode` | 否 | - | 底部额外按钮区域。 | +| `form` | `FormInstance` | 是 | - | antd 表单实例。 | + +### FormBuilder + +引入： + +```tsx +import FormBuilder from "zy-react-library/components/FormBuilder"; +``` + +表单构建组件，继承 `Omit`。组件上挂载 `FormBuilder.useForm`、`FormBuilder.useWatch`。 + +| 参数 | 类型 | 必填 | 默认值 | 说明 | +| --- | --- | --- | --- | --- | +| `values` | `DeepPartial` | 否 | - | 表单初始值，会传给 antd `Form.initialValues`。 | +| `options` | `FormOption[]` | 是 | - | 表单项配置数组。 | +| `gutter` | `Gutter \| [Gutter, Gutter]` | 否 | `24` | 栅格间距，同时影响表单宽度计算。 | +| `span` | `number` | 否 | `12` | 默认栅格占位。 | +| `labelCol` | `ColProps` | 否 | `{ span: 4 }` | 标签栅格配置，继承自 `FormProps` 后被组件设置默认值。 | +| `wrapperCol` | `ColProps` | 否 | `{ span: 20 }` | 控件栅格配置，默认按 `24 - labelCol.span` 计算。 | +| `scrollToFirstError` | `boolean` | 否 | `true` | 校验失败时滚动到第一个错误字段，组件内部默认开启。 | +| `useAutoGenerateRequired` | `boolean` | 否 | `true` | 是否根据配置自动生成必填规则。 | +| `showActionButtons` | `boolean` | 否 | `true` | 是否显示底部操作按钮区域。 | +| `submitButtonText` | `string` | 否 | `"提交"` | 提交按钮文案。 | +| `cancelButtonText` | `string` | 否 | `"取消"` | 取消按钮文案。 | +| `showSubmitButton` | `boolean` | 否 | `true` | 是否显示提交按钮。 | +| `showCancelButton` | `boolean` | 否 | `true` | 是否显示取消按钮。 | +| `customActionButtons` | `ReactNode` | 否 | - | 自定义操作按钮；传入后替换默认提交/取消按钮组。 | +| `extraActionButtons` | `ReactNode` | 否 | - | 额外操作按钮，插入在提交和取消按钮之间。 | +| `loading` | `boolean` | 否 | `false` | 加载状态，控制外层 `Spin`。 | +| `form` | `FormInstance` | 是 | - | antd 表单实例。 | +| `onFinish` | `(values: Values) => void` | 否 | - | 提交成功回调。 | +| `history` | `{ goBack?: () => void; [key: string]: any }` | 否 | `window.history.back` | 路由历史对象，用于取消/返回；没有 `history.goBack` 时使用浏览器返回。 | + +### FormItemsRenderer + +引入： + +```tsx +import FormItemsRenderer from "zy-react-library/components/FormBuilder/FormItemsRenderer"; +``` + +表单项渲染器，一般由 `FormBuilder` 内部使用。 + +| 参数 | 类型 | 必填 | 默认值 | 说明 | +| --- | --- | --- | --- | --- | +| `options` | `FormOption[]` | 是 | - | 表单项配置数组。 | +| `span` | `number` | 否 | `12` | 默认栅格占位。 | +| `collapse` | `boolean` | 否 | `false` | 是否折叠显示；为 `true` 时索引大于等于 3 的项隐藏。 | +| `useAutoGenerateRequired` | `boolean` | 否 | `true` | 是否自动生成必填规则。 | +| `initialValues` | `DeepPartial` | 否 | - | 初始值，用于表单尚未初始化时提供默认值。 | +| `gutter` | `Gutter \| [Gutter, Gutter]` | 否 | `24` | 栅格间距。 | +| `labelCol` | `ColProps` | 否 | 外层传入值 | 标签栅格配置。 | + +### Page + +引入： + +```tsx +import Page from "zy-react-library/components/Page"; +``` + +页面容器组件。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `headerTitle` | `ReactNode` | 否 | 页头标题。 | +| `history` | `{ goBack?: () => void; [key: string]: any }` | 否 | 路由历史对象，用于返回。 | +| `isShowHeader` | `boolean` | 否 | 是否显示头部。 | +| `headerPrevious` | `boolean` | 否 | 头部是否显示返回能力。 | +| `isShowFooter` | `boolean` | 否 | 是否显示底部操作区。 | +| `isShowAllAction` | `boolean` | 否 | 是否显示默认全部操作。 | +| `loading` | `boolean` | 否 | 页面加载状态。 | +| `backButtonText` | `string` | 否 | 返回按钮文案。 | +| `contentPadding` | `string` | 否 | 内容区内边距。 | +| `customActionButtons` | `ReactNode` | 否 | 自定义底部操作按钮。 | +| `extraActionButtons` | `ReactNode` | 否 | 额外底部操作按钮。 | +| `children` | `ReactNode \| (() => ReactNode)` | 是 | 页面内容。 | + +### HeaderBack + +引入： + +```tsx +import HeaderBack from "zy-react-library/components/HeaderBack"; +``` + +页头返回组件。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `title` | `ReactNode` | 是 | 标题内容。 | +| `history` | `{ goBack?: () => void; [key: string]: any }` | 否 | 路由历史对象。 | +| `previous` | `boolean` | 否 | 是否显示返回操作。 | + +### Upload + +引入： + +```tsx +import Upload from "zy-react-library/components/Upload"; +``` + +上传组件，继承 `Omit`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `value` | `UploadFile[]` | 否 | 当前文件列表。 | +| `ratio` | `` `${number}*${number}` `` | 否 | 图片宽高比例提示，例如 `"16*9"`。 | +| `showTip` | `boolean` | 否 | 是否显示上传提示。 | +| `size` | `number` | 否 | 文件大小限制。 | +| `tipContent` | `ReactNode` | 否 | 自定义提示内容。 | +| `uploadButtonText` | `string` | 否 | 上传按钮文案。 | +| `fileType` | `"image" \| "video" \| "document"` | 否 | 文件类型。 | +| `onGetRemoveFile` | `(file: Omit) => void` | 否 | 删除文件时返回被移除的文件。 | + +### ImportFile + +引入： + +```tsx +import ImportFile from "zy-react-library/components/ImportFile"; +``` + +文件导入弹窗，继承 `Omit`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `visible` | `boolean` | 是 | 是否显示弹窗。 | +| `title` | `string` | 否 | 弹窗标题。 | +| `templateUrl` | `string` | 否 | 导入模板下载地址。 | +| `children` | `ReactNode \| ((props: { form: FormInstance }) => ReactNode)` | 否 | 自定义弹窗内容；函数形式可拿到内部表单实例。 | +| `onConfirm` | `(values: { file?: UploadFile[]; [key: string]: any }) => void` | 是 | 确认导入回调。 | +| `onCancel` | `() => void` | 是 | 取消回调。 | +| `exportTemplateButtonText` | `ReactNode` | 否 | 下载模板按钮文案。 | +| `extraButtons` | `ReactNode` | 否 | 额外按钮。 | + +### PreviewImg + +引入： + +```tsx +import PreviewImg from "zy-react-library/components/PreviewImg"; +``` + +图片预览组件。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `files` | `string[] \| { filePath?: string; [key: string]: string }[]` | 是 | 图片地址数组，或包含图片地址字段的对象数组。 | +| `fileUrlKey` | `string` | 否 | 对象数组中图片地址字段名。 | + +### TooltipPreviewImg + +引入： + +```tsx +import TooltipPreviewImg from "zy-react-library/components/TooltipPreviewImg"; +``` + +悬浮提示式图片预览组件，参数同 `PreviewImg`。 + +### PreviewPdf + +引入： + +```tsx +import PreviewPdf from "zy-react-library/components/PreviewPdf"; +``` + +PDF 预览入口组件。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `files` | `{ filePath?: string; fileName?: string; name?: string; [key: string]: string }[]` | 否 | PDF 文件对象数组。 | +| `nameKey` | `string` | 否 | 文件名字段名。 | +| `urlKey` | `string` | 否 | 文件地址字段名。 | +| `name` | `string` | 否 | 单文件文件名。 | +| `url` | `string` | 否 | 单文件地址。 | + +### Pdf + +引入： + +```tsx +import Pdf from "zy-react-library/components/Pdf"; +``` + +PDF 展示组件。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `file` | `string` | 是 | PDF 文件地址。 | +| `name` | `string` | 否 | 文件名。 | +| `visible` | `boolean` | 否 | 是否以弹窗形式显示。 | +| `title` | `string` | 否 | 弹窗标题。 | +| `onCancel` | `() => void` | 否 | 关闭弹窗回调。 | +| `inline` | `boolean` | 否 | 是否内联展示。 | +| `style` | `CSSProperties` | 否 | 外层样式。 | + +### Video + +引入： + +```tsx +import Video from "zy-react-library/components/Video"; +``` + +视频播放组件，继承 `AliPlayerProps`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `title` | `string` | 否 | 弹窗标题。 | +| `visible` | `boolean` | 否 | 是否显示弹窗。 | +| `inline` | `boolean` | 否 | 是否内联展示。 | +| `onCancel` | `() => void` | 否 | 关闭回调。 | + +### AliPlayer + +引入： + +```tsx +import AliPlayer from "zy-react-library/components/Video/AliPlayer"; +``` + +阿里云播放器封装，支持 `ref`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `source` | `string \| string[]` | 否 | 视频播放地址。 | +| `vid` | `string` | 否 | 阿里云视频 ID。 | +| `playAuth` | `string` | 否 | 阿里云播放凭证。 | +| `cover` | `string` | 否 | 封面地址。 | +| `width` | `string` | 否 | 播放器宽度。 | +| `height` | `string` | 否 | 播放器高度。 | +| `autoplay` | `boolean` | 否 | 是否自动播放。 | +| `showProgress` | `boolean` | 否 | 是否显示进度条。 | +| `isLive` | `boolean` | 否 | 是否为直播。 | +| `playTime` | `number` | 否 | 初始播放时间。 | +| `onEnded` | `() => void` | 否 | 播放结束回调。 | +| `onTimeupdate` | `(currentTime: number) => void` | 否 | 播放时间更新回调。 | +| `onGetPlayerInstance` | `(player: any) => void` | 否 | 获取播放器实例。 | +| `aliPlayerProps` | `Record` | 否 | 透传给 AliPlayer 的额外属性。 | + +Ref 方法： + +| 方法 | 类型 | 说明 | +| --- | --- | --- | +| `play` | `() => void` | 播放。 | +| `pause` | `() => void` | 暂停。 | +| `getPlayerInstance` | `() => any` | 获取播放器实例。 | + +### Editor + +引入： + +```tsx +import Editor from "zy-react-library/components/Editor"; +``` + +富文本编辑器组件，支持 `ref`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `value` | `string` | 否 | HTML 内容。 | +| `onChange` | `(html: string) => void` | 否 | 内容变化回调。 | +| `disabled` | `boolean` | 否 | 是否禁用编辑。 | + +Ref 方法： + +| 方法 | 类型 | 说明 | +| --- | --- | --- | +| `getEditorInstance` | `() => IDomEditor \| null` | 获取编辑器实例。 | +| `getHtml` | `() => string \| undefined` | 获取 HTML。 | +| `setHtml` | `(value: string) => void` | 设置 HTML。 | +| `getText` | `() => string \| undefined` | 获取纯文本。 | + +### Signature + +引入： + +```tsx +import Signature from "zy-react-library/components/Signature"; +``` + +手写签名组件。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `onConfirm` | `(value: SignatureValue) => void` | 是 | 确认签名回调。 | +| `width` | `number` | 否 | 画布宽度。 | +| `height` | `number` | 否 | 画布高度。 | +| `url` | `string` | 否 | 已有签名图片地址。 | + +`SignatureValue`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `time` | `string` | 签名时间。 | +| `base64` | `string` | 签名图片 base64。 | +| `file` | `File` | 签名图片文件对象。 | + +### Map + +引入： + +```tsx +import Map from "zy-react-library/components/Map"; +``` + +地图选择组件。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `longitudeProps` | `string` | 否 | 经度字段名。 | +| `latitudeProps` | `string` | 否 | 纬度字段名。 | +| `required` | `boolean` | 否 | 是否必填。 | +| `area` | `string` | 否 | 区域文本。 | +| `showArea` | `boolean` | 否 | 是否显示区域。 | +| `disable` | `boolean` | 否 | 是否禁用选择。 | +| `onConfirm` | `(longitude, latitude, extra: { area: string }) => void` | 否 | 确认选择回调。 | +| `type` | `"baidu" \| "cesium"` | 否 | 地图类型。 | + +### MapSelector + +引入： + +```tsx +import MapSelector from "zy-react-library/components/Map/MapSelector"; +``` + +地图选择弹窗。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `visible` | `boolean` | 是 | 是否显示弹窗。 | +| `onClose` | `() => void` | 是 | 关闭回调。 | +| `longitude` | `number \| string` | 否 | 初始经度。 | +| `latitude` | `number \| string` | 否 | 初始纬度。 | +| `area` | `string` | 否 | 初始区域文本。 | +| `showArea` | `boolean` | 否 | 是否显示区域。 | +| `disable` | `boolean` | 否 | 是否禁用选择。 | +| `onConfirm` | `(longitude, latitude, extra: { area: string }) => void` | 否 | 确认选择回调。 | +| `type` | `"baidu" \| "cesium"` | 否 | 地图类型。 | + +### SeamlessScroll + +引入： + +```tsx +import SeamlessScroll from "zy-react-library/components/SeamlessScroll"; +``` + +无缝滚动组件，支持 `ref.reset()`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `value` | `boolean` | 否 | 是否启用滚动。 | +| `list` | `unknown[]` | 是 | 滚动数据列表。 | +| `step` | `number` | 否 | 滚动步长。 | +| `limitScrollNum` | `number` | 否 | 触发滚动的最小数据条数。 | +| `hover` | `boolean` | 否 | 鼠标悬浮时是否暂停。 | +| `direction` | `"up" \| "down" \| "left" \| "right"` | 否 | 滚动方向。 | +| `singleHeight` | `number` | 否 | 单条高度。 | +| `singleWidth` | `number` | 否 | 单条宽度。 | +| `singleWaitTime` | `number` | 否 | 单步滚动等待时间。 | +| `isRemUnit` | `boolean` | 否 | 尺寸是否使用 rem 单位。 | +| `isWatch` | `boolean` | 否 | 是否监听数据变化并重置滚动。 | +| `delay` | `number` | 否 | 动画延迟。 | +| `ease` | `string \| { x1: number; y1: number; x2: number; y2: number }` | 否 | 动画缓动函数。 | +| `count` | `number` | 否 | 滚动次数。 | +| `copyNum` | `number` | 否 | 复制列表份数。 | +| `wheel` | `boolean` | 否 | 是否支持滚轮。 | +| `singleLine` | `boolean` | 否 | 是否单行滚动。 | +| `className` | `string` | 否 | 自定义类名。 | + +### SelectCreate + +引入： + +```tsx +import SelectCreate from "zy-react-library/components/SelectCreate"; +``` + +可创建/删除选项的选择器，继承 `antd SelectProps`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `items` | `SelectCreateOption[]` | 是 | 选项列表。 | +| `showDelete` | `boolean` | 否 | 是否显示删除选项能力。 | +| `label` | `string` | 否 | 创建项标签文案。 | +| `onDelete` | `(option: SelectCreateOption) => void` | 否 | 删除选项回调。 | + +`SelectCreateOption`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `id` | `string \| number` | 选项值。 | +| `name` | `string` | 选项名称。 | + +### HiddenInfo + +引入： + +```tsx +import HiddenInfo from "zy-react-library/components/HiddenInfo/gwj"; +``` + +隐患信息展示组件。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `id` | `string` | 否 | 业务 ID。 | +| `idKey` | `string` | 否 | 业务 ID 字段名。 | +| `hiddenId` | `string` | 否 | 隐患 ID。 | +| `hiddenIdKey` | `string` | 否 | 隐患 ID 字段名。 | +| `history` | `boolean` | 否 | 是否展示历史相关内容。 | +| `onGetData` | `(data: Record) => void` | 否 | 获取详情数据后的回调。 | + +## Select 选择器 + +### BasicSelect + +引入： + +```tsx +import BasicSelect from "zy-react-library/components/Select/Basic"; +``` + +基础选择器，继承 `antd SelectProps`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `data` | `Record[]` | 是 | 选项数据。 | +| `nameKey` | `string` | 否 | 标签字段名。 | +| `idKey` | `string` | 否 | 值字段名。 | +| `placeholder` | `string` | 否 | 占位文案。 | +| `onGetLabel` | `(label: string \| string[]) => void` | 否 | 选择后返回标签。 | +| `onGetOption` | `(option: Record \| Record[]) => void` | 否 | 选择后返回选项对象。 | +| `onGetData` | `(data: Record[]) => void` | 否 | 返回处理后的选项数据。 | +| `labelRender` | `(item: Record) => ReactNode` | 否 | 自定义选项标签渲染。 | + +### DictionarySelect + +引入： + +```tsx +import DictionarySelect from "zy-react-library/components/Select/Dictionary"; +``` + +字典选择器，继承 `BasicSelectProps`，但内部接管 `data`、默认字段和部分回调。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `appKey` | `string` | 否 | 字典应用 key。 | +| `dictValue` | `string` | 是 | 字典类型值。 | +| `nameKey` | `string` | 否 | 标签字段名。 | +| `idKey` | `string` | 否 | 值字段名。 | +| `onGetOption` | `(option: DictionarySelectItem \| DictionarySelectItem[]) => void` | 否 | 选择后返回字典项。 | +| `onGetData` | `(data: DictionarySelectItem[]) => void` | 否 | 返回字典数据。 | + +`DictionarySelectItem`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `dictValue` | `string` | 字典项值。 | +| `dictLabel` | `string` | 字典项标签。 | + +### PersonnelSelect + +引入： + +```tsx +import PersonnelSelect from "zy-react-library/components/Select/Personnel/Gwj"; +``` + +人员选择器，继承 `BasicSelectProps`，内部接管人员数据源和默认字段。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `params` | `Params` | 否 | 人员查询基础参数。 | +| `placeholder` | `string` | 否 | 占位文案。 | +| `isNeedCorpInfoId` | `boolean` | 否 | 是否需要企业 ID。 | +| `isNeedPostId` | `boolean` | 否 | 是否需要岗位 ID。 | +| `isNeedDepartmentId` | `boolean` | 否 | 是否需要部门 ID。 | +| `extraParams` | `ExtraParams` | 否 | 人员查询额外参数。 | +| `onGetOption` | `(option: PersonnelSelectItem \| PersonnelSelectItem[]) => void` | 否 | 选择后返回人员项。 | +| `onGetData` | `(data: PersonnelSelectItem[]) => void` | 否 | 返回人员数据。 | + +`Params`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `corpinfoId` | `string` | 企业 ID。 | +| `postId` | `string` | 岗位 ID。 | +| `departmentId` | `string` | 部门 ID。 | + +`ExtraParams`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `noMain` | `1 \| ""` | 是否过滤主账号相关数据。 | +| `eqEmploymentFlag` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 11 \| 10` | 用工状态筛选。 | +| `flowFlag` | `1 \| 0` | 流程标识。 | +| `rzFlag` | `1 \| 0` | 认证标识。 | + +`PersonnelSelectItem`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `id` | `string` | 数据 ID。 | +| `name` | `string` | 姓名。 | +| `corpinfoId` | `string` | 企业 ID。 | +| `corpinfoName` | `string` | 企业名称。 | +| `departmentId` | `string` | 部门 ID。 | +| `departmentName` | `string` | 部门名称。 | +| `postId` | `string` | 岗位 ID。 | +| `postName` | `string` | 岗位名称。 | +| `userId` | `string` | 用户 ID。 | +| `username` | `string` | 用户名。 | + +## SelectTree 树选择器 + +### BasicSelectTree + +引入： + +```tsx +import BasicSelectTree from "zy-react-library/components/SelectTree/Basic"; +``` + +基础树选择器，继承 `Omit`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `nameKey` | `string` | 否 | 节点标签字段名。 | +| `idKey` | `string` | 否 | 节点值字段名。 | +| `childrenKey` | `string` | 否 | 子节点字段名。 | +| `getNodePathsIsIncludeOneself` | `boolean` | 否 | 获取节点路径时是否包含当前节点。 | +| `onGetNodePaths` | `(nodes: Record[]) => void` | 否 | 返回当前节点路径。 | +| `placeholder` | `string` | 否 | 占位文案。 | +| `level` | `number` | 否 | 限制展示层级。 | +| `onGetLabel` | `(label: string \| string[]) => void` | 否 | 返回选中标签。 | +| `onGetData` | `(data, processedData) => void` | 否 | 返回原始数据和处理后的数据。 | +| `onlyLastLevel` | `boolean` | 否 | 是否只允许选择最后一级。 | + +### AreaSelectTree + +引入： + +```tsx +import AreaSelectTree from "zy-react-library/components/SelectTree/Area"; +``` + +地区树选择器，继承 `BasicSelectTree` 能力，内部接管地区数据、默认字段和占位文案。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `onGetNodePaths` | `(nodes: AreaSelectTreeItem[]) => void` | 否 | 返回地区节点路径。 | +| `onGetData` | `(data: AreaSelectTreeItem[], processedData: AreaSelectTreeItem[]) => void` | 否 | 返回原始地区数据和处理后的地区数据。 | + +`AreaSelectTreeItem`：`value: string`、`label: string`、`children: AreaSelectTreeItem[]`。 + +### IndustrySelectTree + +引入： + +```tsx +import IndustrySelectTree from "zy-react-library/components/SelectTree/Industry"; +``` + +行业树选择器。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `onGetNodePaths` | `(nodes: IndustrySelectTreeItem[]) => void` | 否 | 返回行业节点路径。 | +| `onGetData` | `(data: IndustrySelectTreeItem[], processedData: IndustrySelectTreeItem[]) => void` | 否 | 返回原始行业数据和处理后的行业数据。 | + +`IndustrySelectTreeItem`：`dict_value: string`、`dict_label: string`、`childrenList: IndustrySelectTreeItem[]`。 + +### DictionarySelectTree + +引入： + +```tsx +import DictionarySelectTree from "zy-react-library/components/SelectTree/Dictionary"; +``` + +字典树选择器。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `appKey` | `string` | 否 | 字典应用 key。 | +| `dictValue` | `string` | 是 | 字典类型值。 | +| `nameKey` | `string` | 否 | 节点标签字段名。 | +| `idKey` | `string` | 否 | 节点值字段名。 | +| `onGetNodePaths` | `(nodes: DictionarySelectTreeItem[]) => void` | 否 | 返回字典节点路径。 | +| `onGetData` | `(data: DictionarySelectTreeItem[], processedData: DictionarySelectTreeItem[]) => void` | 否 | 返回原始字典数据和处理后的字典数据。 | + +`DictionarySelectTreeItem`：`dictValue: string`、`dictLabel: string`、`children: DictionarySelectTreeItem[]`。 + +### DepartmentSelectTree + +引入： + +```tsx +import DepartmentSelectTree from "zy-react-library/components/SelectTree/Department/Gwj"; +``` + +部门树选择器。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `params` | `Params` | 否 | 部门查询参数。 | +| `placeholder` | `string` | 否 | 占位文案。 | +| `isNeedCorpInfoId` | `boolean` | 否 | 是否需要企业 ID。 | +| `isNeedParentId` | `boolean` | 否 | 是否需要父级 ID。 | +| `searchType` | `"current" \| "all" \| "inType"` | 否 | 查询范围类型。 | +| `onGetNodePaths` | `(nodes: DepartmentSelectTreeItem[]) => void` | 否 | 返回部门节点路径。 | +| `onGetData` | `(data: DepartmentSelectTreeItem[], processedData: DepartmentSelectTreeItem[]) => void` | 否 | 返回原始部门数据和处理后的部门数据。 | + +`Params`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `eqCorpinfoId` | `string` | 企业 ID。 | +| `eqParentId` | `string` | 父级部门 ID。 | +| `inType` | `InType[]` | 部门类型集合。 | +| `enterpriseType` | `EnterpriseType \| EnterpriseType[]` | 企业类型。 | + +`DepartmentSelectTreeItem`：`id: string`、`name: string`、`childrenList: DepartmentSelectTreeItem[]`。 + +### HiddenLevelSelectTree + +引入： + +```tsx +import HiddenLevelSelectTree from "zy-react-library/components/SelectTree/HiddenLevel/Gwj"; +``` + +隐患等级树选择器。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `isShowNeglect` | `boolean` | 否 | 是否显示可忽略等级。 | +| `isShowLarger` | `boolean` | 否 | 是否显示较大等级。 | +| `isShowMajor` | `boolean` | 否 | 是否显示重大等级。 | +| `onGetNodePaths` | `(nodes: HiddenLevelSelectTreeItem[]) => void` | 否 | 返回隐患等级节点路径。 | +| `onGetData` | `(data: HiddenLevelSelectTreeItem[], processedData: HiddenLevelSelectTreeItem[]) => void` | 否 | 返回原始数据和处理后的数据。 | + +`HiddenLevelSelectTreeItem`：`dictValue: string`、`dictLabel: string`、`children: HiddenLevelSelectTreeItem[]`。 + +### HiddenPartSelectTree + +引入： + +```tsx +import HiddenPartSelectTree from "zy-react-library/components/SelectTree/HiddenPart/Gwj"; +``` + +隐患部位树选择器。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `params` | `{ eqCorpinfoId?: string }` | 否 | 查询参数。 | +| `isNeedCorpInfoId` | `boolean` | 否 | 是否需要企业 ID。 | +| `onGetNodePaths` | `(nodes: HiddenPartSelectTreeItem[]) => void` | 否 | 返回隐患部位节点路径。 | +| `onGetData` | `(data: HiddenPartSelectTreeItem[], processedData: HiddenPartSelectTreeItem[]) => void` | 否 | 返回原始数据和处理后的数据。 | + +`HiddenPartSelectTreeItem`：`hiddenregionId: string`、`hiddenregion: string`、`children: HiddenPartSelectTreeItem[]`。 + +## Cascader 级联选择器 + +### BasicCascader + +引入： + +```tsx +import BasicCascader from "zy-react-library/components/Cascader/Basic"; +``` + +基础级联选择器，继承 `Omit`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `nameKey` | `string` | 否 | 节点标签字段名。 | +| `idKey` | `string` | 否 | 节点值字段名。 | +| `childrenKey` | `string` | 否 | 子节点字段名。 | +| `getNodePathsIsIncludeOneself` | `boolean` | 否 | 获取节点路径时是否包含当前节点。 | +| `onGetNodePaths` | `(nodes: Record[]) => void` | 否 | 返回当前节点路径。 | +| `placeholder` | `string` | 否 | 占位文案。 | +| `level` | `number` | 否 | 限制展示层级。 | +| `onGetData` | `(data, processedData) => void` | 否 | 返回原始数据和处理后的数据。 | + +### AreaCascader + +引入： + +```tsx +import AreaCascader from "zy-react-library/components/Cascader/Area"; +``` + +地区级联选择器。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `onGetNodePaths` | `(nodes: AreaCascaderItem[]) => void` | 否 | 返回地区节点路径。 | +| `onGetData` | `(data: AreaCascaderItem[], processedData: AreaCascaderItem[]) => void` | 否 | 返回原始地区数据和处理后的地区数据。 | + +`AreaCascaderItem`：`value: string`、`label: string`、`children: AreaCascaderItem[]`。 + +### IndustryCascader + +引入： + +```tsx +import IndustryCascader from "zy-react-library/components/Cascader/Industry"; +``` + +行业级联选择器。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `onGetNodePaths` | `(nodes: IndustryCascaderItem[]) => void` | 否 | 返回行业节点路径。 | +| `onGetData` | `(data: IndustryCascaderItem[], processedData: IndustryCascaderItem[]) => void` | 否 | 返回原始行业数据和处理后的行业数据。 | + +`IndustryCascaderItem`：`dict_value: string`、`dict_label: string`、`childrenList: IndustryCascaderItem[]`。 + +### DictionaryCascader + +引入： + +```tsx +import DictionaryCascader from "zy-react-library/components/Cascader/Dictionary"; +``` + +字典级联选择器。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `appKey` | `string` | 否 | 字典应用 key。 | +| `dictValue` | `string` | 是 | 字典类型值。 | +| `nameKey` | `string` | 否 | 节点标签字段名。 | +| `idKey` | `string` | 否 | 节点值字段名。 | +| `onGetNodePaths` | `(nodes: DictionaryCascaderItem[]) => void` | 否 | 返回字典节点路径。 | +| `onGetData` | `(data: DictionaryCascaderItem[], processedData: DictionaryCascaderItem[]) => void` | 否 | 返回原始字典数据和处理后的字典数据。 | + +`DictionaryCascaderItem`：`dictValue: string`、`dictLabel: string`、`children: DictionaryCascaderItem[]`。 + +## LeftTree 左侧树 + +### BasicLeftTree + +引入： + +```tsx +import BasicLeftTree from "zy-react-library/components/LeftTree/Basic"; +``` + +基础树组件，继承 `Omit`。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `nameKey` | `string` | 否 | 节点标题字段名。 | +| `idKey` | `string` | 否 | 节点 key 字段名。 | +| `childrenKey` | `string` | 否 | 子节点字段名。 | +| `getNodePathsIsIncludeOneself` | `boolean` | 否 | 获取节点路径时是否包含当前节点。 | +| `onGetNodePaths` | `(nodes: Record[]) => void` | 否 | 返回当前节点路径。 | +| `onGetData` | `(data: Record[]) => void` | 否 | 返回树数据。 | + +### AreaLeftTree + +引入： + +```tsx +import AreaLeftTree from "zy-react-library/components/LeftTree/Area"; +``` + +地区左侧树。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `onGetNodePaths` | `(nodes: AreaLeftTreeItem[]) => void` | 否 | 返回地区节点路径。 | +| `onGetData` | `(data: AreaLeftTreeItem[], processedData: AreaLeftTreeItem[]) => void` | 否 | 返回原始地区数据和处理后的地区数据。 | + +`AreaLeftTreeItem`：`value: string`、`label: string`、`children: AreaLeftTreeItem[]`。 + +### DictionaryLeftTree + +引入： + +```tsx +import DictionaryLeftTree from "zy-react-library/components/LeftTree/Dictionary"; +``` + +字典左侧树。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `appKey` | `string` | 否 | 字典应用 key。 | +| `dictValue` | `string` | 是 | 字典类型值。 | +| `nameKey` | `string` | 否 | 节点标题字段名。 | +| `idKey` | `string` | 否 | 节点 key 字段名。 | +| `onGetNodePaths` | `(nodes: DictionaryLeftTreeItem[]) => void` | 否 | 返回字典节点路径。 | +| `onGetData` | `(data: DictionaryLeftTreeItem[], processedData: DictionaryLeftTreeItem[]) => void` | 否 | 返回原始字典数据和处理后的字典数据。 | + +`DictionaryLeftTreeItem`：`dictValue: string`、`dictLabel: string`、`children: DictionaryLeftTreeItem[]`。 + +### DepartmentLeftTree + +引入： + +```tsx +import DepartmentLeftTree from "zy-react-library/components/LeftTree/Department/Gwj"; +``` + +部门左侧树。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `params` | `DepartmentSelectTreeProps["params"]` | 否 | 部门查询参数。 | +| `searchType` | `DepartmentSelectTreeProps["searchType"]` | 否 | 查询范围类型。 | +| `onGetNodePaths` | `(nodes: DepartmentLeftTreeItem[]) => void` | 否 | 返回部门节点路径。 | +| `onGetData` | `(data: DepartmentLeftTreeItem[], processedData: DepartmentLeftTreeItem[]) => void` | 否 | 返回原始部门数据和处理后的部门数据。 | + +`DepartmentLeftTreeItem`：`id: string`、`name: string`、`childrenList: DepartmentLeftTreeItem[]`。 + +## Icon 图标 + +图标组件均继承 `AntdIconProps`。 + +| 组件 | 引入路径 | +| --- | --- | +| `AddIcon` | `zy-react-library/components/Icon/AddIcon` | +| `BackIcon` | `zy-react-library/components/Icon/BackIcon` | +| `DeleteIcon` | `zy-react-library/components/Icon/DeleteIcon` | +| `DownloadIcon` | `zy-react-library/components/Icon/DownloadIcon` | +| `EditIcon` | `zy-react-library/components/Icon/EditIcon` | +| `ExportIcon` | `zy-react-library/components/Icon/ExportIcon` | +| `ImportIcon` | `zy-react-library/components/Icon/ImportIcon` | +| `LocationIcon` | `zy-react-library/components/Icon/LocationIcon` | +| `PrintIcon` | `zy-react-library/components/Icon/PrintIcon` | +| `ResetIcon` | `zy-react-library/components/Icon/ResetIcon` | +| `SearchIcon` | `zy-react-library/components/Icon/SearchIcon` | +| `VideoIcon` | `zy-react-library/components/Icon/VideoIcon` | +| `ViewIcon` | `zy-react-library/components/Icon/ViewIcon` | + +## Hooks + +### useTable + +引入： + +```tsx +import useTable from "zy-react-library/hooks/useTable"; +``` + +基于 `ahooks useAntdTable` 扩展。 + +```ts +useTable(service, options?) +``` + +`options` 继承 `Omit, "defaultParams" | "form" | "defaultType">`，并扩展： + +| 参数 | 类型 | 必填 | 默认值 | 说明 | +| --- | --- | --- | --- | --- | +| `usePagination` | `boolean` | 否 | `true` | 是否启用分页。 | +| `defaultPagination` | `{ current: number; pageSize: number }` | 否 | `{ current: 1, pageSize: 20 }` | 默认分页参数。 | +| `useStorageQueryCriteria` | `boolean` | 否 | `true` | 是否启用查询条件存储。 | +| `usePermission` | `boolean` | 否 | `true` | 是否启用数据权限参数；开启时请求参数会追加 `menuPath=window.location.pathname`。 | +| `params` | `Record \| (() => Record)` | 否 | - | 附加请求参数。 | +| `transform` | `(formData: Record) => Record` | 否 | - | 请求前转换搜索表单数据。 | +| `callback` | `(list: any[], data: any) => void` | 否 | - | 已废弃，建议使用 `onSuccess`。 | +| `form` | `FormInstance` | 否 | - | antd 表单实例。 | + +返回值扩展： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `tableProps.dataSource` | `TData["list"]` | 表格数据。 | +| `tableProps.loading` | `boolean` | 表格加载状态。 | +| `tableProps.onChange` | `(pagination, filters?, sorter?) => void` | 表格变化回调。 | +| `tableProps.pagination` | `false \| ExtendedPaginationConfig` | 分页配置。 | +| `getData` | `() => void` | 触发查询，等价于 `search.submit`。 | + +`BasePaginationConfig`：`current: number`、`pageSize: number`、`total: number`。 + +`ExtendedPaginationConfig`：在 `BasePaginationConfig` 基础上增加 `showQuickJumper: boolean`、`showSizeChanger: boolean`。 + +### useUploadFile + +引入： + +```tsx +import useUploadFile from "zy-react-library/hooks/useUploadFile"; +``` + +重载： + +```ts +useUploadFile("array"): [boolean, UploadFileFunction] +useUploadFile("object"): { loading: boolean; uploadFile: UploadFileFunction } +``` + +`UploadFile`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `originFileObj` | `File` | 原始文件对象。 | +| `filePath` | `string` | 文件地址。 | +| `id` | `string` | 文件 ID。 | +| `[key: string]` | `any` | 业务扩展字段。 | + +单文件上传参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `files` | `UploadFile[]` | 是 | 待上传文件。 | +| `single` | `true` | 否 | 单文件上传标识。 | +| `params` | `SingleParams` | 是 | 上传参数。 | + +`SingleParams`：`type: number`、`corpinfoId?: string`、`foreignKey?: string`。 + +多文件上传参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `files` | `UploadFile[]` | 是 | 待上传文件。 | +| `single` | `false` | 是 | 多文件上传标识。 | +| `params` | `MultipleParams` | 是 | 上传参数。 | + +`MultipleParams`：`type: number`、`corpinfoId?: string`、`foreignKey: string`。 + +返回值：单文件返回 `Promise<{ filePath: string; [key: string]: any }>`，多文件返回 `Promise<{ id: string; [key: string]: any }>`. + +### useGetFile + +引入： + +```tsx +import useGetFile from "zy-react-library/hooks/useGetFile"; +``` + +重载： + +```ts +useGetFile("array"): [boolean, GetFileFunction] +useGetFile("object"): { loading: boolean; getFile: GetFileFunction } +``` + +单文件获取参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `eqType` | `number` | 是 | 文件类型。 | +| `eqForeignKey` | `string` | 是 | 外键 ID。 | +| `single` | `true` | 否 | 单文件获取标识。 | + +多文件获取参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `eqType` | `number` | 是 | 文件类型。 | +| `foreignKey` | `string` | 是 | `dataSource` 中外键 ID 的字段名。 | +| `single` | `false` | 是 | 多文件获取标识。 | +| `dataSource` | `Record[]` | 是 | 原始数据源。 | + +`GetFileItem`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `filePath` | `string` | 文件路径。 | +| `fileName` | `string` | 文件名称。 | +| `id` | `string` | 文件 ID。 | +| `url` | `string` | 文件完整 URL。 | +| `name` | `string` | 文件展示名称。 | +| `[key: string]` | `any` | 业务扩展字段。 | + +### useDeleteFile + +引入： + +```tsx +import useDeleteFile from "zy-react-library/hooks/useDeleteFile"; +``` + +重载： + +```ts +useDeleteFile("array"): [boolean, DeleteFileFunction] +useDeleteFile("object"): { loading: boolean; deleteFile: DeleteFileFunction } +``` + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `files` | `DeleteFileItem[]` | 是 | 待删除文件。 | +| `single` | `boolean` | 否 | 是否按单文件删除。 | + +`DeleteFileItem`：`filePath?: string`、`id?: string`。 + +### useImportFile + +引入： + +```tsx +import useImportFile from "zy-react-library/hooks/useImportFile"; +``` + +重载： + +```ts +useImportFile("array"): [boolean, ImportFileFunction] +useImportFile("object"): { loading: boolean; importFile: ImportFileFunction } +``` + +`importFile(url, options)` 参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `url` | `string` | 是 | 导入接口地址。 | +| `options.files` | `UploadFile[]` | 是 | 上传文件数组。 | +| `options.params` | `Record` | 否 | 额外提交参数。 | + +`UploadFile`：`originFileObj?: File`，并支持业务扩展字段。 + +### useDownloadFile + +引入： + +```tsx +import useDownloadFile from "zy-react-library/hooks/useDownloadFile"; +``` + +重载： + +```ts +useDownloadFile("array"): [boolean, DownloadFileFunction] +useDownloadFile("object"): { loading: boolean; downloadFile: DownloadFileFunction } +``` + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `url` | `string` | 是 | 下载地址。 | +| `name` | `string` | 否 | 下载文件名。 | + +### useDownloadBlob + +引入： + +```tsx +import useDownloadBlob from "zy-react-library/hooks/useDownloadBlob"; +``` + +重载： + +```ts +useDownloadBlob("array"): [boolean, DownloadBlobFunction] +useDownloadBlob("object"): { loading: boolean; downloadBlob: DownloadBlobFunction } +``` + +`downloadBlob(url, options?)` 参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `url` | `string` | 是 | 下载接口地址。 | +| `options.name` | `string` | 否 | 自定义文件名，不含后缀。 | +| `options.type` | `string` | 否 | Blob MIME 类型。 | +| `options.params` | `Record` | 否 | 请求查询参数。 | + +返回：`Promise<{ data: Blob }>`。 + +### useDictionary + +引入： + +```tsx +import useDictionary from "zy-react-library/hooks/useDictionary"; +``` + +重载： + +```ts +useDictionary("array"): [boolean, getDictionaryFunction] +useDictionary("object"): { loading: boolean; getDictionary: getDictionaryFunction } +``` + +`getDictionary(options)` 参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `appKey` | `string` | 否 | 字典应用 key。 | +| `dictValue` | `string` | 是 | 字典类型值。 | + +返回 `Promise`。 + +`DictionaryItem`：`dictLabel: string`、`dictValue: string`、`children: DictionaryItem[]`。 + +### useGetUserInfo + +引入： + +```tsx +import useGetUserInfo from "zy-react-library/hooks/useGetUserInfo"; +``` + +重载： + +```ts +useGetUserInfo("array"): [boolean, getUserInfoFunction] +useGetUserInfo("object"): { loading: boolean; getUserInfo: getUserInfoFunction } +``` + +`getUserInfo` 无参数，返回 `Promise`。 + +`UserInfoData`： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `corpinfoId` | `string` | 企业 ID。 | +| `corpinfoName` | `string` | 企业名称。 | +| `departmentId` | `string` | 部门 ID。 | +| `departmentName` | `string` | 部门名称。 | +| `id` | `string` | 数据 ID。 | +| `name` | `string` | 姓名。 | +| `postId` | `string` | 岗位 ID。 | +| `postName` | `string` | 岗位名称。 | +| `userId` | `string` | 用户 ID。 | +| `username` | `string` | 用户名。 | +| `[key: string]` | `any` | 业务扩展字段。 | + +### useGetUrlQuery + +引入： + +```tsx +import useGetUrlQuery from "zy-react-library/hooks/useGetUrlQuery"; +``` + +无参数，返回当前 URL 查询参数对象：`Record`。 + +### useUrlQueryCriteria + +引入： + +```tsx +import useUrlQueryCriteria from "zy-react-library/hooks/useUrlQueryCriteria"; +``` + +返回： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `setUrlCriteriaQuery` | `(searchForm: Record, pagination: Record) => void` | 将搜索项和分页信息写入 URL 查询参数。 | +| `getUrlCriteriaQuery` | `(keysStr, valuesStr) => Record` | 从 URL 查询参数中读取指定条件。 | + +`getUrlCriteriaQuery` 参数： + +| 参数 | 类型 | 说明 | +| --- | --- | --- | +| `keysStr` | `"searchFormKeys" \| "paginationKeys" \| string` | 存储字段名集合的 key。 | +| `valuesStr` | `"searchFormValues" \| "paginationValues" \| string` | 存储字段值集合的 key。 | + +### useIdle + +引入： + +```tsx +import useIdle from "zy-react-library/hooks/useIdle"; +``` + +检测用户是否空闲。 + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `timeout` | `number` | 否 | 空闲超时时间。 | +| `events` | `string[]` | 否 | 用于判断活跃状态的事件名列表。 | + +返回：`boolean`，表示是否处于空闲状态。 + +### useIsExistenceDuplicateSelection + +引入： + +```tsx +import useIsExistenceDuplicateSelection from "zy-react-library/hooks/useIsExistenceDuplicateSelection"; +``` + +返回 `{ isExistenceDuplicateSelection }`，用于判断选择项中是否存在重复数据。 + +`isExistenceDuplicateSelection(options)` 参数： + +| 参数 | 类型 | 必填 | 说明 | +| --- | --- | --- | --- | +| `data` | `T[]` | 是 | 需要检查重复项的目标数组。 | +| `key` | `keyof T \| string` | 是 | 用于判断重复的对象属性名。 | +| `message` | `string` | 否 | 存在重复项时的错误提示。 | + +返回：`Promise`。 + +### useGetFile、useUploadFile、useDeleteFile 的 loading + +这些请求类 Hook 均支持两种返回格式： + +```ts +const { loading, uploadFile } = useUploadFile(); +const [loading, uploadFile] = useUploadFile("array"); +``` + +## 工具函数 + +引入： + +```ts +import { serialNumber, getFileName } from "zy-react-library/utils"; +``` + +| 函数 | 参数 | 返回值 | 说明 | +| --- | --- | --- | --- | +| `serialNumber` | `pagination: BasePaginationConfig`, `index: number` | `number` | 根据分页信息和行索引计算序号。 | +| `toArrayString` | `value: string` | `Array` | 将字符串转换成字符串数组。 | +| `interceptTheSuffix` | `name: string`, `suffix: string` | `boolean` | 判断文件名是否匹配指定后缀。 | +| `image2Base64` | `imgUrl: string` | `Promise` | 将图片地址转换为 base64。 | +| `image2Base642` | `file: File` | `Promise` | 将文件对象转换为 base64。 | +| `checkImgExists` | `imgUrl: string` | `Promise` | 检查图片地址是否可加载。 | +| `getDataType` | `data: any` | `DataType` | 获取数据类型。 | +| `ArrayDeduplication` | `arr: T[]` | `T[]` | 数组去重。 | +| `arrayObjectDeduplication` | `arr: T[]`, `key: string` | `T[]` | 对象数组按指定字段去重。 | +| `findCharIndex` | `{ str: string; char: string; num: number }` | `number` | 查找字符第 `num` 次出现的位置。 | +| `randoms` | `min: number`, `max: number` | `number` | 生成范围随机数。 | +| `numFormat` | `num: number \| string` | `string` | 数字格式化。 | +| `isEmpty` | `value: any` | `boolean` | 判断值是否为空。 | +| `getUrlParam` | `key: string` | `string` | 获取 URL 指定查询参数。 | +| `paging` | `{ list: Record[]; currentPage: number \| string; pageSize: number \| string }` | `T[]` | 对数组做前端分页。 | +| `getFileSuffix` | `name: string` | `FileSuffix` | 获取文件后缀。 | +| `getFileName` | `name: string` | `string` | 获取文件名。 | +| `readTxtDocument` | `filePah: string` | `Promise` | 读取 txt 文档内容。 | +| `secondConversion` | `second: string \| number` | `string` | 秒数格式化。 | +| `addingPrefixToFile` | `list: T[]`, `options?: { pathKey?: string; nameKey?: string; idKey?: string }` | `(T & { url: string; name: string; id: any })[]` | 为文件列表补充完整地址、名称和 ID。 | +| `getLabelName` | `{ status: number \| string; list: Record[]; idKey?: string; nameKey?: string }` | `string \| undefined` | 根据值从列表中获取标签。 | +| `calculateFileSize` | `size: number \| string` | `string` | 格式化文件大小。 | +| `idCardGetDateAndGender` | `idCard: string` | `{ sex: "1" \| "0"; date: string }` | 从身份证号解析性别和出生日期。 | +| `getMatchedItems` | `{ list: Record[]; value: (number \| string)[]; idKey?: string }` | `T[]` | 获取匹配值集合的数据项。 | +| `getUnmatchedItems` | `{ list: Record[]; value: (number \| string)[]; idKey?: string }` | `T[]` | 获取不匹配值集合的数据项。 | +| `listTransTree` | `{ json: Record[]; idKey: string; parentIdKey: string; childrenKey: string }` | `T[]` | 将扁平列表转换为树。 | +| `isEmptyToWhether` | `value: any`, `options?: { yesText?: string; noText?: string; yesValue?: string \| number }` | `string` | 将值转换为是否文案。 | +| `createGuid` | `len?: number` | `string` | 创建随机 ID。 | +| `getIndexColumn` | `pagination: false \| BasePaginationConfig` | `{ title: string; key: string; width: number; render: (...args: any[]) => number }` | 获取表格序号列配置。 | +| `getFileUrl` | 无 | `string` | 获取文件服务地址。 | +| `getBaseGateway` | 无 | `string` | 获取基础网关地址。 | +| `getFileUrlFromServer` | 无 | `Promise` | 从服务端获取文件地址配置。 | +| `base642File` | `base64: string`, `filename?: string` | `File` | 将 base64 转成文件对象。 | +| `getTreeNodePaths` | `{ data; targetId; idKey; childrenKey; path?; isIncludeOneself? }` | `T[] \| null` | 获取树节点路径。 | +| `processTreeDataByLevel` | `{ data; level?; childrenKey; currentLevel? }` | `{ isLeaf: boolean; [key: string]: any }[]` | 按层级处理树数据。 | +| `processTreeDataForOnlyLastLevel` | `{ data; childrenKey; onlyLastLevel? }` | `{ selectable: boolean; [key: string]: any }[]` | 处理树节点是否可选择。 | +| `validatorEndTime` | `{ startTime: string; message?: string; type?: "date" \| "datetime" }` | `{ validator }` | 校验结束时间大于开始时间。 | +| `validatorTimeGTCurrentDay` | `{ message?: string; type?: "date" \| "datetime" }` | `{ validator }` | 校验时间大于当前日期。 | +| `validatorTimeGECurrentDay` | `{ message?: string; type?: "date" \| "datetime" }` | `{ validator }` | 校验时间大于等于当前日期。 | +| `dynamicLoadJs` | `url: string` | `Promise` | 动态加载 JS。 | +| `dynamicLoadCss` | `url: string` | `Promise` | 动态加载 CSS。 | +| `normalizeEmptyHtml` | `html: string` | `string` | 规范化空 HTML 内容。 | +| `executeWithCache` | `cacheKey: string \| object`, `requestFn: () => Promise`, `setData: Dispatch>` | `Promise` | 带缓存执行异步请求，并写入状态。 | + +## 正则 + +引入： + +```ts +import { PHONE, ID_NUMBER } from "zy-react-library/regular"; +``` + +| 常量 | 类型 | 说明 | +| --- | --- | --- | +| `PHONE` | `RegExp` | 中国手机号，支持国家码。 | +| `UNIFIED_SOCIAL_CREDIT_CODE` | `RegExp` | 统一社会信用代码。 | +| `ID_NUMBER` | `RegExp` | 中国大陆身份证号。 | +| `MOBILE_PHONE` | `RegExp` | 不含国家码的手机号。 | +| `FLOATING_POINT_NUMBER` | `RegExp` | 浮点数。 | +| `TWO_DECIMAL_PLACES` | `RegExp` | 两位小数。 | +| `ONE_DECIMAL_PLACES` | `RegExp` | 一位小数。 | +| `LICENSE_PLATE_NUMBER` | `RegExp` | 中国大陆车牌号。 | +| `STRONG_PASSWORD` | `RegExp` | 强密码。 | +| `HTML_TAG` | `RegExp` | HTML 标签。 | +| `POSTAL_CODE` | `RegExp` | 邮政编码。 | +| `TEL_PHONE` | `RegExp` | 座机号码。 | diff --git a/src/components/FormBuilder/FormBuilder.js b/src/components/FormBuilder/FormBuilder.js index e2ba47e..d26b536 100644 --- a/src/components/FormBuilder/FormBuilder.js +++ b/src/components/FormBuilder/FormBuilder.js @@ -79,7 +79,7 @@ const FormBuilder = (props) => { /> {showActionButtons && ( -
+
{ const componentProps = getComponentProps(option); + if (getHidden(option.hidden)) + return null; + // 如果是 customizeRender 类型，完全交给外部控制渲染 if (option.customizeRender) { return ( @@ -520,30 +523,14 @@ const FormItemsRenderer = ({ return null; }; - // 渲染需要动态更新的表单项 - const renderDynamicFormItem = ({ option, index, style, col, preserve }) => { - const formItemProps = getFormItemProps(option); - - return ( - - {() => { - return renderFormItem({ option, style, col, index, preserve }); - }} - - ); - }; - // 渲染 Form.List const renderFormList = ({ option, index, col, style }) => { const formListUniqueProps = getFormListUniqueProps(option); const componentProps = getComponentProps(option); + if (getHidden(option.hidden)) + return null; + return ( {getColTitle(option)} @@ -568,6 +555,12 @@ const FormItemsRenderer = ({ index: `${fieldIndex}_${listIndex}`, preserve: true, }; + + // 如果配置了 shouldUpdate 或 dependencies，使用 Form.Item 的联动机制 + // 注意：动态检测必须在 renderOtherTypeItem 之前，否则特殊类型（customizeRender / onlyForLabel / DIVIDER）无法响应联动 + if (getIsDynamicFormItem(listOption, formItemProps)) + return renderDynamicFormItem(params); + const otherTypeItem = renderOtherTypeItem(params); if (otherTypeItem) return otherTypeItem; @@ -575,9 +568,6 @@ const FormItemsRenderer = ({ if (listOption.render === FORM_ITEM_RENDER_ENUM.FORM_LIST) return renderFormList(params); - if (getIsDynamicFormItem(listOption, formItemProps)) - return renderDynamicFormItem(params); - // 判断一个项是否需要显示按钮（不是 onlyForLabel 且不是隐藏的） const isShow = (opt) => { return !getHidden(opt.hidden) && !opt.onlyForLabel; @@ -674,6 +664,32 @@ const FormItemsRenderer = ({ ); }; + // 渲染需要动态更新的表单项 + const renderDynamicFormItem = ({ option, index, style, col, preserve }) => { + const formItemProps = getFormItemProps(option); + + return ( + + {() => { + const otherTypeItem = renderOtherTypeItem({ option, style, col, index, preserve }); + if (otherTypeItem) + return otherTypeItem; + + if (option.render === FORM_ITEM_RENDER_ENUM.FORM_LIST) + return renderFormList({ option, index, col, style }); + + return renderFormItem({ option, style, col, index, preserve }); + }} + + ); + }; + return ( <> {options.map((option, index) => { @@ -689,6 +705,10 @@ const FormItemsRenderer = ({ preserve: false, }; + // 如果配置了 shouldUpdate 或 dependencies，使用 Form.Item 的联动机制 + if (getIsDynamicFormItem(option, formItemProps)) + return renderDynamicFormItem(params); + // 处理特殊类型的表单项 const otherTypeItem = renderOtherTypeItem(params); if (otherTypeItem) @@ -698,10 +718,6 @@ const FormItemsRenderer = ({ if (option.render === FORM_ITEM_RENDER_ENUM.FORM_LIST) return renderFormList(params); - // 如果配置了 shouldUpdate 或 dependencies，使用 Form.Item 的联动机制 - if (getIsDynamicFormItem(option, formItemProps)) - return renderDynamicFormItem(params); - // 普通表单项（静态配置） return renderFormItem(params); })} diff --git a/src/components/Page/index.js b/src/components/Page/index.js index 7fc529f..a444709 100644 --- a/src/components/Page/index.js +++ b/src/components/Page/index.js @@ -55,7 +55,7 @@ function Page(props) { {children && typeof children === "function" ? children() : children} { (isShowAllAction && isShowFooter) && ( -
+
{customActionButtons || ( diff --git a/src/enum/uploadFile/aqd/index.d.ts b/src/enum/uploadFile/aqd/index.d.ts new file mode 100644 index 0000000..e363429 --- /dev/null +++ b/src/enum/uploadFile/aqd/index.d.ts @@ -0,0 +1,13 @@ +/** + * 文件上传类型枚举 + */ +export declare const UPLOAD_FILE_TYPE_ENUM: { + 1: 1; // template_task - 模板任务附件 +}; + +/** + * 文件上传类型对应的 path 枚举 + */ +export declare const UPLOAD_FILE_PATH_ENUM: { + 1: "template_task"; +}; diff --git a/src/enum/uploadFile/aqd/index.js b/src/enum/uploadFile/aqd/index.js new file mode 100644 index 0000000..3e9f86f --- /dev/null +++ b/src/enum/uploadFile/aqd/index.js @@ -0,0 +1,16 @@ +/** + * 文件上传类型枚举 + */ +/** + * 文件上传类型枚举 + */ +export const UPLOAD_FILE_TYPE_ENUM = { + 1: 1, // template_task - 模板任务附件 +}; + +/** + * 文件上传类型对应的 path 枚举 + */ +export const UPLOAD_FILE_PATH_ENUM = { + 1: "template_task", +};