@jswork/antd-form-schema-crud 0.0.0-stage → 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.
- package/README.md +244 -2
- package/dist/index.cjs +1571 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.mts +265 -0
- package/dist/index.d.ts +267 -0
- package/dist/index.mjs +1523 -0
- package/dist/index.mjs.map +1 -0
- package/dist/style.css +1 -0
- package/llms.txt +110 -0
- package/package.json +65 -4
package/README.md
CHANGED
|
@@ -1,3 +1,245 @@
|
|
|
1
|
-
#
|
|
1
|
+
# antd-form-schema-crud
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> Ant Design schema-driven CRUD: `SchemaCrudForm` for one record, `SchemaCrudList` for a resource list.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```shell
|
|
8
|
+
pnpm add @jswork/antd-form-schema-crud
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick start
|
|
12
|
+
|
|
13
|
+
一行记录:`SchemaCrudForm` 负责创建、预览、编辑、删除。列表:`SchemaCrudList` 负责 `xx_index`、分页、列和行内动作。
|
|
14
|
+
|
|
15
|
+
```tsx
|
|
16
|
+
import { SchemaCrudForm, SchemaCrudList } from '@jswork/antd-form-schema-crud';
|
|
17
|
+
import '@jswork/antd-form-schema-crud/style.css';
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### 列表
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
<SchemaCrudList
|
|
24
|
+
resource="posts"
|
|
25
|
+
schema={postSchema}
|
|
26
|
+
title="文章"
|
|
27
|
+
presets={postListPresets}
|
|
28
|
+
onCreate={() => navigate('/posts/new')}
|
|
29
|
+
onEdit={(record) => navigate(`/posts/${record.id}/edit`)}
|
|
30
|
+
/>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
页码写回路由的最小写法:
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
const [searchParams, setSearchParams] = useSearchParams();
|
|
37
|
+
const page = Number(searchParams.get('page') ?? 1);
|
|
38
|
+
|
|
39
|
+
<SchemaCrudList
|
|
40
|
+
page={page}
|
|
41
|
+
onPageChange={(nextPage) => {
|
|
42
|
+
const next = new URLSearchParams(searchParams);
|
|
43
|
+
if (nextPage <= 1) next.delete('page');
|
|
44
|
+
else next.set('page', String(nextPage));
|
|
45
|
+
setSearchParams(next);
|
|
46
|
+
}}
|
|
47
|
+
/>
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
固定接口约定:
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
posts_index({ page, size, ...params }) // => { rows, total }
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
- `resource="posts"` 自动解析 `nx.$api.posts_index`;也可以传 `api.index`。
|
|
57
|
+
- `page`、`size` 由组件控制,`params` 里的同名字段会被覆盖。
|
|
58
|
+
- 默认响应是 `{ rows, total }`;外层 `data` 解包放在 API 适配层。
|
|
59
|
+
- 请求和响应字段名可在项目入口全局配置一次,默认仍是 `page / size / rows / total`。
|
|
60
|
+
- 服务端分页;`presets` 只配置列展示,不改变表单字段。
|
|
61
|
+
- 列表不依赖 React Router,跳转由 `onCreate / onEdit` 交给业务。
|
|
62
|
+
- `fields` 只筛选 schema 推导列;显式 `columns` 优先,`fields` 不传时展示全部字段。
|
|
63
|
+
- 行内只有编辑和删除,不提供查看按钮,也不响应整行点击。
|
|
64
|
+
- 行内删除默认开启,带 `Popconfirm`;删除当前页最后一条会自动回退一页。
|
|
65
|
+
- 需要刷新后保留页码时,把 `page` 受控传入,并用 `onPageChange` 写回路由;`onPageChange` 也会覆盖筛选重置和删除回退。
|
|
66
|
+
|
|
67
|
+
### 业务字段配置
|
|
68
|
+
|
|
69
|
+
列表字段和详情字段通常不同。每个业务用一个普通配置对象集中声明,不复制 schema:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
export const postPageConfig = {
|
|
73
|
+
resource: 'posts',
|
|
74
|
+
title: '文章',
|
|
75
|
+
schema: postSchema,
|
|
76
|
+
list: {
|
|
77
|
+
fields: ['title', 'subtitle', 'status'],
|
|
78
|
+
presets: postListPresets,
|
|
79
|
+
},
|
|
80
|
+
detail: {
|
|
81
|
+
fields: ['title', 'subtitle', 'status', 'is_sticky'],
|
|
82
|
+
},
|
|
83
|
+
};
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
页面消费同一份配置:
|
|
87
|
+
|
|
88
|
+
```tsx
|
|
89
|
+
<SchemaCrudList
|
|
90
|
+
resource={postPageConfig.resource}
|
|
91
|
+
schema={postPageConfig.schema}
|
|
92
|
+
title={postPageConfig.title}
|
|
93
|
+
fields={postPageConfig.list.fields}
|
|
94
|
+
presets={postPageConfig.list.presets}
|
|
95
|
+
/>
|
|
96
|
+
|
|
97
|
+
<SchemaCrudForm
|
|
98
|
+
resource={postPageConfig.resource}
|
|
99
|
+
schema={postPageConfig.schema}
|
|
100
|
+
id={id}
|
|
101
|
+
mode="view"
|
|
102
|
+
title={postPageConfig.title}
|
|
103
|
+
viewFields={postPageConfig.detail.fields}
|
|
104
|
+
/>
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
- `fields` 按数组顺序生成列表列,未知 key 和 schema `hidden` 字段会被忽略。
|
|
108
|
+
- `viewFields` 只在 `mode="view"` 生效;新建、编辑继续使用完整 schema。
|
|
109
|
+
- 详情字段、列表字段都来自同一份 schema;需要额外计算列时继续用显式 `columns`。
|
|
110
|
+
|
|
111
|
+
### 详情 / 新建 / 编辑
|
|
112
|
+
|
|
113
|
+
```tsx
|
|
114
|
+
<SchemaCrudForm
|
|
115
|
+
resource="posts"
|
|
116
|
+
schema={postSchema}
|
|
117
|
+
id={activeId}
|
|
118
|
+
title="文章"
|
|
119
|
+
onSuccess={(event) => {
|
|
120
|
+
if (event.action === 'create') setActiveId(event.result.id);
|
|
121
|
+
}}
|
|
122
|
+
onBack={() => setActiveId(undefined)}
|
|
123
|
+
/>
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
- `id` 为空进入创建,有值进入详情;不传 `mode` 时,详情里的“编辑”由组件内部切换。
|
|
127
|
+
- 表单默认横向布局,标签宽 `120px`;要改宽度传 `formProps.labelCol`。
|
|
128
|
+
- 详情可用 `viewFields` 筛选字段,组件内按声明顺序展示;新建和编辑不受影响。
|
|
129
|
+
- 新建、编辑支持 `Cmd+S`(macOS)/ `Ctrl+S`(Windows/Linux)保存,并拦截浏览器自带的保存网页;详情态不绑定快捷键。
|
|
130
|
+
- 快捷键与保存按钮共用同一套可保存条件:表单 ready、无请求进行中、编辑态有变更;校验不通过时不会发请求。
|
|
131
|
+
- 标题左侧有图标返回;底部是独立工具栏:删除、取消/返回与主操作统一靠右,删除排在最前。
|
|
132
|
+
- 创建默认值写在 `schema.initialValues`,提交前转换写在 `schema.normalizeValues`。
|
|
133
|
+
- 成功回调统一为 `onSuccess(event)`,按 `event.action` 区分 `create / update / delete`。
|
|
134
|
+
- 需要受控模式时传 `mode`,并通过 `onModeChange` 同步。
|
|
135
|
+
|
|
136
|
+
## Router 分页
|
|
137
|
+
|
|
138
|
+
`SchemaCrudList` 默认从路由查询参数读取并写回分页,不需要额外组件或子入口:
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
import { SchemaCrudList } from '@jswork/antd-form-schema-crud';
|
|
142
|
+
|
|
143
|
+
<SchemaCrudList
|
|
144
|
+
resource="posts"
|
|
145
|
+
schema={postSchema}
|
|
146
|
+
title="文章"
|
|
147
|
+
onCreate={() => navigate('/posts/new')}
|
|
148
|
+
onEdit={(record) => navigate(`/posts/${record.id}/edit`)}
|
|
149
|
+
/>
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
- 默认读写 `?page=1&size=10`,翻页和切换每页数量会自动更新 URL。
|
|
153
|
+
- URL 参数名跟随 `configureSchemaCrudList({ keys: { page, size } })` 的全局配置。
|
|
154
|
+
- 业务不再需要手写 `handlePageChange`,也不需要自己读取 `useSearchParams`。
|
|
155
|
+
- `keepDefaultParams` 默认 `true`,即使等于默认值也保留在 URL 中;传 `false` 时默认值会从 URL 移除。
|
|
156
|
+
- 需要额外处理时仍可传 `onPageChange`,它在 URL 更新后触发。
|
|
157
|
+
- 同时传 `page` 或 `pageSize` 视为受控分页,此时不读写 URL,回到纯组件状态。
|
|
158
|
+
- 不在 Router 上下文中时自动退回组件内部分页,单元测试和无路由页面仍可直接使用。
|
|
159
|
+
- 在 Router 上下文中,新建默认导航到 `${pathname}/add${search}`,编辑默认导航到 `${pathname}/${rowKey}/edit${search}`;传入 `onCreate` / `onEdit` 即完全覆盖。
|
|
160
|
+
- 删除成功默认提示“删除成功”,请求失败默认提示“操作失败,请重试。”;`onSuccess` / `onError` 可覆盖。
|
|
161
|
+
|
|
162
|
+
## Column presets
|
|
163
|
+
|
|
164
|
+
```ts
|
|
165
|
+
import type { ListPresets } from '@jswork/antd-form-schema-crud';
|
|
166
|
+
|
|
167
|
+
export const postListPresets: ListPresets = {
|
|
168
|
+
fields: {
|
|
169
|
+
title: { title: '标题', width: 240 },
|
|
170
|
+
status: { title: '状态', width: 100, align: 'center' },
|
|
171
|
+
},
|
|
172
|
+
};
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
也接受扁平写法 `{ title: '标题', status: '状态' }`。
|
|
176
|
+
|
|
177
|
+
- 列优先级:显式 `columns` > `presets` > `schema.fields.label` > 字段 `key`。
|
|
178
|
+
- `presets` 不创建列;schema 没有的字段不会多出一列。
|
|
179
|
+
- `hidden: true` 只隐藏列表里的推导列,表单字段不受影响。
|
|
180
|
+
- 操作列不受 `presets` 影响;复杂单元格继续用显式 `columns`。
|
|
181
|
+
|
|
182
|
+
## Shared UI defaults
|
|
183
|
+
|
|
184
|
+
表单卡片和列表卡片共用同一个 `cardSize`,默认 `middle`。需要调整时只配置一次:
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
import { configureSchemaCrud } from '@jswork/antd-form-schema-crud';
|
|
188
|
+
|
|
189
|
+
configureSchemaCrud({ cardSize: 'small' });
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`getSchemaCrudDefaults()` 返回当前共享默认值,`resetSchemaCrudDefaults()` 恢复默认。改成 `small` 后,标题栏、内边距和底部工具栏会一起收紧。
|
|
193
|
+
|
|
194
|
+
## Project defaults
|
|
195
|
+
|
|
196
|
+
`configureSchemaCrudForm` 只作用于 `SchemaCrudForm`,列表有独立的项目级配置。列表默认值:`pageSize=10`、`rowKey='id'`、`confirmDelete=true`、表格 `size='small'`。
|
|
197
|
+
|
|
198
|
+
```ts
|
|
199
|
+
import {
|
|
200
|
+
configureSchemaCrudForm,
|
|
201
|
+
getSchemaCrudFormDefaults,
|
|
202
|
+
resetSchemaCrudFormDefaults,
|
|
203
|
+
} from '@jswork/antd-form-schema-crud';
|
|
204
|
+
|
|
205
|
+
configureSchemaCrudForm({
|
|
206
|
+
title: '文章',
|
|
207
|
+
confirmDelete: false,
|
|
208
|
+
actions: { save: { text: '提交' }, delete: { text: '移除' } },
|
|
209
|
+
formProps: { layout: 'horizontal' },
|
|
210
|
+
});
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
- `actions` 和 `formProps` 会与实例 props 浅合并,实例优先。
|
|
214
|
+
- `getSchemaCrudFormDefaults()` 返回当前默认值的副本。
|
|
215
|
+
- `resetSchemaCrudFormDefaults()` 清空默认值,主要用于测试。
|
|
216
|
+
|
|
217
|
+
列表请求和响应 key 的项目级配置:
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
import {
|
|
221
|
+
configureSchemaCrudList,
|
|
222
|
+
getSchemaCrudListDefaults,
|
|
223
|
+
resetSchemaCrudListDefaults,
|
|
224
|
+
} from '@jswork/antd-form-schema-crud';
|
|
225
|
+
|
|
226
|
+
configureSchemaCrudList({
|
|
227
|
+
keys: {
|
|
228
|
+
page: 'pageNo',
|
|
229
|
+
size: 'pageSize',
|
|
230
|
+
rows: 'list',
|
|
231
|
+
total: 'count',
|
|
232
|
+
},
|
|
233
|
+
});
|
|
234
|
+
// GET: posts_index({ pageNo, pageSize, ...params })
|
|
235
|
+
// Response: { list, count }
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
只传需要改的 key;未传的继续使用默认值。`getSchemaCrudListDefaults()` 返回合并后的四个 key,`resetSchemaCrudListDefaults()` 恢复默认。
|
|
239
|
+
|
|
240
|
+
## Exports
|
|
241
|
+
|
|
242
|
+
- 组件:`SchemaCrudForm`、`AntdFormSchemaCrudForm`、`SchemaCrudList`
|
|
243
|
+
- 全局配置:`configureSchemaCrud`、`getSchemaCrudDefaults`、`resetSchemaCrudDefaults`、`configureSchemaCrudForm`、`getSchemaCrudFormDefaults`、`resetSchemaCrudFormDefaults`、`configureSchemaCrudList`、`getSchemaCrudListDefaults`、`resetSchemaCrudListDefaults`
|
|
244
|
+
- 工具:`resolveApi`、`checkRequirement`、`checkListRequirement`、`errorMessage`、`getNxApi`
|
|
245
|
+
- 类型:`SchemaCrudDefaults`、`SchemaCrudFormProps`、`SchemaCrudListProps`、`CrudApi`、`CrudListParams`、`CrudListResult`、`ListPresets`、`CrudSuccessEvent` 等
|