@hzab/list-render 1.12.10 → 1.12.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +22 -0
- package/README.md +387 -203
- package/dist/index.cjs +1 -1
- package/dist/index.js +286 -285
- package/docs/README.md +15 -0
- package/docs/effect.md +112 -0
- package/docs/form-linkage.md +4 -1
- package/docs/remote-data.md +6 -1
- package/docs/table.md +131 -6
- package/package.json +6 -6
- package/src/list-render.jsx +7 -4
package/README.md
CHANGED
|
@@ -6,6 +6,16 @@
|
|
|
6
6
|
（需另行 clone，在其目录内执行 `npm i` / `npm run dev` 启动配置界面）
|
|
7
7
|
- 官方在线配置地址（配置响应器存在白屏 bug）：https://designable-antd.formilyjs.org/
|
|
8
8
|
|
|
9
|
+
## 目录
|
|
10
|
+
|
|
11
|
+
- [安装](#安装)
|
|
12
|
+
- [组件](#组件)：[Tips](#tips) / [示例](#示例) / [ListRender Attributes](#listrender-attributes) / [Table ref Methods](#table-ref-methods)
|
|
13
|
+
- [编辑模式 editMode](#编辑模式-editmode)
|
|
14
|
+
- [Schema](#schema)：[Schema Scope](#schema-scope) / [响应器中可用的参数](#响应器中可用的参数)
|
|
15
|
+
- [DataModel](#datamodel)
|
|
16
|
+
- [常见问题 FAQ](#常见问题-faq)
|
|
17
|
+
- [相关文档](#相关文档)
|
|
18
|
+
|
|
9
19
|
## 安装
|
|
10
20
|
|
|
11
21
|
```bash
|
|
@@ -21,19 +31,22 @@ pnpm add @hzab/list-render
|
|
|
21
31
|
|
|
22
32
|
> **发布形态**：本包在本仓以**源码直出**方式发布——`main` 指向 `src`，由消费方打包器编译
|
|
23
33
|
> TypeScript 与 `.less` 样式；`@hzab/list-render/src/*` 深路径同样可直接引用。随包发布的 `dist/` 仅用于
|
|
24
|
-
> 类型解析（`types` → `dist/index.d.ts
|
|
34
|
+
> 类型解析（`types` → `dist/index.d.ts`），不是运行时入口。消费方需要承担的编译责任见
|
|
35
|
+
> [消费方接入指南 §4](../../../docs/consumer-access.md#4-src-直出包消费方要承担的编译责任)。
|
|
25
36
|
|
|
26
37
|
# 组件
|
|
27
38
|
|
|
28
39
|
## Tips
|
|
29
40
|
|
|
30
|
-
- antd
|
|
31
|
-
- 相关文档可查看 docs
|
|
41
|
+
- antd 组件样式需要手动引入（本包只随包发布自己的 `.less`，不引入 antd 样式）
|
|
42
|
+
- 相关文档可查看 docs 中的文件，索引见 [docs/README.md](./docs/README.md)
|
|
43
|
+
- `model` 必须在组件内部（`useMemo` / `useDataModel`）创建，不要定义在组件外部，否则会出现「切换页面后上次搜索条件仍在」的 query 残留，详见 [常见问题 FAQ](#常见问题-faq)
|
|
32
44
|
|
|
33
45
|
## 示例
|
|
34
46
|
|
|
35
47
|
```jsx
|
|
36
|
-
import
|
|
48
|
+
import { useMemo } from "react";
|
|
49
|
+
import ListRender, { DataModel } from "@hzab/list-render";
|
|
37
50
|
|
|
38
51
|
const listDM = useMemo(
|
|
39
52
|
() =>
|
|
@@ -56,180 +69,216 @@ const listDM = useMemo(
|
|
|
56
69
|
[],
|
|
57
70
|
);
|
|
58
71
|
|
|
59
|
-
// testSchema 为 formily 生成的 schema json
|
|
72
|
+
// testSchema 为 formily 生成的 schema json（见上方 Schema JSON 配置工具）
|
|
60
73
|
<ListRender schema={testSchema} model={listDM} />;
|
|
61
74
|
```
|
|
62
75
|
|
|
63
76
|
## API
|
|
64
77
|
|
|
65
|
-
###
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
|
72
|
-
|
|
|
73
|
-
|
|
|
74
|
-
|
|
|
75
|
-
|
|
|
76
|
-
|
|
|
77
|
-
|
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
|
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
|
|
|
87
|
-
|
|
|
88
|
-
|
|
|
89
|
-
| tableConf | Object |
|
|
90
|
-
| tableProps | Object |
|
|
91
|
-
| cardConf | Object |
|
|
92
|
-
| cardProps | Object |
|
|
93
|
-
| fetchOnEdit | Boolean |
|
|
94
|
-
| fetchById | Boolean |
|
|
95
|
-
| modalMode | string |
|
|
96
|
-
| modalConf | Object |
|
|
97
|
-
| modalDetailProps | Object |
|
|
98
|
-
| modalFormProps | Object |
|
|
99
|
-
| modalProps | Object |
|
|
100
|
-
| schemaScope | Object |
|
|
101
|
-
| components | Object |
|
|
102
|
-
| detailComponents | Object |
|
|
103
|
-
| hasPagination | Boolean |
|
|
104
|
-
| paginationConf | Object |
|
|
105
|
-
| formInitialValues | Object |
|
|
106
|
-
| Slots | Object |
|
|
107
|
-
| getFieldListOpt | Object |
|
|
108
|
-
| onGetListEnd | Function |
|
|
109
|
-
| onCreateSuc | Function |
|
|
110
|
-
| onEditSuc | Function |
|
|
111
|
-
| onDelSuc | Function |
|
|
112
|
-
| onFormModalClose | Function |
|
|
113
|
-
| modalFormMount | Function |
|
|
114
|
-
| msgConf | Object |
|
|
115
|
-
| i18n | Object |
|
|
116
|
-
| queryFormInitialValues | Object |
|
|
117
|
-
| queryFormIsExtendModelQuery | Boolean |
|
|
118
|
-
| useFormData | boolean | 否 |
|
|
119
|
-
| editMode | modal/line/line-cell/cell | 否 | modal |
|
|
120
|
-
|
|
|
121
|
-
|
|
|
122
|
-
|
|
|
78
|
+
### ListRender Attributes
|
|
79
|
+
|
|
80
|
+
- 默认值均取自源码解构默认值；「必须」列的空白表示非必填。
|
|
81
|
+
- `hasEdit` / `hasDel` / `hasDetail` / `hasDelTips` 由 **tableConf**（表格布局）或 **cardConf**（卡片布局）读取，
|
|
82
|
+
见对应子表——作为顶层 props 传入不会生效。
|
|
83
|
+
|
|
84
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
85
|
+
| --------------------------- | ------------------------- | ---- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
86
|
+
| layout | string | 否 | default | 列表渲染类型：`default` 表格 / `card` 卡片栅格 |
|
|
87
|
+
| className | string | 否 | - | 外层 div className |
|
|
88
|
+
| idKey | string | 否 | id | 唯一值字段的 key（行 key、详情/编辑/删除请求入参都用它） |
|
|
89
|
+
| schema | Object | 是 | - | 字段描述文件，包含各个字段的信息（formily schema JSON） |
|
|
90
|
+
| model | Object | 是 | - | 数据模型，包含 CURD 接口信息，传入 DataModel 的实例 |
|
|
91
|
+
| isPatchUpdate | boolean | 否 | false | 编辑提交接口是否使用 patch 发起请求（走 model.patch / model.patchMap） |
|
|
92
|
+
| list | Array | 否 | - | 本地数据源；未提供 model.getList 时使用，并按 hasPagination 决定是否前端切片分页 |
|
|
93
|
+
| closeAutoRequest | Boolean | 否 | false | 是否关闭加载完毕后自动发起请求。true 时组件 didMount 不自动发起请求 |
|
|
94
|
+
| hasQuery | Boolean | 否 | true | 是否包含搜索、筛选框、搜索按钮等 |
|
|
95
|
+
| verticalHeader | Boolean | 否 | false | 搜索项和新增按钮是否处于不同的行等 |
|
|
96
|
+
| search | String | 否 | - | 传入空字符串时，不包含搜索框；传入非空字符串时，显示搜索框，同时传入的字符串作为搜索框的占位符（固定字段名为 `search`） |
|
|
97
|
+
| filters | Array | 否 | [] | 字符串数组，可以包含要筛选的字段 key 值（schema 中的 name），或者字符串 '$timerange'（时间范围筛选专用） |
|
|
98
|
+
| queryConf | Object | 否 | {} | 设置 query 参数的 key |
|
|
99
|
+
| createText | String/ReactNode | 否 | 新增 | 新增按钮文案（`i18n.createText` 优先于此值） |
|
|
100
|
+
| hasCreate | Boolean | 否 | true | 是否显示新增按钮 |
|
|
101
|
+
| hasAction | Boolean | 否 | true | 是否在表格的最右增加一个“操作”列（卡片布局为卡片头部操作区）；hasAction 为 true 时，tableConf/cardConf 的 hasEdit/hasDel/hasDetail 才会生效 |
|
|
102
|
+
| tableConf | Object | 否 | {} | Table 相关配置，见 [tableConf](#tableconf)（编辑/删除/详情按钮开关也在其中） |
|
|
103
|
+
| tableProps | Object | 否 | {} | 直接传给 Table 的 props，相关 API 可直接参考 antd table 组件（在内部配置之后展开，可覆盖内部值） |
|
|
104
|
+
| cardConf | Object | 否 | {} | Card 相关配置，见 [cardConf](#cardconf) |
|
|
105
|
+
| cardProps | Object | 否 | {} | 直接传给 cardRender 的 props，因内部渲染使用的是详情组件，相关 API 可直接参考 @hzab/schema-descriptions 组件 |
|
|
106
|
+
| fetchOnEdit | Boolean | 否 | true | 展示编辑弹框时，是否会调用一次详情接口进行回填；若为 false，则会使用表格列表接口返回的 row 数据进行回填 |
|
|
107
|
+
| fetchById | Boolean | 否 | true | 详情/编辑请求是否以 `id` 作为入参的 key；为 false 时改用 idKey 的值作为 key |
|
|
108
|
+
| modalMode | string | 否 | dialog | 新增/编辑表单、详情 展示模式： dialog drawer |
|
|
109
|
+
| modalConf | Object | 否 | {} | modal/Drawer 配置对象，见 [modalConf](#modalconf) |
|
|
110
|
+
| modalDetailProps | Object | 否 | {} | modal descriptions 配置对象（透传给 @hzab/schema-descriptions） |
|
|
111
|
+
| modalFormProps | Object | 否 | {} | modal/drawer fromRender 配置对象（透传给 @hzab/form-render） |
|
|
112
|
+
| modalProps | Object | 否 | {} | modal/drawer 配置对象（透传给 antd Modal/Drawer，如 maskClosable、getContainer） |
|
|
113
|
+
| schemaScope | Object | 否 | {} | formRender schemaScope props |
|
|
114
|
+
| components | Object | 否 | {} | formRender components props 自定义组件（查询、表格、表单共用） |
|
|
115
|
+
| detailComponents | Object | 否 | {} | descriptions components props 自定义组件（仅详情渲染） |
|
|
116
|
+
| hasPagination | Boolean | 否 | true | 是否显示分页 |
|
|
117
|
+
| paginationConf | Object | 否 | {} | 可自定义 Pagination props，进行 pagination 相关设置，见 [paginationConf](#paginationconf) |
|
|
118
|
+
| formInitialValues | Object | 否 | {} | 给新增、编辑对话框中的表单增加默认值 |
|
|
119
|
+
| Slots | Object | 否 | {} | 组件插槽，见 [Slots 插槽](#slots-插槽) |
|
|
120
|
+
| getFieldListOpt | Object | 否 | {} | getFieldList opt 参数，见 [getFieldListOpt](#getfieldlistopt) |
|
|
121
|
+
| onGetListEnd | Function | 否 | - | 请求列表成功返回的回调，参数为 `{ list, pagination }` |
|
|
122
|
+
| onCreateSuc | Function | 否 | - | 新增成功返回的回调 |
|
|
123
|
+
| onEditSuc | Function | 否 | - | 编辑成功返回的回调 |
|
|
124
|
+
| onDelSuc | Function | 否 | - | 删除成功返回的回调 |
|
|
125
|
+
| onFormModalClose | Function | 否 | - | 表单/详情弹窗关闭回调（旧名 `onFormDialogClose`，二者取其一） |
|
|
126
|
+
| modalFormMount | Function | 否 | - | 新增、编辑、详情弹窗 Form 渲染完成回调（旧名 `dialogFormMount`） |
|
|
127
|
+
| msgConf | Object | 否 | {} | 新增、编辑、删除、列表查询，详情查询的报错 msg 提示设置（传给 `message.error({ ...msgConf, content })`） |
|
|
128
|
+
| i18n | Object | 否 | {} | 文案配置，见 [i18n](#i18n) |
|
|
129
|
+
| queryFormInitialValues | Object | 否 | {} | 列表上方查询 Form 默认值 |
|
|
130
|
+
| queryFormIsExtendModelQuery | Boolean | 否 | false | 列表上方查询 Form 默认值是否继承 model.query |
|
|
131
|
+
| useFormData | boolean | 否 | - | 是否使用 form data 提交数据（未传时回退 `dialogConf.useFormData` / `modalConf.useFormData`） |
|
|
132
|
+
| editMode | modal/line/line-cell/cell | 否 | modal | 编辑模式，见 [编辑模式 editMode](#编辑模式-editmode) |
|
|
133
|
+
| canEditCallback | Function | 否 | - | 行内编辑模式下按单元格判定是否可编辑：`(record, field, dataIndex) => boolean`，返回 false 时该单元格不可编辑 |
|
|
134
|
+
| cellEditTableProps | Object | 否 | {} | tableConf.isCellEditTable 为 true 时，透传给 @hzab/edit-table 的 CellEditTable |
|
|
135
|
+
| appendUrlQuery | boolean | 否 | false | 筛选条件改变时是否将参数（对象形式）设置到 url query 中（**仅 hash 路由生效**，见常见问题） |
|
|
136
|
+
| appendUrlQueryKey | string | 否 | URL_PARAM_NAME = "defaultSearchParams" | 自定义设置 url query 对象参数的 key |
|
|
137
|
+
| hasFilterTag | boolean | 否 | false | 是否在搜索区下方展示已选筛选条件 Tag，可单个关闭并自动重新查询 |
|
|
138
|
+
| onEditReqVerify | Function | 否 | - | 编辑态保存时额外的规则校验函数，返回 Promise 的 resolve 或 reject 用于继续执行或停止执行 |
|
|
123
139
|
|
|
124
140
|
- fetchOnEdit 展示编辑弹框时，是否会调用一次详情接口进行回填（某些场景下，列表接口只返回部分部分字段，只有详情接口会返回全部字段）；若为 false，则会使用表格列表接口返回的 row 数据进行回填
|
|
141
|
+
- 旧命名别名：`dialogConf` / `dialogFormProps` / `dialogProps` / `dialogDetailProps` / `dialogFormMount` / `onFormDialogClose`
|
|
142
|
+
与对应的 `modal*` 合并后生效，且 **`modal*` 优先**（如 `{ ...dialogFormProps, ...modalFormProps }`）。新代码请直接使用 `modal*`。
|
|
125
143
|
|
|
126
144
|
#### tableConf
|
|
127
145
|
|
|
128
|
-
| 属性名称
|
|
129
|
-
|
|
|
130
|
-
| colConf
|
|
131
|
-
| rowSelection
|
|
132
|
-
| scroll
|
|
133
|
-
| expandable
|
|
134
|
-
| onRow
|
|
135
|
-
|
|
|
136
|
-
|
|
|
137
|
-
|
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
146
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
147
|
+
| ----------------- | ---------------- | ---- | --------------- | -------------------------------------------------------------------------------------------------------- |
|
|
148
|
+
| colConf | Object | | {} | 指定各列的配置（比如列宽），key 为字段的 name。可以指定名为 “\_$actions”的字段来设置“操作”列，见下方子表 |
|
|
149
|
+
| rowSelection | Object | | {} | 选择功能的配置。参考 antd table rowSelection 参数 |
|
|
150
|
+
| scroll | Object | | {} | 表格是否可滚动，也可以指定滚动区域的宽、高。参考 antd table scroll 参数 |
|
|
151
|
+
| expandable | Object | | {} | 配置展开属性。参考 antd table expandable 参数 |
|
|
152
|
+
| onRow | Function | | {} | 设置行属性。参考 antd table onRow 参数 |
|
|
153
|
+
| hasEdit | Boolean/Function | | true | 是否显示「编辑」按钮；函数入参 `(record, index)`，返回 false 时该行不显示 |
|
|
154
|
+
| hasDel | Boolean/Function | | true | 是否显示「删除」按钮；函数同上 |
|
|
155
|
+
| hasDetail | Boolean/Function | | false | 是否显示「详情」按钮；函数同上（**默认不显示**，需要显式开启） |
|
|
156
|
+
| hasDelTips | String/Function | | "确认删除该项?" | 删除确认文案；函数入参 `(record, index)`，可返回该行的提示文案 |
|
|
157
|
+
| orderColType | string | | - | 序号列数据类型：page（按当前页的序号）、all（按所有页的序号） |
|
|
158
|
+
| orderColWidth | string/number | | - | 序号列 width 的参数 |
|
|
159
|
+
| tableEmptyValue | string/number | | undefined | table 列表空值展示数 |
|
|
160
|
+
| isTableSortXIdex | Boolean | | false | table 列表列排序是否按照 x-index 排序 |
|
|
161
|
+
| isShowTableFilter | Boolean | | false | 是否显示表格右上角「显示过滤项 / 显示列」设置 |
|
|
162
|
+
| isCellEditTable | Boolean | | false | 是否改用 @hzab/edit-table 的 CellEditTable 渲染表格（配套 cellEditTableProps） |
|
|
163
|
+
| dragColConf | Object | | undefined | 拖拽列的配置 |
|
|
164
|
+
| isDargTable | Boolean | | undefined | 是否开启表格拖拽排序（源码拼写如此） |
|
|
165
|
+
| dargEndBack | function | | undefined | 拖拽结束回调，参数为 `(newList, query)`（源码拼写如此） |
|
|
142
166
|
|
|
143
167
|
##### tableConf.colConf[xxx]
|
|
144
168
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
|
148
|
-
|
|
|
169
|
+
- `xxx` 为 schema 字段 name；`_$actions` 用于操作列（其 `width` 会作为操作列容器宽度）。
|
|
170
|
+
|
|
171
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
172
|
+
| --------------- | --------------- | ---- | --------- | ------------------------------------------------------------------------------------------- |
|
|
173
|
+
| title | string/Function | | - | 覆盖列标题（函数返回值作为标题） |
|
|
174
|
+
| width | string/number | | - | 当前列宽度 |
|
|
175
|
+
| ellipsis | boolean/Object | | - | 当前列是否超出隐藏，true 或 { showTitle: true } 开启超出隐藏 |
|
|
176
|
+
| emptyValue | string/number | | undefined | 该列空值展示（优先级：列配置 > schema 的 emptyValue > tableConf.tableEmptyValue） |
|
|
177
|
+
| showMode | string | | - | 用 @hzab/formily-result-utils 的 EnumRender 渲染，指定枚举展示模式 |
|
|
178
|
+
| showTags | boolean | | - | 便捷开关，等价于 `showMode=tags` |
|
|
179
|
+
| showPrefixNode | boolean | | - | 便捷开关，等价于 `showMode=prefixNode`（Switch 字段默认开启） |
|
|
180
|
+
| enumRenderProps | Object | | - | 传给 EnumRender 的额外 props |
|
|
181
|
+
| onCell | Function | | - | 自定义 onCell，入参会额外带上 `_field`（已合并最新 fieldSchema）；返回值与 antd onCell 一致 |
|
|
182
|
+
| 其他键 | - | | - | 其余键整体透传给 antd Table column，如 fixed、align、sorter |
|
|
149
183
|
|
|
150
184
|
#### cardConf
|
|
151
185
|
|
|
152
|
-
| 属性名称 | 属性类型
|
|
153
|
-
| -------------- |
|
|
154
|
-
| CardItemRender |
|
|
155
|
-
| columns | Number
|
|
186
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
187
|
+
| -------------- | ---------------- | ---- | --------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
188
|
+
| CardItemRender | React 组件 | | - | 自定义渲染卡片，入参 `{ item, index, functionProps }`，其中 functionProps 为 `{ onEdit, onDel, onSearch, getList }` |
|
|
189
|
+
| columns | Number | | 3 | 栅格列数（内部作为 CSS grid 的列数） |
|
|
190
|
+
| hasEdit | Boolean/Function | | true | 同 tableConf.hasEdit |
|
|
191
|
+
| hasDel | Boolean/Function | | true | 同 tableConf.hasDel |
|
|
192
|
+
| hasDetail | Boolean/Function | | false | 同 tableConf.hasDetail（**默认不显示**） |
|
|
193
|
+
| hasDelTips | String/Function | | "确认删除该项?" | 同 tableConf.hasDelTips |
|
|
194
|
+
| colConf | Object | | {} | 同 tableConf.colConf；卡片布局当前只读取 `_$actions` 的 width |
|
|
156
195
|
|
|
157
196
|
##### cardConf.colConf[xxx]
|
|
158
197
|
|
|
159
|
-
|
|
198
|
+
- 与上文 `tableConf.colConf[xxx]` 同构；卡片布局当前只用到 `_$actions` 的 `width`。
|
|
160
199
|
|
|
161
200
|
#### queryConf
|
|
162
201
|
|
|
163
|
-
| 属性名称 | 属性类型 | 必须 | 默认值
|
|
164
|
-
| ----------------- | ----------------------------------------- | ---- |
|
|
165
|
-
| hasReset | boolean | | false
|
|
166
|
-
| isSelectSearch | boolean | | true
|
|
167
|
-
| isRmDefault | boolean | | false
|
|
168
|
-
| isRmValidator | boolean | | false
|
|
169
|
-
| isChangeSubmit | boolean | | true
|
|
170
|
-
| isEnterSubmit | boolean | | true
|
|
171
|
-
| selectList | Array<string> | | ["Radio.Group", "Checkbox.Group"]
|
|
172
|
-
| inputList | Array<string> | | ["NumberPicker"]
|
|
173
|
-
| customSubmitList | Array<{component:string,event:string}> | |
|
|
174
|
-
| replaceComList | Array<{name:string,"x-component":string}> | |
|
|
175
|
-
| queryMap | Function | | -
|
|
176
|
-
| beforeQuerySearch | Function ｜ Promise\<boolean> | | -
|
|
177
|
-
|
|
178
|
-
#### modalConf
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
|
183
|
-
|
|
|
184
|
-
|
|
|
185
|
-
|
|
|
186
|
-
|
|
|
187
|
-
|
|
|
188
|
-
|
|
|
202
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
203
|
+
| ----------------- | ----------------------------------------- | ---- | ------ | ---------------------------------------------------------------------------------------------- |
|
|
204
|
+
| hasReset | boolean | | false | 是否有重置按钮 |
|
|
205
|
+
| isSelectSearch | boolean | | true | Select 是否支持搜索 |
|
|
206
|
+
| isRmDefault | boolean | | false | 是否去除默认值 |
|
|
207
|
+
| isRmValidator | boolean | | false | 是否去除校验 |
|
|
208
|
+
| isChangeSubmit | boolean | | true | 是否支持改变提交 |
|
|
209
|
+
| isEnterSubmit | boolean | | true | 是否支持回车提交 |
|
|
210
|
+
| selectList | Array<string> | | [] | **追加**到默认 `["Select", "Radio.Group", "Checkbox.Group"]` 的组件列表（命中则转换为 Select） |
|
|
211
|
+
| inputList | Array<string> | | [] | **追加**到默认 `["NumberPicker"]` 的组件列表（命中则转换为 Input） |
|
|
212
|
+
| customSubmitList | Array<{component:string,event:string}> | | | 自定义提交触发函数的列表 [{component: 'test', event: 'onTest'}] |
|
|
213
|
+
| replaceComList | Array<{name:string,"x-component":string}> | | | 通过 name 替换过滤项中组件 schema 对象逻辑。注意 name 必传，不传会把所有同类型 component 替换 |
|
|
214
|
+
| queryMap | Function | | - | query 数据提交前的处理函数 |
|
|
215
|
+
| beforeQuerySearch | Function ｜ Promise\<boolean> | | - | 点击搜索按钮前触发的函数 |
|
|
216
|
+
|
|
217
|
+
#### modalConf
|
|
218
|
+
|
|
219
|
+
- 作用于新增/编辑表单弹层（FormModal）与详情弹层（DetailModal）；与旧名 `dialogConf` 合并时 `modalConf` 优先。
|
|
220
|
+
|
|
221
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
222
|
+
| ------------ | -------------- | ---- | ------ | ----------------------------------------------------------------------------------------------- |
|
|
223
|
+
| width | number/string | 否 | 720 | 弹窗宽度 |
|
|
224
|
+
| okText | string | 否 | 确 定 | 弹窗底部确定按钮文案（详情弹层为「关 闭」） |
|
|
225
|
+
| cancelText | string | 否 | 取 消 | 弹窗底部取消按钮文案 |
|
|
226
|
+
| footer | Array/Function | 否 | - | 自定义弹窗底部按钮；函数入参 `{ cancel, onOk, close, formRef, validate, scenario, options }` |
|
|
227
|
+
| beforeSubmit | Function | 否 | - | 提交前的回调 `(formValues, { cancel, formRef, scenario })`，`return false` 表示拦截，不进行请求 |
|
|
228
|
+
| useFormData | boolean | 否 | - | 等价于顶层 useFormData（未传顶层时可在此配置） |
|
|
229
|
+
| title | Object | 否 | - | 配置弹窗标题，见下方 modalConf.title |
|
|
189
230
|
|
|
190
231
|
#### modalConf.title
|
|
191
232
|
|
|
192
233
|
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
193
234
|
| ---------- | -------- | ---- | ------ | ---------------------------------------------- |
|
|
194
|
-
| createText | string | 否 |
|
|
195
|
-
| createKey | string | 否 |
|
|
196
|
-
| editText | string | 否 |
|
|
197
|
-
| editKey | string | 否 |
|
|
198
|
-
| detailText | string | 否 |
|
|
199
|
-
| detailKey | string | 否 |
|
|
235
|
+
| createText | string | 否 | 新增 | 新增弹窗标题 |
|
|
236
|
+
| createKey | string | 否 | - | 新增弹窗标题 key,取自初始值 formInitialValues |
|
|
237
|
+
| editText | string | 否 | 编辑 | 编辑弹窗标题 |
|
|
238
|
+
| editKey | string | 否 | - | 编辑弹窗标题 key,取自当前选中行的 key 的对应值 |
|
|
239
|
+
| detailText | string | 否 | 详情 | 详情弹窗标题 |
|
|
240
|
+
| detailKey | string | 否 | - | 详情弹窗标题 key,取自当前选中行的 key 的对应值 |
|
|
200
241
|
|
|
201
242
|
#### model
|
|
202
243
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
244
|
+
- `model` 为 DataModel 实例（由 `@hzab/data-model` 提供，本包已 `export *` 再导出）；组件实际调用的方法为
|
|
245
|
+
`getList` / `get` / `create` / `update`（`isPatchUpdate` 时为 `patch`）/ `delete`。
|
|
246
|
+
- 全量参数见下文 [DataModel 属性 Props](#属性-props) 与 `@hzab/data-model` 的 README。
|
|
247
|
+
|
|
248
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
249
|
+
| -------- | -------- | ---- | ------ | -------------------------------------------- |
|
|
250
|
+
| query | Object | 否 | {} | get 请求参数（分页参数由组件内部维护并合并） |
|
|
206
251
|
|
|
207
252
|
#### i18n
|
|
208
253
|
|
|
209
|
-
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述
|
|
210
|
-
| ----------- | -------- | ---- | ------------- |
|
|
211
|
-
| createText | string | 否 | 新增 | 新增按钮文案
|
|
212
|
-
| tableEdit | string | 否 | 编辑 | 表格编辑按钮文案
|
|
213
|
-
| tableDel | string | 否 | 删除 | 表格删除按钮文案
|
|
214
|
-
|
|
|
254
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
255
|
+
| ----------- | -------- | ---- | ------------- | --------------------- |
|
|
256
|
+
| createText | string | 否 | 新增 | 新增按钮文案 |
|
|
257
|
+
| tableEdit | string | 否 | 编辑 | 表格编辑按钮文案 |
|
|
258
|
+
| tableDel | string | 否 | 删除 | 表格删除按钮文案 |
|
|
259
|
+
| tableDetail | string | 否 | 详情 | 表格/卡片详情按钮文案 |
|
|
260
|
+
| tableDelTip | string | 否 | 确认删除该项? | 表格删除提示文案 |
|
|
215
261
|
|
|
216
262
|
#### Slots 插槽
|
|
217
263
|
|
|
218
264
|
- 用于在指定位置添加所需的组件
|
|
219
265
|
|
|
220
|
-
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述
|
|
221
|
-
| ------------------ | -------- | ---- | ------ |
|
|
222
|
-
| headerActionPrefix | Function | 否 |
|
|
223
|
-
| headerActionSuffix | Function | 否 |
|
|
224
|
-
| HeaderOthersSuffix | Function | 否 |
|
|
225
|
-
| tableActionsSlot | Function | 否 |
|
|
226
|
-
| actionPrefixSlot | Function | 否 |
|
|
227
|
-
| actionCenterSlot | Function | 否 |
|
|
228
|
-
| actionSuffixSlot | Function | 否 |
|
|
229
|
-
| FormSlot | Function | 否 |
|
|
230
|
-
|
|
|
231
|
-
|
|
|
232
|
-
|
|
|
266
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
267
|
+
| ------------------ | -------- | ---- | ------ | --------------------------------------------------------------------------------------------------------------- |
|
|
268
|
+
| headerActionPrefix | Function | 否 | - | 新增按钮左侧插槽，入参 `{ onCreate, onSearch, getList, i18n }` |
|
|
269
|
+
| headerActionSuffix | Function | 否 | - | 新增按钮右侧插槽，入参同上 |
|
|
270
|
+
| HeaderOthersSuffix | Function | 否 | - | 表格和搜索项之间的插槽，入参 `{ onSearch, getList }` |
|
|
271
|
+
| tableActionsSlot | Function | 否 | - | 操作列插槽，会覆盖操作列，入参 `{ text, record, index, onEdit, onDel, onSearch, getList }`（卡片布局无 text） |
|
|
272
|
+
| actionPrefixSlot | Function | 否 | - | 操作列 详情按钮左侧插槽，入参同 tableActionsSlot |
|
|
273
|
+
| actionCenterSlot | Function | 否 | - | 操作列 编辑、删除按钮中间插槽，入参同上 |
|
|
274
|
+
| actionSuffixSlot | Function | 否 | - | 操作列 删除按钮右侧插槽，入参同上 |
|
|
275
|
+
| FormSlot | Function | 否 | - | 替换新增、编辑弹窗内的表单，入参 `{ ...ListRender props, formRef, scenario, schema }` |
|
|
276
|
+
| modalFooterPre | Function | 否 | - | 新增、编辑、详情弹窗按钮左侧插槽，入参 `{ options }` |
|
|
277
|
+
| modalFooterCenter | Function | 否 | - | 新增、编辑弹窗按钮中间插槽，入参 `{ options }`（详情弹层不渲染此插槽） |
|
|
278
|
+
| modalFooterSuffix | Function | 否 | - | 新增、编辑、详情弹窗按钮右侧插槽，入参 `{ options }` |
|
|
279
|
+
| [字段 name] | Function | 否 | - | 以 schema 字段 name 为 key 的插槽，用于自定义该列单元格渲染，入参 `{ text, record, index, field, fieldSchema }` |
|
|
280
|
+
|
|
281
|
+
- `options` 为弹层操作集合：表单弹层为 `{ cancel, onOk, close, formRef, validate, scenario }`，详情弹层为 `{ close, formRef, scenario }`。
|
|
233
282
|
|
|
234
283
|
```JSX
|
|
235
284
|
// Slots 按需添加
|
|
@@ -241,65 +290,105 @@ const Slots = {
|
|
|
241
290
|
const { text, record, index, onEdit, onDel } = props;
|
|
242
291
|
return (<div>actionPrefixSlot</div>)
|
|
243
292
|
},
|
|
244
|
-
|
|
293
|
+
modalFooterPre(props) {
|
|
245
294
|
const {
|
|
246
295
|
cancel,
|
|
247
296
|
onOk,
|
|
248
297
|
close,
|
|
249
|
-
|
|
298
|
+
formRef,
|
|
250
299
|
validate,
|
|
251
300
|
} = props?.options || {};
|
|
252
|
-
return (<div>
|
|
301
|
+
return (<div>modalFooterPre</div>)
|
|
253
302
|
}
|
|
254
303
|
};
|
|
255
304
|
|
|
256
305
|
<ListRender schema={schema} model={listDM} Slots={Slots} />
|
|
257
306
|
```
|
|
258
307
|
|
|
308
|
+
- 字段级插槽（key 为 schema 字段 name）用于自定义某列的单元格渲染：
|
|
309
|
+
|
|
310
|
+
```JSX
|
|
311
|
+
const Slots = {
|
|
312
|
+
// 字段 name 为 status 的列
|
|
313
|
+
status(props) {
|
|
314
|
+
const { text, record, index, field, fieldSchema } = props;
|
|
315
|
+
return <Tag>{text}</Tag>;
|
|
316
|
+
},
|
|
317
|
+
};
|
|
318
|
+
|
|
319
|
+
<ListRender schema={schema} model={listDM} Slots={Slots} />
|
|
320
|
+
```
|
|
321
|
+
|
|
259
322
|
#### dialogConf
|
|
260
323
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
|
265
|
-
|
|
|
266
|
-
|
|
|
267
|
-
|
|
|
324
|
+
- **旧命名**，与 [modalConf](#modalconf) 合并后生效（`{ ...props.dialogConf, ...modalConf }`，即 `modalConf` 优先）。
|
|
325
|
+
新代码请使用 `modalConf`；同名键的取值与默认值完全一致。
|
|
326
|
+
|
|
327
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
328
|
+
| ------------ | -------------- | ---- | ------ | --------------------------------------------------- |
|
|
329
|
+
| width | number/string | 否 | 720 | 弹窗宽度 |
|
|
330
|
+
| okText | string | 否 | 确 定 | 弹窗底部确定按钮文案 |
|
|
331
|
+
| cancelText | string | 否 | 取 消 | 弹窗底部取消按钮文案 |
|
|
332
|
+
| footer | Array/Function | 否 | - | 自定义弹窗底部按钮 |
|
|
333
|
+
| beforeSubmit | Function | 否 | - | 提交前的回调， return false; 表示拦截，不进行请求。 |
|
|
268
334
|
|
|
269
335
|
#### paginationConf
|
|
270
336
|
|
|
271
|
-
- 默认参数参考 antd pagination
|
|
337
|
+
- 默认参数参考 antd pagination 组件；其余键（如 showSizeChanger、showQuickJumper）会透传给 antd Pagination。
|
|
338
|
+
- `pageSizeOptions` 默认值随 `layout` 变化：`default` 为 `[10, 20, 50, 100]`，`card` 为 `[9, 18, 54, 99]`。
|
|
272
339
|
|
|
273
|
-
| 属性名称 | 属性类型 | 必须 | 默认值
|
|
274
|
-
| --------------- | -------- | ---- |
|
|
275
|
-
| pageSizeOptions | Array | 否 | [10, 20, 50, 100] | 可选 pageSize 数组
|
|
276
|
-
| isAllSelect | boolean | 否 | false
|
|
277
|
-
| isAllSelectKey | string | 否 | "isAllSelect"
|
|
340
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
341
|
+
| --------------- | -------- | ---- | ------------------------------------------------ | --------------------------------------------------------------------- |
|
|
342
|
+
| pageSizeOptions | Array | 否 | [10, 20, 50, 100]（card 布局为 [9, 18, 54, 99]） | 可选 pageSize 数组 |
|
|
343
|
+
| isAllSelect | boolean | 否 | false | 是否使用全部（会在 pageSizeOptions 末尾追加「全部」选项） |
|
|
344
|
+
| isAllSelectKey | string | 否 | "isAllSelect" | 选中全部时告知后端的字段名称，实际值为 true（同时 pageSize 不再发送） |
|
|
278
345
|
|
|
279
346
|
#### getFieldListOpt
|
|
280
347
|
|
|
281
|
-
| 属性名称
|
|
282
|
-
|
|
|
283
|
-
| boxList
|
|
348
|
+
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
349
|
+
| ----------- | ----------- | ---- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
350
|
+
| boxList | Array/false | 否 | [] | 表格列解析时**追加**到内置容器白名单 `["FormGrid", "FormGrid.GridColumn"]`，如 `"Card"`；传 `false` 关闭递归（FormGrid 内字段会被当成普通列） |
|
|
351
|
+
| schemaScope | Object | 否 | - | 由组件内部注入（无需手传），用于解析列 title 中的 `{{ }}` 表达式 |
|
|
284
352
|
|
|
285
353
|
### Table ref Methods
|
|
286
354
|
|
|
287
|
-
- 可使用 ref
|
|
288
|
-
|
|
289
|
-
| 函数名
|
|
290
|
-
|
|
|
291
|
-
| onSearch
|
|
292
|
-
| getList
|
|
293
|
-
|
|
|
294
|
-
|
|
|
295
|
-
|
|
|
296
|
-
|
|
|
297
|
-
|
|
|
298
|
-
|
|
|
355
|
+
- 可使用 ref 获取并触发执行；`onSearch` / `getList` / `onEdit` 均返回 Promise。
|
|
356
|
+
|
|
357
|
+
| 函数名 | 参数 | 说明 |
|
|
358
|
+
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------- |
|
|
359
|
+
| onSearch | (query, opt) | 重置页码至 1，并刷新列表 |
|
|
360
|
+
| getList | query | 获取当前页列表数据（query 会与查询表单缓存、分页参数合并） |
|
|
361
|
+
| onQueryFormSubmit | (query, isReset) | 查询表单提交回调；`isReset` 为 true 时清空 url query 中的查询参数 |
|
|
362
|
+
| forceUpdate | - | 强制重渲染列表，解决枚举数据渲染不正常的问题 |
|
|
363
|
+
| formModalRef | - | 新增、编辑 弹窗 form-modal 的 ref（含 show / close / cancel / onOk / formRef / validate） |
|
|
364
|
+
| formDialogRef | - | `formModalRef` 的别名 |
|
|
365
|
+
| queryRef | - | 筛选条件 query-render 的 ref（`queryRef.current.formRef.current.formRender` 为查询表单） |
|
|
366
|
+
| tableRef | - | 表格渲染实例，含 `onEditByTable`、`cellEditTableRef`、`columns` |
|
|
367
|
+
| onCreate | - | 手动触发新增按钮相关操作 |
|
|
368
|
+
| onEdit | row | 手动触发编辑按钮相关操作（fetchOnEdit 为 true 时先请求详情再回填/进入编辑态） |
|
|
369
|
+
| onDel | row | 手动触发删除按钮相关操作 |
|
|
299
370
|
|
|
300
371
|
- onSearch opt
|
|
301
|
-
- isSaveQuery 是否保存传入的 query
|
|
302
|
-
- isMergeQuery 是否合并上一次保存的 query
|
|
372
|
+
- isSaveQuery 是否保存传入的 query 值（默认 true）
|
|
373
|
+
- isMergeQuery 是否合并上一次保存的 query 值（默认 true）
|
|
374
|
+
|
|
375
|
+
### 编辑模式 editMode
|
|
376
|
+
|
|
377
|
+
- 由 `editMode` 控制，取值与行为如下（默认 `modal`）：
|
|
378
|
+
|
|
379
|
+
| 取值 | 编辑入口 | 保存操作 | 说明 |
|
|
380
|
+
| --------- | ---------------------------------- | ------------------------- | --------------------------------------------------------- |
|
|
381
|
+
| modal | 操作列「编辑」按钮 | 弹窗底部确定按钮 | 默认；弹窗/抽屉内编辑，`fetchOnEdit` 决定是否先拉详情回填 |
|
|
382
|
+
| line | 操作列「编辑」按钮 | 操作列变为「保存 / 取消」 | 整行进入编辑态，单元格内不显示确认图标 |
|
|
383
|
+
| line-cell | 单元格内的编辑图标（或双击单元格） | 单元格内「✓ / ✕」图标 | 单元格级编辑，操作列不再显示「编辑」按钮 |
|
|
384
|
+
| cell | 单元格内的编辑图标（或双击单元格） | 单元格内「✓ / ✕」图标 | 同一行可只编辑单个单元格（`editing` 精确到 dataIndex） |
|
|
385
|
+
|
|
386
|
+
- 行内编辑模式下（line / line-cell / cell）还可通过以下方式控制可编辑性：
|
|
387
|
+
- `tableConf.hasEdit`：整表编辑权限（Boolean 或 `(record, index) => boolean`）
|
|
388
|
+
- `canEditCallback`：单元格级判定 `(record, field, dataIndex) => boolean`
|
|
389
|
+
- schema 字段的 `x-pattern: disabled / readOnly`、`x-display: none`：该字段不可编辑
|
|
390
|
+
- 行内保存会走 `onEditSubmit`：`isPatchUpdate` 决定调用 `model.patch` 还是 `model.update`，
|
|
391
|
+
并先经过 `model.patchMap` / `model.updateMap`、`onEditReqVerify`（返回 reject 即中止）与 `useFormData` 处理。
|
|
303
392
|
|
|
304
393
|
# Schema
|
|
305
394
|
|
|
@@ -349,7 +438,7 @@ const Slots = {
|
|
|
349
438
|
#### 字段在表格中隐藏 inTable
|
|
350
439
|
|
|
351
440
|
- true: 在表格中展示（默认）
|
|
352
|
-
- false:
|
|
441
|
+
- false: 在表格中隐藏（卡片布局同样生效）
|
|
353
442
|
|
|
354
443
|
```JSON
|
|
355
444
|
{
|
|
@@ -425,25 +514,28 @@ const Slots = {
|
|
|
425
514
|
|
|
426
515
|
#### 响应器中可用的参数
|
|
427
516
|
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
|
432
|
-
|
|
|
433
|
-
|
|
|
434
|
-
| $
|
|
435
|
-
| $
|
|
436
|
-
| $
|
|
437
|
-
| $
|
|
438
|
-
| $
|
|
517
|
+
- 完整配置流程与场景示例见 [docs/effect.md](./docs/effect.md)；响应器写法本身参考
|
|
518
|
+
[formily Schema 内表达式作用域](https://react.formilyjs.org/api/shared/schema#%E5%86%85%E7%BD%AE%E8%A1%A8%E8%BE%BE%E5%BC%8F%E4%BD%9C%E7%94%A8%E5%9F%9F)。
|
|
519
|
+
|
|
520
|
+
| 参数名 | 说明 |
|
|
521
|
+
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
522
|
+
| scenario | 环境参数，当前环境：create（新增表单）、edit（编辑表单）、detail（详情）、query（查询表单）、table-render（表格列与卡片） |
|
|
523
|
+
| $self | 代表当前字段实例，可以在普通属性表达式中使用，也能在 x-reactions 中使用 |
|
|
524
|
+
| $form | 代表当前 Form 实例，可以在普通属性表达式中使用，也能在 x-reactions 中使用 |
|
|
525
|
+
| $deps | 只能在 x-reactions 中的表达式消费，与 x-reactions 定义的 dependencies 对应，数组顺序一致 |
|
|
526
|
+
| $values | 代表顶层表单数据，可以在普通属性表达式中使用，也能在 x-reactions 中使用 |
|
|
527
|
+
| $observable | 用于创建响应式对象，使用方式与 observable 一致 |
|
|
528
|
+
| $memo | 用于创建持久引用数据，使用方式与 autorun.memo 一致 |
|
|
529
|
+
| $effect | 用于响应 autorun 第一次执行的下一个微任务时机与响应 autorun 的 dispose，使用方式与 autorun.effect 一致 |
|
|
530
|
+
| $props | 用于对当前字段实例设置组件 props |
|
|
439
531
|
|
|
440
532
|
# DataModel
|
|
441
533
|
|
|
442
534
|
## Tips
|
|
443
535
|
|
|
444
|
-
- 若存在 axios
|
|
536
|
+
- 若存在 axios 相关配置失效的问题，请选择以下任意一种方式解决；
|
|
445
537
|
- 在入口文件设置 DataModel 默认的 axios 为已配置好的 axios；
|
|
446
|
-
- 在入口文件对
|
|
538
|
+
- 在入口文件对 DataModel 的 axios 进行配置;
|
|
447
539
|
|
|
448
540
|
```js
|
|
449
541
|
// 设置 DataModel 默认的 axios 为已配置好的 axios；
|
|
@@ -454,7 +546,7 @@ setDefaultAxios(axios);
|
|
|
454
546
|
```
|
|
455
547
|
|
|
456
548
|
```js
|
|
457
|
-
// 配置
|
|
549
|
+
// 配置 DataModel 的 axios;
|
|
458
550
|
import axios from "axios";
|
|
459
551
|
import { axios as ax } from "@hzab/list-render";
|
|
460
552
|
|
|
@@ -540,11 +632,11 @@ const dataModel = new DataModel({
|
|
|
540
632
|
timeout: 10000,
|
|
541
633
|
},
|
|
542
634
|
});
|
|
543
|
-
//
|
|
635
|
+
// 调用方式（方法名与 DataModel 一致）
|
|
544
636
|
async function test() {
|
|
545
637
|
const createRes = await dataModel.create();
|
|
546
638
|
const getRes = await dataModel.get();
|
|
547
|
-
const getListRes = await dataModel.
|
|
639
|
+
const getListRes = await dataModel.getList();
|
|
548
640
|
const updateRes = await dataModel.update();
|
|
549
641
|
const deleteRes = await dataModel.delete();
|
|
550
642
|
const multipleDeleteRes = await dataModel.multipleDelete();
|
|
@@ -553,18 +645,110 @@ async function test() {
|
|
|
553
645
|
|
|
554
646
|
### 属性 Props
|
|
555
647
|
|
|
648
|
+
- 下表为 `list-render` 用到的常用参数速查；**完整参数表**（各接口独立的 axiosConf、ReqMap/ResMap、
|
|
649
|
+
handleResponse、isResponse、isResponseData、useDataModel 等）见 `@hzab/data-model` 的 README。
|
|
650
|
+
|
|
556
651
|
| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 |
|
|
557
652
|
| ----------------- | -------- | ---- | ------ | ----------------------------------------------------------------------- |
|
|
558
|
-
| createApi | String | |
|
|
559
|
-
| createMap | Function | |
|
|
560
|
-
| getApi | String | |
|
|
561
|
-
| getMap | Function | |
|
|
562
|
-
| getListApi | String | |
|
|
563
|
-
| getListMap | Function | |
|
|
564
|
-
| getListFunc | Function | |
|
|
565
|
-
| updateApi | String | |
|
|
566
|
-
| updateMap | Function | |
|
|
567
|
-
|
|
|
568
|
-
|
|
|
569
|
-
|
|
|
570
|
-
|
|
|
653
|
+
| createApi | String | | - | 新增 post 请求的 api |
|
|
654
|
+
| createMap | Function | | - | post 请求提交前的处理函数 |
|
|
655
|
+
| getApi | String | | - | get 请求的 api |
|
|
656
|
+
| getMap | Function | | - | 处理 get 返回结果，处理完需要把结果返回 |
|
|
657
|
+
| getListApi | String | | - | getList 获取列表的 api，返回列表数据和 pagination 数据 |
|
|
658
|
+
| getListMap | Function | | - | getList 结果 map 的回调函数，参数为结果每一项数据，处理完需要把结果返回 |
|
|
659
|
+
| getListFunc | Function | | - | 可用于替代 getList 的函数，处理自定义数据，参数为 query |
|
|
660
|
+
| updateApi | String | | - | put 请求的 api |
|
|
661
|
+
| updateMap | Function | | - | put 请求提交前的处理函数 |
|
|
662
|
+
| patchApi | String | | - | patch 请求的 api（`isPatchUpdate` 为 true 时使用） |
|
|
663
|
+
| patchMap | Function | | - | patch 请求提交前的处理函数 |
|
|
664
|
+
| deleteApi | String | | - | delete 请求的 api |
|
|
665
|
+
| multipleDeleteApi | String | | - | 批量删除请求的 api，使用的 axios({ method: 'DELETE' }) 发请求 |
|
|
666
|
+
| query | Object | | - | get 请求的参数 |
|
|
667
|
+
| axiosConf | Object | | - | axios 的配置项 |
|
|
668
|
+
|
|
669
|
+
## 常见问题 FAQ
|
|
670
|
+
|
|
671
|
+
### 1. 为什么 `model` 必须定义在组件内部？
|
|
672
|
+
|
|
673
|
+
- 若把 `model` 定义在页面文件最外层（组件函数外部），设置搜索条件后切换到其他页面再切回来，
|
|
674
|
+
上次的搜索条件（`model.query`）仍然存在，列表会带着旧条件发起请求。
|
|
675
|
+
- 请在组件内用 `useMemo` 创建，或直接使用 `@hzab/data-model` 的 `useDataModel`：
|
|
676
|
+
|
|
677
|
+
```jsx
|
|
678
|
+
// ✅ 推荐：组件内创建
|
|
679
|
+
function Page() {
|
|
680
|
+
const listDM = useMemo(() => new DataModel({ getListApi: "/api/v1/userinfo" }), []);
|
|
681
|
+
return <ListRender schema={schema} model={listDM} />;
|
|
682
|
+
}
|
|
683
|
+
|
|
684
|
+
// ❌ 不推荐：定义在组件外部，切换页面后 query 残留
|
|
685
|
+
const listDM = new DataModel({ getListApi: "/api/v1/userinfo" });
|
|
686
|
+
```
|
|
687
|
+
|
|
688
|
+
### 2. 列表请求参数是怎么拼出来的？
|
|
689
|
+
|
|
690
|
+
- 合并顺序为 `{ ...查询表单缓存, ...传入的 query, ...分页参数 }`，后者覆盖前者；
|
|
691
|
+
即同名的分页键（pageNum / pageSize）始终以组件内部状态为准。
|
|
692
|
+
- `$timerange` 仅用于查询表单，提交前会被删除，并拆成 `beginTime` / `endTime` 两个字段。
|
|
693
|
+
|
|
694
|
+
### 3. 接口报错没有提示，或想改提示样式？
|
|
695
|
+
|
|
696
|
+
- 列表、详情、新增、编辑、删除的失败都会走 antd `message.error`，可用 `msgConf` 传 message 配置
|
|
697
|
+
（内部默认附加 `className: "list-render-err-message"`，可被 `msgConf.className` 覆盖）：
|
|
698
|
+
|
|
699
|
+
```jsx
|
|
700
|
+
<ListRender schema={schema} model={listDM} msgConf={{ duration: 5 }} />
|
|
701
|
+
```
|
|
702
|
+
|
|
703
|
+
### 4. 编辑弹窗里显示的是列表行的旧数据？
|
|
704
|
+
|
|
705
|
+
- 默认 `fetchOnEdit` 为 true：打开编辑弹窗会先请求详情接口回填；若列表接口已返回完整字段，
|
|
706
|
+
可传 `fetchOnEdit={false}` 直接用行数据回填。
|
|
707
|
+
- 详情请求的入参 key 默认为 `id`；后端要求用其他字段名时传 `fetchById={false}`，
|
|
708
|
+
此时改用 `idKey` 对应的值作为 key。
|
|
709
|
+
|
|
710
|
+
### 5. 刷新列表有哪些方式？
|
|
711
|
+
|
|
712
|
+
- `ref.current.onSearch(query)`：重置页码到 1 后请求（查询表单提交走的就是它）
|
|
713
|
+
- `ref.current.getList()`：按当前查询条件与页码请求
|
|
714
|
+
- `ref.current.forceUpdate()`：只重渲染已有数据，适合枚举/字典数据更新后刷新单元格展示
|
|
715
|
+
|
|
716
|
+
### 6. `hasEdit` / `hasDel` / `hasDetail` 传了没生效？
|
|
717
|
+
|
|
718
|
+
- 这四个开关由 `tableConf`（表格布局）或 `cardConf`（卡片布局）读取，**顶层传入不会生效**；
|
|
719
|
+
其中 `hasDetail` 默认不显示，需要显式开启：
|
|
720
|
+
|
|
721
|
+
```jsx
|
|
722
|
+
<ListRender
|
|
723
|
+
schema={schema}
|
|
724
|
+
model={listDM}
|
|
725
|
+
tableConf={{ hasDetail: true, hasEdit: (record) => record.status === 1 }}
|
|
726
|
+
/>
|
|
727
|
+
```
|
|
728
|
+
|
|
729
|
+
- 另外 `hasAction={false}` 会让整个操作列不渲染，此时上述开关都无意义。
|
|
730
|
+
|
|
731
|
+
### 7. `appendUrlQuery` 没有写入地址栏？
|
|
732
|
+
|
|
733
|
+
- 该能力基于 `window.location.hash` 实现（写入 `#/path?defaultSearchParams=<encodeURIComponent(JSON)>`），
|
|
734
|
+
**只在 hash 路由下生效**；history 路由不会写入。参数 key 可用 `appendUrlQueryKey` 自定义。
|
|
735
|
+
- 空值（空字符串 / 空数组 / null）不会写入；清空 Input、Select、DatePicker、DatePicker.RangePicker
|
|
736
|
+
时会从 url 中移除对应字段。
|
|
737
|
+
|
|
738
|
+
### 8. 卡片布局的分页选项为什么和其他布局不一样？
|
|
739
|
+
|
|
740
|
+
- `pageSizeOptions` 默认值随 `layout` 变化：`default` 为 `[10, 20, 50, 100]`，`card` 为 `[9, 18, 54, 99]`；
|
|
741
|
+
显式传 `paginationConf.pageSizeOptions` 可覆盖。
|
|
742
|
+
|
|
743
|
+
## 相关文档
|
|
744
|
+
|
|
745
|
+
| 文档 | 内容 |
|
|
746
|
+
| -------------------------------------------------- | ------------------------------------------------------------- |
|
|
747
|
+
| [docs/README.md](./docs/README.md) | 本包文档索引 |
|
|
748
|
+
| [docs/table.md](./docs/table.md) | 表格相关：筛选、顶部操作栏、手动请求、编辑模式、新增/编辑表单 |
|
|
749
|
+
| [docs/form-linkage.md](./docs/form-linkage.md) | 表单联动：表单项显隐、按其他字段改变数值与选项 |
|
|
750
|
+
| [docs/remote-data.md](./docs/remote-data.md) | 远程数据源：Select / TreeSelect 动态取数 |
|
|
751
|
+
| [docs/effect.md](./docs/effect.md) | 配置响应器：可用参数、属性响应与 `$effect` 场景 |
|
|
752
|
+
| [CHANGELOG.md](./CHANGELOG.md) | 版本变更记录 |
|
|
753
|
+
| [消费方接入指南](../../../docs/consumer-access.md) | 安装源、src 直出包的编译责任、peerDependencies |
|
|
754
|
+
| [源仓同步规则](../../../docs/source-sync.md) | 本包与源仓 `list-render-pc` 的同步规则 |
|