@chengkejie/form-page 1.0.1

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.
Files changed (78) hide show
  1. package/README.md +562 -0
  2. package/dist/cjs/FormPage.d.ts +26 -0
  3. package/dist/cjs/FormPage.d.ts.map +1 -0
  4. package/dist/cjs/FormPage.js +710 -0
  5. package/dist/cjs/assets/setting.svg +17 -0
  6. package/dist/cjs/components/CompanySelect/index.d.ts +7 -0
  7. package/dist/cjs/components/CompanySelect/index.d.ts.map +1 -0
  8. package/dist/cjs/components/CompanySelect/index.js +81 -0
  9. package/dist/cjs/components/CustomNode/index.d.ts +7 -0
  10. package/dist/cjs/components/CustomNode/index.d.ts.map +1 -0
  11. package/dist/cjs/components/CustomNode/index.js +13 -0
  12. package/dist/cjs/components/ExtraDatePicker/index.d.ts +8 -0
  13. package/dist/cjs/components/ExtraDatePicker/index.d.ts.map +1 -0
  14. package/dist/cjs/components/ExtraDatePicker/index.js +140 -0
  15. package/dist/cjs/components/ExtraDatePicker/index.module.scss +40 -0
  16. package/dist/cjs/components/Section/index.d.ts +7 -0
  17. package/dist/cjs/components/Section/index.d.ts.map +1 -0
  18. package/dist/cjs/components/Section/index.js +30 -0
  19. package/dist/cjs/components/SelectSearch/index.d.ts +7 -0
  20. package/dist/cjs/components/SelectSearch/index.d.ts.map +1 -0
  21. package/dist/cjs/components/SelectSearch/index.js +40 -0
  22. package/dist/cjs/components/SettingDialog/index.d.ts +12 -0
  23. package/dist/cjs/components/SettingDialog/index.d.ts.map +1 -0
  24. package/dist/cjs/components/SettingDialog/index.js +129 -0
  25. package/dist/cjs/components/SettingDialog/index.module.scss +67 -0
  26. package/dist/cjs/context.d.ts +34 -0
  27. package/dist/cjs/context.d.ts.map +1 -0
  28. package/dist/cjs/context.js +23 -0
  29. package/dist/cjs/index.d.ts +12 -0
  30. package/dist/cjs/index.d.ts.map +1 -0
  31. package/dist/cjs/index.js +71 -0
  32. package/dist/cjs/styles/index.module.scss +178 -0
  33. package/dist/cjs/tableKeyMap.d.ts +3 -0
  34. package/dist/cjs/tableKeyMap.d.ts.map +1 -0
  35. package/dist/cjs/tableKeyMap.js +13 -0
  36. package/dist/cjs/types.d.ts +197 -0
  37. package/dist/cjs/types.d.ts.map +1 -0
  38. package/dist/cjs/types.js +5 -0
  39. package/dist/cjs/typings.d.ts +14 -0
  40. package/dist/esm/FormPage.d.ts +26 -0
  41. package/dist/esm/FormPage.d.ts.map +1 -0
  42. package/dist/esm/FormPage.js +708 -0
  43. package/dist/esm/assets/setting.svg +17 -0
  44. package/dist/esm/components/CompanySelect/index.d.ts +7 -0
  45. package/dist/esm/components/CompanySelect/index.d.ts.map +1 -0
  46. package/dist/esm/components/CompanySelect/index.js +75 -0
  47. package/dist/esm/components/CustomNode/index.d.ts +7 -0
  48. package/dist/esm/components/CustomNode/index.d.ts.map +1 -0
  49. package/dist/esm/components/CustomNode/index.js +7 -0
  50. package/dist/esm/components/ExtraDatePicker/index.d.ts +8 -0
  51. package/dist/esm/components/ExtraDatePicker/index.d.ts.map +1 -0
  52. package/dist/esm/components/ExtraDatePicker/index.js +133 -0
  53. package/dist/esm/components/ExtraDatePicker/index.module.scss +40 -0
  54. package/dist/esm/components/Section/index.d.ts +7 -0
  55. package/dist/esm/components/Section/index.d.ts.map +1 -0
  56. package/dist/esm/components/Section/index.js +25 -0
  57. package/dist/esm/components/SelectSearch/index.d.ts +7 -0
  58. package/dist/esm/components/SelectSearch/index.d.ts.map +1 -0
  59. package/dist/esm/components/SelectSearch/index.js +34 -0
  60. package/dist/esm/components/SettingDialog/index.d.ts +12 -0
  61. package/dist/esm/components/SettingDialog/index.d.ts.map +1 -0
  62. package/dist/esm/components/SettingDialog/index.js +122 -0
  63. package/dist/esm/components/SettingDialog/index.module.scss +67 -0
  64. package/dist/esm/context.d.ts +34 -0
  65. package/dist/esm/context.d.ts.map +1 -0
  66. package/dist/esm/context.js +14 -0
  67. package/dist/esm/index.d.ts +12 -0
  68. package/dist/esm/index.d.ts.map +1 -0
  69. package/dist/esm/index.js +9 -0
  70. package/dist/esm/styles/index.module.scss +178 -0
  71. package/dist/esm/tableKeyMap.d.ts +3 -0
  72. package/dist/esm/tableKeyMap.d.ts.map +1 -0
  73. package/dist/esm/tableKeyMap.js +7 -0
  74. package/dist/esm/types.d.ts +197 -0
  75. package/dist/esm/types.d.ts.map +1 -0
  76. package/dist/esm/types.js +1 -0
  77. package/dist/esm/typings.d.ts +14 -0
  78. package/package.json +67 -0
