1552 lines
66 KiB
Markdown
1552 lines
66 KiB
Markdown
# 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<Values>` | 否 | `{}` | 点击新增时插入的默认值。 |
|
||
| `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<AntdTableProps, "columns">` 与 `ProTableProps<DataSource, U, ValueType>`。
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `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<FormProps, "form" | "onFinish" | "onReset">`。组件上挂载 `Search.useForm`、`Search.useWatch`。
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `options` | `FormOption<Values>[]` | 是 | `[]` | 搜索项配置数组。 |
|
||
| `values` | `DeepPartial<Values>` | 否 | `{}` | 表单值。 |
|
||
| `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<Values>` | 是 | - | antd 表单实例。 |
|
||
|
||
### FormBuilder
|
||
|
||
引入：
|
||
|
||
```tsx
|
||
import FormBuilder from "zy-react-library/components/FormBuilder";
|
||
```
|
||
|
||
表单构建组件，继承 `Omit<FormProps, "form" | "onFinish">`。组件上挂载 `FormBuilder.useForm`、`FormBuilder.useWatch`。
|
||
|
||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `values` | `DeepPartial<Values>` | 否 | - | 表单初始值，会传给 antd `Form.initialValues`。 |
|
||
| `options` | `FormOption<Values>[]` | 是 | - | 表单项配置数组。 |
|
||
| `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<Values>` | 是 | - | 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<Values>[]` | 是 | - | 表单项配置数组。 |
|
||
| `span` | `number` | 否 | `12` | 默认栅格占位。 |
|
||
| `collapse` | `boolean` | 否 | `false` | 是否折叠显示；为 `true` 时索引大于等于 3 的项隐藏。 |
|
||
| `useAutoGenerateRequired` | `boolean` | 否 | `true` | 是否自动生成必填规则。 |
|
||
| `initialValues` | `DeepPartial<Values>` | 否 | - | 初始值，用于表单尚未初始化时提供默认值。 |
|
||
| `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<AntUploadProps, "fileList">`。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `value` | `UploadFile[]` | 否 | 当前文件列表。 |
|
||
| `ratio` | `` `${number}*${number}` `` | 否 | 图片宽高比例提示，例如 `"16*9"`。 |
|
||
| `showTip` | `boolean` | 否 | 是否显示上传提示。 |
|
||
| `size` | `number` | 否 | 文件大小限制。 |
|
||
| `tipContent` | `ReactNode` | 否 | 自定义提示内容。 |
|
||
| `uploadButtonText` | `string` | 否 | 上传按钮文案。 |
|
||
| `fileType` | `"image" \| "video" \| "document"` | 否 | 文件类型。 |
|
||
| `onGetRemoveFile` | `(file: Omit<UploadFile, "originFileObj">) => void` | 否 | 删除文件时返回被移除的文件。 |
|
||
|
||
### ImportFile
|
||
|
||
引入：
|
||
|
||
```tsx
|
||
import ImportFile from "zy-react-library/components/ImportFile";
|
||
```
|
||
|
||
文件导入弹窗，继承 `Omit<FormProps, "form">`。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `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<string, any>` | 否 | 透传给 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<string, any>) => void` | 否 | 获取详情数据后的回调。 |
|
||
|
||
## Select 选择器
|
||
|
||
### BasicSelect
|
||
|
||
引入：
|
||
|
||
```tsx
|
||
import BasicSelect from "zy-react-library/components/Select/Basic";
|
||
```
|
||
|
||
基础选择器，继承 `antd SelectProps`。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `data` | `Record<string, any>[]` | 是 | 选项数据。 |
|
||
| `nameKey` | `string` | 否 | 标签字段名。 |
|
||
| `idKey` | `string` | 否 | 值字段名。 |
|
||
| `placeholder` | `string` | 否 | 占位文案。 |
|
||
| `onGetLabel` | `(label: string \| string[]) => void` | 否 | 选择后返回标签。 |
|
||
| `onGetOption` | `(option: Record<string, any> \| Record<string, any>[]) => void` | 否 | 选择后返回选项对象。 |
|
||
| `onGetData` | `(data: Record<string, any>[]) => void` | 否 | 返回处理后的选项数据。 |
|
||
| `labelRender` | `(item: Record<string, any>) => 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<TreeSelectProps, "fieldNames">`。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `nameKey` | `string` | 否 | 节点标签字段名。 |
|
||
| `idKey` | `string` | 否 | 节点值字段名。 |
|
||
| `childrenKey` | `string` | 否 | 子节点字段名。 |
|
||
| `getNodePathsIsIncludeOneself` | `boolean` | 否 | 获取节点路径时是否包含当前节点。 |
|
||
| `onGetNodePaths` | `(nodes: Record<string, any>[]) => 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<CascaderProps, "fieldNames">`。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `nameKey` | `string` | 否 | 节点标签字段名。 |
|
||
| `idKey` | `string` | 否 | 节点值字段名。 |
|
||
| `childrenKey` | `string` | 否 | 子节点字段名。 |
|
||
| `getNodePathsIsIncludeOneself` | `boolean` | 否 | 获取节点路径时是否包含当前节点。 |
|
||
| `onGetNodePaths` | `(nodes: Record<string, any>[]) => 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<TreeProps, "fieldNames">`。
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `nameKey` | `string` | 否 | 节点标题字段名。 |
|
||
| `idKey` | `string` | 否 | 节点 key 字段名。 |
|
||
| `childrenKey` | `string` | 否 | 子节点字段名。 |
|
||
| `getNodePathsIsIncludeOneself` | `boolean` | 否 | 获取节点路径时是否包含当前节点。 |
|
||
| `onGetNodePaths` | `(nodes: Record<string, any>[]) => void` | 否 | 返回当前节点路径。 |
|
||
| `onGetData` | `(data: Record<string, any>[]) => 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<TData, TParams>(service, options?)
|
||
```
|
||
|
||
`options` 继承 `Omit<AntdTableOptions<TData, TParams>, "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<string, any> \| (() => Record<string, any>)` | 否 | - | 附加请求参数。 |
|
||
| `transform` | `(formData: Record<string, any>) => Record<string, any>` | 否 | - | 请求前转换搜索表单数据。 |
|
||
| `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<string, any>[]` | 是 | 原始数据源。 |
|
||
|
||
`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<string, any>` | 否 | 额外提交参数。 |
|
||
|
||
`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<string, any>` | 否 | 请求查询参数。 |
|
||
|
||
返回：`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[]>`。
|
||
|
||
`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>`。
|
||
|
||
`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<string, any>`。
|
||
|
||
### useUrlQueryCriteria
|
||
|
||
引入：
|
||
|
||
```tsx
|
||
import useUrlQueryCriteria from "zy-react-library/hooks/useUrlQueryCriteria";
|
||
```
|
||
|
||
返回：
|
||
|
||
| 参数 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `setUrlCriteriaQuery` | `(searchForm: Record<string, any>, pagination: Record<string, any>) => void` | 将搜索项和分页信息写入 URL 查询参数。 |
|
||
| `getUrlCriteriaQuery` | `(keysStr, valuesStr) => Record<string, any>` | 从 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<void>`。
|
||
|
||
### 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<string>` | 将字符串转换成字符串数组。 |
|
||
| `interceptTheSuffix` | `name: string`, `suffix: string` | `boolean` | 判断文件名是否匹配指定后缀。 |
|
||
| `image2Base64` | `imgUrl: string` | `Promise<string>` | 将图片地址转换为 base64。 |
|
||
| `image2Base642` | `file: File` | `Promise<string>` | 将文件对象转换为 base64。 |
|
||
| `checkImgExists` | `imgUrl: string` | `Promise<Event>` | 检查图片地址是否可加载。 |
|
||
| `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<string, any>[]; currentPage: number \| string; pageSize: number \| string }` | `T[]` | 对数组做前端分页。 |
|
||
| `getFileSuffix` | `name: string` | `FileSuffix` | 获取文件后缀。 |
|
||
| `getFileName` | `name: string` | `string` | 获取文件名。 |
|
||
| `readTxtDocument` | `filePah: string` | `Promise<string>` | 读取 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<string, any>[]; idKey?: string; nameKey?: string }` | `string \| undefined` | 根据值从列表中获取标签。 |
|
||
| `calculateFileSize` | `size: number \| string` | `string` | 格式化文件大小。 |
|
||
| `idCardGetDateAndGender` | `idCard: string` | `{ sex: "1" \| "0"; date: string }` | 从身份证号解析性别和出生日期。 |
|
||
| `getMatchedItems` | `{ list: Record<string, any>[]; value: (number \| string)[]; idKey?: string }` | `T[]` | 获取匹配值集合的数据项。 |
|
||
| `getUnmatchedItems` | `{ list: Record<string, any>[]; value: (number \| string)[]; idKey?: string }` | `T[]` | 获取不匹配值集合的数据项。 |
|
||
| `listTransTree` | `{ json: Record<string, any>[]; 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<void>` | 从服务端获取文件地址配置。 |
|
||
| `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<void>` | 动态加载 JS。 |
|
||
| `dynamicLoadCss` | `url: string` | `Promise<void>` | 动态加载 CSS。 |
|
||
| `normalizeEmptyHtml` | `html: string` | `string` | 规范化空 HTML 内容。 |
|
||
| `executeWithCache` | `cacheKey: string \| object`, `requestFn: () => Promise<T>`, `setData: Dispatch<SetStateAction<T[]>>` | `Promise<T>` | 带缓存执行异步请求，并写入状态。 |
|
||
|
||
## 正则
|
||
|
||
引入：
|
||
|
||
```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` | 座机号码。 |
|