package/README.md ADDED
@@ -0,0 +1,562 @@
1
+ # @linkcld/form-page
2
+
3
+ 可配置的 React **搜索表单 + 表格 + 分页** 一体化组件,基于 Fusion Design (`@alifd/next`) 和 `ahooks`。
4
+
5
+ > 本文档为完整 API 参考,供开发者和 AI 编码助手在调用本组件时查阅。所有 prop 名、类型、默认值均与源码 [`src/types.ts`](src/types.ts) / [`src/FormPage.tsx`](src/FormPage.tsx) 一致。
6
+
7
+ ---
8
+
9
+ ## 目录
10
+
11
+ - [安装](#安装)
12
+ - [快速开始](#快速开始)
13
+ - [FormPage Props](#formpage-props)
14
+ - [tableProps 表格配置](#tableprops-表格配置)
15
+ - [columns 列配置](#columns-列配置)
16
+ - [conditionProps 搜索条件配置](#conditionprops-搜索条件配置)
17
+ - [buttonProps 按钮配置](#buttonprops-按钮配置)
18
+ - [Ref 方法(FormPageRef)](#ref-方法formpageref)
19
+ - [FormPageProvider 外部服务注入](#formpageprovider-外部服务注入)
20
+ - [子组件(独立导出)](#子组件独立导出)
21
+ - [完整示例](#完整示例)
22
+ - [内部行为说明](#内部行为说明)
23
+ - [开发 / 发布](#开发--发布)
24
+
25
+ ---
26
+
27
+ ## 安装
28
+
29
+ ### 1. 配置 `.npmrc`
30
+
31
+ 在项目根目录创建或编辑 `.npmrc`:
32
+
33
+ ```
34
+ @linkcld:registry=https://gitlab.linkcld.com/api/v4/projects/2612/packages/npm/
35
+ //gitlab.linkcld.com/api/v4/projects/2612/packages/npm/:_authToken=<你的 Token>
36
+ ```
37
+
38
+ > Token 需要在 GitLab → Preferences → Access Tokens 中创建,勾选 `read_package_registry` 权限。
39
+ > 推荐使用 Deploy Token 代替个人 Token。
40
+
41
+ ### 2. 安装
42
+
43
+ ```bash
44
+ npm i @linkcld/form-page
45
+ ```
46
+
47
+ 并在入口处引入样式:
48
+
49
+ ```ts
50
+ import '@linkcld/form-page/dist/esm/styles/index.module.scss';
51
+ ```
52
+
53
+ ---
54
+
55
+ ## 快速开始
56
+
57
+ ```tsx
58
+ import { FormPage, FormPageProvider, FormPageRef } from '@linkcld/form-page';
59
+ import '@linkcld/form-page/dist/esm/styles/index.module.scss';
60
+
61
+ // 1) 查询接口:接收 (表单数据, 分页参数, 是否按钮触发),返回 { data, total }
62
+ async function fetchList(data: any, params: any) {
63
+ const res = await request('/api/list', { data: { ...data, ...params } });
64
+ return { data: res.list, total: res.total };
65
+ }
66
+
67
+ function App() {
68
+ const ref = useRef<FormPageRef>(null);
69
+
70
+ return (
71
+ // 2) 用 Provider 注入列设置持久化 / 公司选择等外部服务(可选)
72
+ <FormPageProvider
73
+ config={{
74
+ fetchTableKeys: async (tableId) => [],
75
+ onSaveTableKeys: async (params) => {},
76
+ }}
77
+ >
78
+ {/* 3) 配置条件、列、按钮 */}
79
+ <FormPage
80
+ ref={ref}
81
+ searchFn={fetchList}
82
+ conditionProps={[
83
+ { type: 'input', name: 'keyword', label: '关键词', col: 6 },
84
+ { type: 'select', name: 'status', label: '状态', col: 6, options: [{ label: '启用', value: 1 }] },
85
+ ]}
86
+ tableProps={{
87
+ tableId: 'demo-table',
88
+ primaryKey: 'id',
89
+ columns: [
90
+ { title: '名称', dataIndex: 'name', width: 200, ellipsis: true },
91
+ { title: '状态', dataIndex: 'status', width: 120, ellipsis: true, lock: 'left' },
92
+ ],
93
+ }}
94
+ buttonProps={{ buttons: ['submit', 'reset', 'export', 'setting'] }}
95
+ />
96
+ </FormPageProvider>
97
+ );
98
+ }
99
+ ```
100
+
101
+ ---
102
+
103
+ ## FormPage Props
104
+
105
+ | Prop | 类型 | 默认值 | 说明 |
106
+ |------|------|--------|------|
107
+ | `searchFn` | `(data, params, fromButton) => Promise<{ data: any[]; total: number }>` | `() => {}` | **查询接口**。`data`=表单字段值,`params`=分页参数,`fromButton`=是否由按钮触发(区分搜索/重置与翻页静默刷新) |
108
+ | `exportFn` | `(...args) => any` | `() => {}` | 导出接口,复用同一表单字段,点击「导出」按钮时触发 |
109
+ | `rowSelectionFn` | `((keys, records) => void) \| null` | `null` | 行选择回调;传 `null` 不启用行选择 |
110
+ | `tableProps` | [`TableConfigProps`](#tableprops-表格配置) | `{}` | 表格配置(含 `tableId` / `columns` / `primaryKey` 等) |
111
+ | `conditionProps` | [`ConditionItem[]`](#conditionprops-搜索条件配置) | `[]` | 搜索条件配置数组,每项的 `type` 决定渲染哪种控件 |
112
+ | `buttonProps` | [`ButtonConfigProps`](#buttonprops-按钮配置) | `{}` | 操作按钮区配置 |
113
+ | `extra` | `ReactNode` | — | 渲染在搜索条件下方、表格上方的额外自定义区域 |
114
+ | `showPagination` | `boolean` | `true` | 是否显示分页器 |
115
+ | `autoSearch` | `boolean` | `true` | 挂载后是否自动发起首次查询 |
116
+ | `onReset` | `() => void` | `() => {}` | 重置按钮触发的回调(在内部清空逻辑之外额外执行) |
117
+ | `onFieldChange` | `(name: string, value: any) => void` | `() => {}` | 任意表单字段值变化回调 |
118
+ | `pageSizeList` | `number[]` | `[10, 20, 50, 100]` | 分页条数可选项 |
119
+
120
+ > `searchFn` 返回值需符合 `ahooks` `useFusionTable` 约定:`{ data: 表格数据数组, total: 总条数 }`。
121
+
122
+ ---
123
+
124
+ ## tableProps 表格配置
125
+
126
+ `tableProps` 除了 `columns` 外,其余字段会透传给 Fusion 的 `Table.StickyLock`。
127
+
128
+ | 字段 | 类型 | 默认值 | 说明 |
129
+ |------|------|--------|------|
130
+ | `tableId` | `string` | `''` | 表格唯一标识,用作列设置(显示/隐藏、列宽)的持久化 key |
131
+ | `columns` | `any[]` | — | 列配置,见 [columns 列配置](#columns-列配置) |
132
+ | `primaryKey` | `string` | `'key'` | 行数据的唯一字段名(行选择 / key 复用) |
133
+ | `isTree` | `boolean` | `false` | 是否树形表格 |
134
+ | `isZebra` | `boolean` | `false` | 是否斑马纹 |
135
+ | `hasBorder` | `boolean` | `true` | 是否显示边框 |
136
+ | `defaultPageSize` | `number` | `10` | 默认每页条数 |
137
+ | `[key: string]` | `any` | — | 其它 Fusion `Table` props 透传(如 `sort`、`fixedHeader` 等) |
138
+
139
+ ---
140
+
141
+ ## columns 列配置
142
+
143
+ 每列 = Fusion `Table.Column` 的全部 props **+ 库扩展属性**。库会自动给每列加上 `asyncResizable: true`(异步可拖拽调宽),无需手动设置。
144
+
145
+ ### Fusion 常用 props
146
+
147
+ | 字段 | 类型 | 说明 |
148
+ |------|------|------|
149
+ | `dataIndex` | `string` | 对应的数据字段名(支持 `a.b` 取值) |
150
+ | `title` | `ReactNode` | 表头文本 |
151
+ | `width` | `number \| string` | 列宽。**锁列(`lock`)时必须为数值** |
152
+ | `lock` | `'left' \| 'right' \| true` | 锁列 |
153
+ | `cell` | `ReactNode \| ((value, index, record) => ReactNode)` | 自定义单元格渲染 |
154
+ | `sortable` | `boolean` | 是否可排序 |
155
+ | `align` | `'left' \| 'center' \| 'right'` | 单元格对齐 |
156
+
157
+ ### 库扩展属性 ⭐
158
+
159
+ | 字段 | 类型 | 说明 |
160
+ |------|------|------|
161
+ | `ellipsis` | `true` | **单元格省略号 + hover 气泡**。库自动把单元格内容包进 `Balloon`,触发器宽度取自本列 `width`(`width - 32`,32 为左右内边距)。锁列也不会断层。若同时配置了 `cell`,则包裹 `cell` 的输出。 |
162
+ | `balloon` | `ReactNode` | 表头标题旁追加的提示节点(如一个带说明的问号气泡) |
163
+ | `children` | `column[]` | 多级表头(渲染为 `Table.ColumnGroup`),递归支持 |
164
+
165
+ ### 列配置示例
166
+
167
+ ```tsx
168
+ columns={[
169
+ // 1) 基础列 + 省略号气泡(自动用 width=200)
170
+ { title: '名称', dataIndex: 'name', width: 200, ellipsis: true },
171
+
172
+ // 2) 锁列 + 省略号气泡(width 必填,库内部已用 width 处理,不会断层)
173
+ { title: '状态', dataIndex: 'status', width: 120, ellipsis: true, lock: 'left' },
174
+
175
+ // 3) 省略号气泡 + 自定义 cell:气泡内展示 cell 的返回值
176
+ {
177
+ title: '金额', dataIndex: 'amount', width: 140, ellipsis: true,
178
+ cell: (v) => `¥${v?.toLocaleString()}`,
179
+ },
180
+
181
+ // 4) 自定义 cell(不使用省略号气泡)
182
+ { title: '操作', dataIndex: 'op', cell: (v, i, record) => <a onClick={() => edit(record)}>编辑</a> },
183
+
184
+ // 5) 表头带提示气泡
185
+ { title: '转化率', dataIndex: 'rate', balloon: <Balloon trigger={<QuestionMark />}>转化率 = 成功数 / 总数</Balloon> },
186
+
187
+ // 6) 多级表头
188
+ {
189
+ title: '地址', children: [
190
+ { title: '省', dataIndex: 'province', width: 100 },
191
+ { title: '市', dataIndex: 'city', width: 100 },
192
+ ],
193
+ },
194
+ ]}
195
+ ```
196
+
197
+ > 注:`ellipsis` 旧用法 `cell: renderText(width)` 已由库内置;现在只需声明 `ellipsis: true`。
198
+
199
+ ---
200
+
201
+ ## conditionProps 搜索条件配置
202
+
203
+ 每个条件项由公共布局属性 + 各类型特有字段组成。条件项按 24 栅格在一行内自动换行。
204
+
205
+ ### 公共属性(BaseConditionItem)
206
+
207
+ | 字段 | 类型 | 必填 | 说明 |
208
+ |------|------|------|------|
209
+ | `col` | `number` | 是 | 占据的栅格列数(24 栅格制,如 `6`、`8`、`12`) |
210
+ | `label` | `string` | 否 | 表单项标签文本 |
211
+ | `textAlign` | `'left' \| 'center' \| 'right'` | 否 | 对齐方式,不传则按行内位置自动计算(行首 left / 中间 center / 行尾 right) |
212
+ | `wrapperCol` | `object` | 否 | `Form.Item` 的 `wrapperCol` |
213
+ | `labelCol` | `object` | 否 | `Form.Item` 的 `labelCol` |
214
+
215
+ ### 各类型(`type`)
216
+
217
+ | `type` | 渲染控件 | 特有字段 | `customProps` 类型 |
218
+ |--------|----------|----------|---------------------|
219
+ | `input` | `Input` | `name`, `options?` | `InputProps` |
220
+ | `select` | `Select` | `name`, `options?` | `SelectProps` |
221
+ | `treeSelect` | `TreeSelect` | `name`, `options?` | `TreeSelectProps` |
222
+ | `cascaderSelect` | `CascaderSelect` | `name`, `options?` | `CascaderSelectProps` |
223
+ | `datePicker` | `DatePicker` | `name`, `options?` | `DatePickerProps` |
224
+ | `monthPicker` | `DatePicker.MonthPicker` | `name`, `options?` | `MonthPickerProps` |
225
+ | `rangePicker` | 两个 `DatePicker` | `name: [start, end]`, `options: [.,.]`, `customProps?: [.,.]` | `DatePickerProps[]` |
226
+ | `section` | 两个 `Input`(区间) | `name: [a, b]`, `options: [.,.]`, `unit?: string`, `customProps?: [.,.]` | `InputProps[]` |
227
+ | `companySelect` | `Select`(公司选择) | `name`, `options?`, `hasDefault?` | `SelectProps` |
228
+ | `extraDatePicker` | `DatePicker`/`MonthPicker`/`TimePicker` + 快捷按钮 | `name: string[]`, `options: []`, `extra: {...}`, `customProps?: []` | `DatePickerProps[]` |
229
+ | `selectSearch` | `Select`(远程搜索) | `name`, `options?`, **`request: (keyword) => Promise<any[]>`** | `SelectProps` |
230
+ | `customNode` | 完全自定义 | **`node: (field) => ReactNode`** | — |
231
+ | `custom`(兜底) | 任意 | `type: string`, **`custom: ReactNode`** | — |
232
+
233
+ > `name` / `options` / `customProps` 通过 `field.init(name, options, customProps)` 绑定到 Fusion `Field`,`options` 即 Field 的初始化选项(如 `{ rules, initValue }`),`customProps` 直接透传给底层控件。
234
+
235
+ ### 类型常量
236
+
237
+ 可用 `FormPageData.Type` 引用类型字符串常量(注意 `cascaderSelect` 为小写):
238
+
239
+ ```ts
240
+ FormPageData.Type.Select // 'select'
241
+ FormPageData.Type.Input // 'input'
242
+ FormPageData.Type.TreeSelect // 'treeSelect'
243
+ FormPageData.Type.cascaderSelect // 'cascaderSelect'
244
+ FormPageData.Type.DatePicker // 'datePicker'
245
+ FormPageData.Type.MonthPicker // 'monthPicker'
246
+ FormPageData.Type.RangePicker // 'rangePicker'
247
+ FormPageData.Type.Section // 'section'
248
+ FormPageData.Type.CompanySelect // 'companySelect'
249
+ FormPageData.Type.ExtraDatePicker// 'extraDatePicker'
250
+ FormPageData.Type.SelectSearch // 'selectSearch'
251
+ FormPageData.Type.CustomNode // 'customNode'
252
+ ```
253
+
254
+ ### `extraDatePicker` 的 `extra` 结构
255
+
256
+ ```ts
257
+ extra: {
258
+ name: string; // 存储当前选中按钮索引的字段名
259
+ defaultBtn: number; // 默认选中的按钮索引
260
+ buttons: Array<{
261
+ name: string; // 按钮显示文本
262
+ date: any[]; // 该按钮对应的日期值,与外层 name 一一对应
263
+ datePickerType?: 'datePicker' | 'monthPicker' | 'timePicker';
264
+ props?: DatePickerProps | MonthPickerProps | TimePickerProps;
265
+ }>;
266
+ }
267
+ ```
268
+
269
+ ### `companySelect` / `selectSearch` 依赖说明
270
+
271
+ - `companySelect` 依赖 [`FormPageProvider`](#formpageprovider-外部服务注入) 注入的 `onSearchCompany` / `getCompanyInfo`;`hasDefault: true` 且当前用户非管理员时锁定为当前公司。
272
+ - `selectSearch` 通过自身的 `request(keyword)` 获取选项,自带防抖,无需 Provider。
273
+
274
+ ### 条件配置示例
275
+
276
+ ```tsx
277
+ conditionProps={[
278
+ { type: 'input', name: 'keyword', label: '关键词', col: 6 },
279
+ { type: 'select', name: 'status', label: '状态', col: 6,
280
+ options: { dataSource: [{ label: '启用', value: 1 }, { label: '停用', value: 0 }] } },
281
+
282
+ // 区间:两个 Input,字段名 minAge / maxAge
283
+ { type: 'section', name: ['minAge', 'maxAge'], label: '年龄', col: 8, unit: '岁',
284
+ options: [{}, {}] },
285
+
286
+ // 远程搜索
287
+ { type: 'selectSearch', name: 'userId', label: '用户', col: 6,
288
+ request: async (kw) => {
289
+ const list = await searchUser(kw);
290
+ return list.map(u => ({ label: u.name, value: u.id }));
291
+ } },
292
+
293
+ // 完全自定义
294
+ { type: 'customNode', label: '高级', col: 12,
295
+ node: (field) => <MyComplexControl value={field.getValue('x')} onChange={(v) => field.setValue('x', v)} /> },
296
+ ]}
297
+ ```
298
+
299
+ ---
300
+
301
+ ## buttonProps 按钮配置
302
+
303
+ ```ts
304
+ interface ButtonConfigProps {
305
+ /** @deprecated 不再生效;按钮列自动占据本行剩余宽度以紧贴最右侧 */
306
+ col?: number;
307
+ buttons: Array<'submit' | 'reset' | 'export' | 'setting' | ReactNode>;
308
+ }
309
+ ```
310
+
311
+ `buttons` 中的字符串映射到内置按钮,**未匹配的项直接作为 ReactNode 渲染**(可放自定义 JSX):
312
+
313
+ | 字符串 | 按钮 | 行为 |
314
+ |--------|------|------|
315
+ | `'submit'` | 搜索 | 标记为按钮触发并提交查询 |
316
+ | `'reset'` | 重置 | 清空表单 / 排序 / 选中行,触发 `onReset` |
317
+ | `'export'` | 导出 | 调用 `exportFn` |
318
+ | `'setting'` | 设置 | 打开列显示/隐藏设置弹窗(依赖 `tableId`) |
319
+
320
+ ```tsx
321
+ buttonProps={{
322
+ buttons: ['submit', 'reset', <Button key="custom" onClick={...}>自定义</Button>, 'setting'],
323
+ }}
324
+ ```
325
+
326
+ ---
327
+
328
+ ## Ref 方法(FormPageRef)
329
+
330
+ 通过 `ref` 获取命令式句柄:
331
+
332
+ ```tsx
333
+ const ref = useRef<FormPageRef>(null);
334
+ <FormPage ref={ref} ... />
335
+ ```
336
+
337
+ | 方法 | 签名 | 说明 |
338
+ |------|------|------|
339
+ | `submit` | `() => void` | 手动提交查询(不标记为按钮触发) |
340
+ | `reset` | `() => void` | 重置表单、排序、选中行 |
341
+ | `refresh` | `() => void` | 静默刷新当前页(如外部数据变更后调用) |
342
+ | `resetWidth` | `() => void` | 重置所有列宽为初始值 |
343
+ | `selectedRowKeysChange` | `(keys: any[], records?: any[]) => void` | 程序化修改选中行(需开启行选择) |
344
+ | `field` | Fusion `Field` 实例 | 直接读写表单值:`field.getValue(name)` / `field.setValue(name, v)` / `field.validate(...)` 等 |
345
+
346
+ ```tsx
347
+ ref.current?.submit();
348
+ ref.current?.reset();
349
+ ref.current?.refresh();
350
+ ref.current?.resetWidth();
351
+ ref.current?.field.getValue('keyword');
352
+ ref.current?.selectedRowKeysChange([1, 2]);
353
+ ```
354
+
355
+ ---
356
+
357
+ ## FormPageProvider 外部服务注入
358
+
359
+ 可选:用 `<FormPageProvider config={...}>` 包裹,注入列设置持久化与公司选择等外部服务。
360
+
361
+ ```ts
362
+ import { FormPageProvider, FormPageConfig } from '@linkcld/form-page';
363
+
364
+ const config: FormPageConfig = {
365
+ // 列设置(显示/隐藏)持久化
366
+ fetchTableKeys: async (tableId) => [...], // 读取已隐藏的列
367
+ onSaveTableKeys: async ({ tableId, value, name, tableName }) => {...}, // 保存隐藏列
368
+ getTableName: () => '当前表格名', // 设置弹窗用
369
+
370
+ // 公司选择
371
+ onSearchCompany: async (keyword) => [{ name, id }], // 按关键字搜公司
372
+ getCompanyInfo: () => ({ id, name, isManage }), // 当前公司/是否管理员
373
+ };
374
+ ```
375
+
376
+ | 字段 | 签名 | 用于 |
377
+ |------|------|------|
378
+ | `fetchTableKeys` | `(tableId) => Promise<Array<{ tableId, value }>>` | 列显示/隐藏持久化读取 |
379
+ | `onSaveTableKeys` | `(params: { tableId, value, name, tableName? }) => Promise<any>` | 列显示/隐藏持久化保存 |
380
+ | `getTableName` | `() => string` | `SettingDialog` 显示表格名 |
381
+ | `onSearchCompany` | `(keyword) => Promise<Array<{ name, id }>>` | `companySelect` 远程搜索 |
382
+ | `getCompanyInfo` | `() => { id, name, isManage }` | `companySelect` 默认公司 / 锁定判断 |
383
+
384
+ > 不使用「设置」弹窗或「公司选择」时,可省略对应字段,甚至完全不用 Provider。
385
+
386
+ ---
387
+
388
+ ## 子组件(独立导出)
389
+
390
+ 以下组件均从包入口导出(见 [src/index.tsx](src/index.tsx)),可在 condition 体系之外单独使用。
391
+
392
+ ### SettingDialog — 列定制弹窗
393
+
394
+ ```ts
395
+ interface SettingDialogProps {
396
+ onChange: (id: string) => void; // 保存成功后回调,入参为 tableId
397
+ id: string; // 表格 ID(tableId)
398
+ dataSource: any[]; // 列配置数组;弹窗用 title→label、dataIndex→value 生成勾选项
399
+ container?: HTMLElement | null; // 弹窗挂载容器
400
+ hiddenKeys: string[]; // 当前已隐藏列的 dataIndex 列表
401
+ onSave: (params: { value; tableId; name; tableName? }) => Promise<any>; // 保存回调
402
+ }
403
+ // ref 暴露:{ show: () => void } // 打开弹窗并初始化勾选
404
+ ```
405
+
406
+ - 渲染「定制列」`Dialog`,用 `Checkbox.Group` 列出所有列(由 `dataSource` 的 `title`/`dataIndex` 派生),勾选 = 显示。
407
+ - 点「确定」时把**未勾选**的列拼成 `value`(dataIndex 逗号拼接)和 `name`(title 逗号拼接),连同 `tableId`、`tableName`(取自 Provider 的 `getTableName`)调 `onSave`;成功后调 `onChange(id)`。
408
+
409
+ ```tsx
410
+ import { SettingDialog } from '@linkcld/form-page';
411
+ import { useRef } from 'react';
412
+
413
+ const ref = useRef<any>(null);
414
+ <SettingDialog
415
+ ref={ref}
416
+ id="my-table"
417
+ dataSource={columns} // 传完整列配置
418
+ hiddenKeys={hiddenDataIndexes} // 已隐藏列的 dataIndex
419
+ container={containerEl}
420
+ onSave={async (params) => { await api.saveTableKeys(params); }}
421
+ onChange={(id) => reloadHidden(id)}
422
+ />;
423
+ ref.current?.show(); // 打开弹窗
424
+ ```
425
+
426
+ ### 条件渲染组件(CompanySelect / ExtraDatePicker / SelectSearch / Section / CustomNode)
427
+
428
+ 这些是 [`conditionProps`](#conditionprops-搜索条件配置) 各类型对应的渲染组件,签名为 `{ field, data }`,其中 `data` 就是对应类型的条件条目。一般通过 condition 配置使用;单独使用时需自行传入 Fusion `field` 实例与条件条目:
429
+
430
+ | 组件 | `data` 类型 | 说明 |
431
+ |------|------------|------|
432
+ | `CompanySelect` | `CompanySelectCondition` | 公司搜索 Select,依赖 Provider 的 `onSearchCompany`/`getCompanyInfo` |
433
+ | `ExtraDatePicker` | `ExtraDatePickerCondition` | 带快捷按钮的 日期/月/时间 选择器 |
434
+ | `SelectSearch` | `SelectSearchCondition` | 远程搜索 Select,依赖 `data.request(keyword)` |
435
+ | `Section` | `SectionCondition` | 双 Input 区间,支持 `data.unit` |
436
+ | `CustomNode` | `CustomNodeCondition` | 渲染 `data.node(field)` |
437
+
438
+ ```tsx
439
+ import { Section } from '@linkcld/form-page';
440
+ import { Field } from '@alifd/next';
441
+
442
+ const field = Field.useField();
443
+ <Section
444
+ field={field}
445
+ data={{ type: 'section', name: ['min', 'max'], options: [{}, {}], col: 6, unit: '元' }}
446
+ />
447
+ ```
448
+
449
+ ---
450
+
451
+ ## 完整示例
452
+
453
+ ```tsx
454
+ import { useRef } from 'react';
455
+ import { FormPage, FormPageProvider, FormPageRef, FormPageData } from '@linkcld/form-page';
456
+ import '@linkcld/form-page/dist/esm/styles/index.module.scss';
457
+
458
+ const fetchList = async (data: any, params: any) => {
459
+ const res = await fetch(`/api/users?q=${data.keyword}&page=${params.current}&size=${params.pageSize}`).then(r => r.json());
460
+ return { data: res.list, total: res.total };
461
+ };
462
+
463
+ export default function Page() {
464
+ const ref = useRef<FormPageRef>(null);
465
+
466
+ return (
467
+ <FormPageProvider
468
+ config={{
469
+ fetchTableKeys: async () => [],
470
+ onSaveTableKeys: async () => {},
471
+ }}
472
+ >
473
+ <FormPage
474
+ ref={ref}
475
+ searchFn={fetchList}
476
+ autoSearch
477
+ rowSelectionFn={(keys) => console.log('selected', keys)}
478
+ conditionProps={[
479
+ { type: FormPageData.Type.Input, name: 'keyword', label: '关键词', col: 6 },
480
+ { type: FormPageData.Type.Select, name: 'status', label: '状态', col: 6,
481
+ options: { dataSource: [{ label: '启用', value: 1 }, { label: '停用', value: 0 }] } },
482
+ ]}
483
+ tableProps={{
484
+ tableId: 'user-table',
485
+ primaryKey: 'id',
486
+ defaultPageSize: 20,
487
+ columns: [
488
+ { title: 'ID', dataIndex: 'id', width: 80, lock: true },
489
+ { title: '姓名', dataIndex: 'name', width: 160, ellipsis: true },
490
+ { title: '邮箱', dataIndex: 'email', width: 220, ellipsis: true },
491
+ { title: '状态', dataIndex: 'statusText', width: 100, align: 'center' },
492
+ { title: '操作', dataIndex: 'op', cell: (v, i, r) => <a onClick={() => edit(r)}>编辑</a> },
493
+ ],
494
+ }}
495
+ buttonProps={{ buttons: ['submit', 'reset', 'export', 'setting'] }}
496
+ onReset={() => console.log('reset')}
497
+ />
498
+ </FormPageProvider>
499
+ );
500
+ }
501
+ ```
502
+
503
+ ---
504
+
505
+ ## 内部行为说明
506
+
507
+ 以下为组件内部固定、非 prop 可配的行为,调用方知晓即可:
508
+
509
+ - **调试钩子 `window.field`**:组件挂载后会把当前 Fusion `Field` 实例挂到 `window.field`([FormPage.tsx:191](src/FormPage.tsx#L191)),方便在浏览器控制台读取/调试表单值。**生产环境也会挂载**,介意可忽略该全局变量。
510
+ - **表格形态**:使用 `Table.StickyLock`(锁列吸附)+ `fixedHeader`;`maxBodyHeight` 按表格容器实测高度自动计算(减去表头高度,默认 44px)。非用户可配。
511
+ - **排序**:单列排序。内部维护 `sort` state,列上加 `sortable: true` 即参与排序;点击其它列会替换(而非叠加)当前排序。
512
+ - **分页器样式**:固定 `pageSizeSelector="dropdown"`、`useFloatLayout`、显示「共 X 条」。可由 `pageSizeList` 改选项、`showPagination={false}` 关闭。
513
+ - **列宽拖拽**:所有列自动设为 `asyncResizable`(可拖拽调宽),拖拽宽度保留在组件 state(300ms 防抖);`ref.resetWidth()` 重置为初始值。
514
+ - **列显示/隐藏**:`tableId` 对应的列中,`dataIndex` 命中 `tbKeys`(隐藏列表)即不渲染;持久化依赖 Provider 的 `fetchTableKeys`(读取)/`onSaveTableKeys`(保存)。
515
+ - **按钮列宽度**:操作按钮列自动占据本行剩余栅格宽度以紧贴最右侧;条件正好填满整行(24 栅格)时按钮独占一行。
516
+ - **条件对齐**:条件项 `textAlign` 未显式设置时,按行内位置自动取 行首 `left` / 中间 `center` / 行尾 `right`。
517
+
518
+ ---
519
+
520
+ ## 开发 / 发布
521
+
522
+ ```bash
523
+ # 安装依赖
524
+ npm i
525
+
526
+ # 开发模式(监听文件变化)
527
+ npm run dev
528
+
529
+ # 构建(输出 dist/esm、dist/cjs)
530
+ npm run build
531
+
532
+ # 代码检查
533
+ npm run lint
534
+ ```
535
+
536
+ ### 发布
537
+
538
+ 1. 需要 GitLab 项目 Developer 及以上权限
539
+ 2. 需要创建 Personal Access Token(勾选 `api` + `write_package_registry`)
540
+
541
+ ```bash
542
+ # 1. 创建 .npmrc(填入你的 Token)
543
+ echo "@linkcld:registry=https://gitlab.linkcld.com/api/v4/projects/2612/packages/npm/" > .npmrc
544
+ echo "//gitlab.linkcld.com/api/v4/projects/2612/packages/npm/:_authToken=你的token" >> .npmrc
545
+
546
+ # 2. 改 package.json 的 version 后发布(prepublishOnly 会自动构建)
547
+ npm publish
548
+ ```
549
+
550
+ ## 依赖
551
+
552
+ | 依赖 | 版本 |
553
+ |------|------|
554
+ | React | >=16.9.0 <19.0.0 |
555
+ | React DOM | >=16.9.0 <19.0.0 |
556
+ | @alifd/next | >=1.26.0 |
557
+ | moment | >=2.24.0 |
558
+ | ahooks | ^3.0.0 |
559
+
560
+ ## License
561
+
562
+ MIT
@@ -0,0 +1,26 @@
1
+ import React from 'react';
2
+ import type { ConditionItem, SelectCondition, InputCondition, TreeSelectCondition, CascaderSelectCondition, DatePickerCondition, MonthPickerCondition, RangePickerCondition, SectionCondition, CompanySelectCondition, ExtraDatePickerCondition, SelectSearchCondition, CustomNodeCondition, CustomCondition, TableConfigProps, ButtonConfigProps, FormPageProps, FormPageRef } from './types';
3
+ export type { FormPageProps, FormPageRef, ConditionItem, TableConfigProps, ButtonConfigProps, SelectCondition, InputCondition, TreeSelectCondition, CascaderSelectCondition, DatePickerCondition, MonthPickerCondition, RangePickerCondition, SectionCondition, CompanySelectCondition, ExtraDatePickerCondition, SelectSearchCondition, CustomNodeCondition, CustomCondition, };
4
+ declare const _default: React.ForwardRefExoticComponent<FormPageProps & React.RefAttributes<FormPageRef>>;
5
+ export default _default;
6
+ /**
7
+ * 条件类型的枚举常量,供外部使用时避免硬编码字符串
8
+ * 与 condition 映射表中的 key 一一对应
9
+ */
10
+ export declare const FormPageData: {
11
+ Type: {
12
+ Select: string;
13
+ Input: string;
14
+ TreeSelect: string;
15
+ DatePicker: string;
16
+ MonthPicker: string;
17
+ Section: string;
18
+ RangePicker: string;
19
+ CompanySelect: string;
20
+ ExtraDatePicker: string;
21
+ SelectSearch: string;
22
+ CustomNode: string;
23
+ cascaderSelect: string;
24
+ };
25
+ };
26
+ //# sourceMappingURL=FormPage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"FormPage.d.ts","sourceRoot":"","sources":["../src/FormPage.tsx"],"names":[],"mappings":"AAMA,OAAO,KAA2F,MAAM,OAAO,CAAC;AAWhH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACZ,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAC9E,eAAe,EAAE,cAAc,EAAE,mBAAmB,EAAE,uBAAuB,EAC7E,mBAAmB,EAAE,oBAAoB,EACzC,oBAAoB,EAAE,gBAAgB,EACtC,sBAAsB,EAAE,wBAAwB,EAAE,qBAAqB,EACvE,mBAAmB,EAAE,eAAe,GACrC,CAAC;;AAufF,wBAAoC;AAEpC;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;CAexB,CAAC"}