补充跟多 api 说明文档
This commit is contained in:
liaoxuezhi
parent
3ed6d47698
commit
2e4a813753
10
docs/api.md
10
docs/api.md
|
|
@ -48,13 +48,13 @@ amis 渲染器的数据都来源于 api，有一定的格式要求。
|
|||
每个渲染的接口返回都有自己的格式要求，主要体现在 data 字段内部，具体请参考每个渲染的接口说明。
|
||||
|
||||
* [Page](./renderers/Page.md#接口说明)
|
||||
|
||||
`TBD`
|
||||
|
||||
* [CRUD](./renderers/CRUD.md#接口说明)
|
||||
* [Form](./renderers/Form.md#接口说明)
|
||||
* [Form](./renderers/Form/Form.md#接口说明)
|
||||
* [Select](./renderers/Form/Select.md#接口说明)
|
||||
* [Checkboxes](./renderers/Form/Checkboxes.md#接口说明)
|
||||
* [Radios](./renderers/Form/Radios.md#接口说明)
|
||||
* [List](./renderers/Form/List.md#接口说明)
|
||||
* [Wizard](./renderers/Wizard.md#接口说明)
|
||||
* [Wizard](./renderers/Wizard.md#接口说明)
|
||||
|
||||
`TBD`
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ CRUD 支持三种模式：`table`、`cards`、`list`，默认为 `table`。
|
|||
| mode | `string` | `"table"` | `"table" 、 "cards" 或者 "list"` |
|
||||
| title | `string` | `""` | 可设置成空，当设置成空时，没有标题栏 |
|
||||
| className | `string` | | 表格外层 Dom 的类名 |
|
||||
| api | [Api](./Types.md#Api) | | CRUD 用来获取列表数据的 api。 |
|
||||
| [api](#api) | [Api](./Types.md#Api) | | CRUD 用来获取列表数据的 api。 |
|
||||
| loadDataOnce | `boolean` | | 是否一次性加载所有数据（前端分页） |
|
||||
| source | `string` | | 数据映射接口返回某字段的值，不设置会默认把接口返回的`items`或者`rows`填充进`mode`区域 |
|
||||
| filter | [Form](./Form/Form.md) | | 设置过滤器，当该表单提交后，会把数据带给当前 `mode` 刷新列表。 |
|
||||
|
|
@ -24,9 +24,9 @@ CRUD 支持三种模式：`table`、`cards`、`list`，默认为 `table`。
|
|||
| syncLocation | `boolean` | `true` | 是否将过滤条件的参数同步到地址栏 |
|
||||
| draggable | `boolean` | `false` | 是否可通过拖拽排序 |
|
||||
| itemDraggableOn | `boolean` | | 用[表达式](./Types.md#表达式)来配置是否可拖拽排序 |
|
||||
| saveOrderApi | [Api](./Types.md#Api) | | 保存排序的 api。 |
|
||||
| quickSaveApi | [Api](./Types.md#Api) | | 快速编辑后用来批量保存的 API。 |
|
||||
| quickSaveItemApi | [Api](./Types.md#Api) | | 快速编辑配置成及时保存时使用的 API。 |
|
||||
| [saveOrderApi](#saveOrderApi) | [Api](./Types.md#Api) | | 保存排序的 api。 |
|
||||
| [quickSaveApi](#quickSaveApi) | [Api](./Types.md#Api) | | 快速编辑后用来批量保存的 API。 |
|
||||
| [quickSaveItemApi](#quickSaveItemApi) | [Api](./Types.md#Api) | | 快速编辑配置成及时保存时使用的 API。 |
|
||||
| bulkActions | Array Of [Action](./Action.md) | | 批量操作列表，配置后，表格可进行选中操作。 |
|
||||
| defaultChecked | `boolean` | `false` | 当可批量操作时，默认是否全部勾选。 |
|
||||
| messages | `Object` | | 覆盖消息提示，如果不指定，将采用 api 返回的 message |
|
||||
|
|
@ -48,3 +48,149 @@ CRUD 支持三种模式：`table`、`cards`、`list`，默认为 `table`。
|
|||
| labelTpl | `string` | | 单条描述模板，`keepItemSelectionOnPageChange`设置为`true`后会把所有已选择条目列出来，此选项可以用来定制条目展示文案。 |
|
||||
| headerToolbar | Array | `['bulkActions', 'pagination']` | 顶部工具栏配置 |
|
||||
| footerToolbar | Array | `['statistics', 'pagination']` | 顶部工具栏配置 |
|
||||
|
||||
|
||||
|
||||
### 接口说明
|
||||
|
||||
开始之前请你先阅读[整体要求](../api.md)。
|
||||
|
||||
#### api
|
||||
|
||||
用来返回列表数据。
|
||||
|
||||
|
||||
**发送：**
|
||||
|
||||
可能会包含以下信息。
|
||||
|
||||
* `page` 页码，从 `1` 开始, 表示当前请求第几页的信息。 字段名对应 `pageField` 如果配成这样 `{pageField: "pn"}` 发送的时候字段名会变成类似 `/api/xxx?pn=1`。
|
||||
* `perPage` 每页多少条数据，默认假定是 10. 如果想修改请配置 `defaultParams: {perPage: 20}`。 另外字段名对应 `perPageField` 的配置。
|
||||
* `orderBy` 用来告知以什么方式排序。字段名对应 `orderField`
|
||||
* `orderDir` 不是 `asc` 就是 `desc`。分别表示正序还是倒序。
|
||||
|
||||
另外如果 CRUD 配置了 Filter，即过滤器表单，表单里面的数据也会自动 merge 到这个请求里面。前提是：你没有干预接口参数。
|
||||
|
||||
什么意思？来个对比 `/api/xxxx` 和 `/api/xxxx?a=${a}`。第二个配置方式就是干预了，如果你配置接口的时候有明确指定要发送什么参数，那么 amis 则不再默认把所有你可能要的参数都发过去了。这个时候如果想要接收原来的那些参数，你需要进一步配置 api，把你需要的参数写上如：`/api/xxxx?a=${a}&page=${page}&perPage=${perPage}`
|
||||
|
||||
|
||||
**响应：**
|
||||
|
||||
常规返回格式如下：
|
||||
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 0,
|
||||
"msg": "",
|
||||
"data": {
|
||||
"items": [
|
||||
{ // 每个成员的数据。
|
||||
"id": 1,
|
||||
"xxx": "xxxx"
|
||||
}
|
||||
],
|
||||
|
||||
"total": 200 // 注意这里不是当前请求返回的 items 的长度，而是一共有多少条数据，用于生成分页，
|
||||
// 如果你不想要分页，把这个不返回就可以了。
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果无法知道数据总条数，只能知道是否有下一页，请返回如下格式，AMIS 会简单生成一个简单版本的分页控件。
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 0,
|
||||
"msg": "",
|
||||
"data": {
|
||||
"items": [
|
||||
{ // 每个成员的数据。
|
||||
"id": 1,
|
||||
"xxx": "xxxx"
|
||||
}
|
||||
],
|
||||
|
||||
"hasNext": true // 是否有下一页。
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果不需要分页，或者配置了 loadDataOnce 则可以忽略掉 `total` 和 `hasNext` 参数。
|
||||
|
||||
|
||||
#### saveOrderApi
|
||||
|
||||
用来保存新的顺序，配置了 draggable 后会通过这个接口保存结果。
|
||||
|
||||
**发送：**
|
||||
|
||||
发送方式默认为 `POST` 会包含以下信息。
|
||||
|
||||
* `ids` 字符串如： `2,3,1,4,5,6` 用 id 来记录新的顺序。 前提是你的列表接口返回了 id 字段。另外如果你的 primaryField 不是 `id`，则需要配置如： `primaryField: "order_id"`。注意：无论你配置成什么 primayField，这个字段名始终是 ids。
|
||||
* `rows` `Array<Item>` 数组格式，新的顺序，数组里面包含所有原始信息。
|
||||
* `insertAfter` 或者 `insertBefore` 这是 amis 生成的 diff 信息，对象格式，key 为目标成员的 primaryField 值，即 id，value 为数组，数组中存放成员 primaryField 值。如：
|
||||
|
||||
```json
|
||||
{
|
||||
"insertAfter": {
|
||||
"2": ["1", "3"],
|
||||
"6": ["4", "5"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
表示：成员 1 和成员 3 插入到了成员 2 的后面。成员 4 和 成员 5 插入到了 成员 6 的后面。
|
||||
|
||||
发送数据多了？amis 只能猜你可能需要什么格式化的数据，api 不是可以配置数据映射吗？你可以通过 data 指定只发送什么如：
|
||||
|
||||
```json
|
||||
{
|
||||
"saveOrderApi": {
|
||||
"url": "/api/xxxx",
|
||||
"data": {
|
||||
"ids": "${ids}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这样就只会发送 ids 了。
|
||||
|
||||
**响应：**
|
||||
|
||||
响应没有什么特殊要求，只关注 status 状态。data 中返回了数据也不会影响结果集。默认调用完保存顺序接口会自动再调用一次 api 接口用来刷新数据。
|
||||
|
||||
#### quickSaveApi
|
||||
|
||||
用来保存快速编辑结果，当 crud 的列配置快速保存时会调用进来。
|
||||
|
||||
**发送：**
|
||||
|
||||
发送方式默认为 `POST` 会包含以下信息。
|
||||
|
||||
* `ids` `String` 如： `"1,2"` 用来说明这次快速保存涉及了哪些成员。
|
||||
* `indexes` `Array<number>` 通过序号的方式告知更新了哪些成员。
|
||||
* `rows` `Array<Object>` 修改过的成员集合，数组对象是在原有数据的基础上更新后的结果。
|
||||
* `rowsDiff` `Array<Object>` 跟 `rows` 不一样的地方是这里只包含本次修改的数据。
|
||||
* `unModifiedItems` `Array<Object>` 其他没有修改的成员集合。
|
||||
|
||||
默认发送的数据有点多，不过可以通过api的数据映射自己选择需要的部分。
|
||||
|
||||
|
||||
**响应：**
|
||||
|
||||
响应没有什么特殊要求，只关注 status 状态。
|
||||
|
||||
|
||||
#### quickSaveItemApi
|
||||
|
||||
跟 quickSaveApi 不一样的地方在于当你配置快速保存为立即保存的时候，优先使用此接口。因为只会保存单条数据，所以发送格式会不一样，直接就是整个更新后的成员数据。
|
||||
|
||||
**发送：**
|
||||
|
||||
`POST` payload 中就是更新后的成员数据。
|
||||
|
||||
**响应：**
|
||||
|
||||
响应没有什么特殊要求，只关注 status 状态。
|
||||
|
|
@ -48,3 +48,40 @@
|
|||
}
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
### 接口说明
|
||||
|
||||
开始之前请你先阅读[整体要求](../api.md)。
|
||||
|
||||
#### source
|
||||
|
||||
**发送**
|
||||
|
||||
默认 GET，不携带数据，可从上下文中取数据设置进去。
|
||||
|
||||
**响应**
|
||||
|
||||
格式要求如下：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 0,
|
||||
"msg": "",
|
||||
"data": {
|
||||
"options": [
|
||||
{
|
||||
"label": "描述",
|
||||
"value": "值"
|
||||
},
|
||||
|
||||
{
|
||||
"label": "描述2",
|
||||
"value": "值2"
|
||||
}
|
||||
],
|
||||
|
||||
"value": "值" // 默认值，可以获取列表的同时设置默认值。
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -43,18 +43,18 @@
|
|||
| messages.saveSuccess | `string` | | 保存失败时提示 |
|
||||
| wrapWithPanel | `boolean` | `true` | 是否让 Form 用 panel 包起来，设置为 false 后，actions 将无效。 |
|
||||
| panelClassName | `boolean` | `true` | 是否让 Form 用 panel 包起来，设置为 false 后，actions 将无效。 |
|
||||
| api | [Api](../Types.md#api) | | Form 用来保存数据的 api。 |
|
||||
| initApi | [Api](../Types.md#api) | | Form 用来获取初始数据的 api。 |
|
||||
| [api](#api) | [Api](../Types.md#api) | | Form 用来保存数据的 api。 |
|
||||
| [initApi](#initApi) | [Api](../Types.md#api) | | Form 用来获取初始数据的 api。 |
|
||||
| interval | `number` | `3000` | 刷新时间(最低 3000) |
|
||||
| silentPolling | `boolean` | `false` | 配置刷新时是否显示加载动画 |
|
||||
| stopAutoRefreshWhen | `string` | `""` | 通过[表达式](./Types.md#表达式) 来配置停止刷新的条件 |
|
||||
| initAsyncApi | [Api](../Types.md#api) | | Form 用来获取初始数据的 api,与 initApi 不同的是，会一直轮训请求该接口，直到返回 finished 属性为 true 才 结束。 |
|
||||
| [initAsyncApi](#initAsyncApi) | [Api](../Types.md#api) | | Form 用来获取初始数据的 api,与 initApi 不同的是，会一直轮训请求该接口，直到返回 finished 属性为 true 才 结束。 |
|
||||
| initFetch | `boolean` | `true` | 设置了 initApi 或者 initAsyncApi 后，默认会开始就发请求，设置为 false 后就不会起始就请求接口 |
|
||||
| initFetchOn | `string` | | 用表达式来配置 |
|
||||
| initFinishedField | `string` | `finished` | 设置了 initAsyncApi 后，默认会从返回数据的 data.finished 来判断是否完成，也可以设置成其他的 xxx，就会从 data.xxx 中获取 |
|
||||
| initCheckInterval | `number` | `3000` | 设置了 initAsyncApi 以后，默认拉取的时间间隔 |
|
||||
| schemaApi | [Api](../Types.md#api) | | `已不支持`，请改用 controls 里面放置 Service 渲染器实现 |
|
||||
| asyncApi | [Api](../Types.md#api) | | 设置此属性后，表单提交发送保存接口后，还会继续轮训请求该接口，直到返回 `finished` 属性为 `true` 才 结束。 |
|
||||
| [asyncApi](#asyncApi) | [Api](../Types.md#api) | | 设置此属性后，表单提交发送保存接口后，还会继续轮训请求该接口，直到返回 `finished` 属性为 `true` 才 结束。 |
|
||||
| checkInterval | `number` | 3000 | 轮训请求的时间间隔，默认为 3 秒。设置 `asyncApi` 才有效 |
|
||||
| finishedField | `string` | `"finished"` | 如果决定结束的字段名不是 `finished` 请设置此属性，比如 `is_success` |
|
||||
| submitOnChange | `boolean` | `false` | 表单修改即提交 |
|
||||
|
|
@ -200,3 +200,54 @@
|
|||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### 接口说明
|
||||
|
||||
开始之前请你先阅读[整体要求](../api.md)。
|
||||
|
||||
#### initApi
|
||||
|
||||
可以用来初始化表单数据。
|
||||
|
||||
**发送**
|
||||
|
||||
默认不携带任何参数，可以在上下文中取变量设置进去。
|
||||
|
||||
**响应**
|
||||
|
||||
要求返回的数据 data 是对象，不要返回其他格式，且注意层级问题，data 中返回的数据正好跟 form 中的变量一一对应。
|
||||
|
||||
```
|
||||
{
|
||||
status: 0,
|
||||
msg: '',
|
||||
data: {
|
||||
a: '123'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果有个表单项的 name 配置成 a，initApi 返回后会自动填充 '123'。
|
||||
|
||||
#### api
|
||||
|
||||
用来保存表单结果。
|
||||
|
||||
**发送**
|
||||
|
||||
默认为 `POST` 方式，会将所有表单项整理成一个对象发送过过去。
|
||||
|
||||
**响应**
|
||||
|
||||
如果 返回了 data 对象，且是对象，会把结果 merge 到表单数据里面。
|
||||
|
||||
#### initAsyncApi
|
||||
|
||||
这个接口的作用在于解决接口耗时比较长导致超时问题的情况，当配置此接口后，初始化接口的时候先请求 initApi 如果 initApi 接口返回了 data.finished 为 true，则初始化完成。如果返回为 false 则之后每隔 3s 请求 initAsyncApi，直到接口返回了 data.finished 为 true 才结束。 用这种机制的话，业务 api 不需要完全等待操作完成才输出结果，而是直接检测状态，没完成也直接返回，后续还会发起请求检测。
|
||||
|
||||
格式要求就是 data 是对象，且 有 finished 这个字段。返回的其他字段会被 merge 到表单数据里面。
|
||||
|
||||
##### asyncApi
|
||||
|
||||
保存同样也可以采用异步模式，具体请参考 initAsyncApi。
|
||||
|
|
@ -125,3 +125,40 @@
|
|||
}
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
### 接口说明
|
||||
|
||||
开始之前请你先阅读[整体要求](../api.md)。
|
||||
|
||||
#### source
|
||||
|
||||
**发送**
|
||||
|
||||
默认 GET，不携带数据，可从上下文中取数据设置进去。
|
||||
|
||||
**响应**
|
||||
|
||||
格式要求如下：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 0,
|
||||
"msg": "",
|
||||
"data": {
|
||||
"options": [
|
||||
{
|
||||
"label": "描述",
|
||||
"value": "值"
|
||||
},
|
||||
|
||||
{
|
||||
"label": "描述2",
|
||||
"value": "值2"
|
||||
}
|
||||
],
|
||||
|
||||
"value": "值" // 默认值，可以获取列表的同时设置默认值。
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -45,3 +45,40 @@
|
|||
}
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
### 接口说明
|
||||
|
||||
开始之前请你先阅读[整体要求](../api.md)。
|
||||
|
||||
#### source
|
||||
|
||||
**发送**
|
||||
|
||||
默认 GET，不携带数据，可从上下文中取数据设置进去。
|
||||
|
||||
**响应**
|
||||
|
||||
格式要求如下：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 0,
|
||||
"msg": "",
|
||||
"data": {
|
||||
"options": [
|
||||
{
|
||||
"label": "描述",
|
||||
"value": "值"
|
||||
},
|
||||
|
||||
{
|
||||
"label": "描述2",
|
||||
"value": "值2"
|
||||
}
|
||||
],
|
||||
|
||||
"value": "值" // 默认值，可以获取列表的同时设置默认值。
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -6,6 +6,7 @@
|
|||
- `options` 选项配置，类型为数组，成员格式如下。
|
||||
- `label` 文字
|
||||
- `value` 值
|
||||
- `value` 设置默认值，如果想要默认选中某个，请设置默认值。
|
||||
- `source` Api 地址，如果选项不固定，可以通过配置 `source` 动态拉取。另外也可以用 `$xxxx` 来获取当前作用域中的变量。
|
||||
- `autoComplete` 跟 source 不同的是，每次用户输入都会去接口获取提示。
|
||||
- `multiple` 默认为 `false`, 设置成 `true` 表示可多选。
|
||||
|
|
@ -89,3 +90,40 @@
|
|||
}
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
### 接口说明
|
||||
|
||||
开始之前请你先阅读[整体要求](../api.md)。
|
||||
|
||||
#### source
|
||||
|
||||
**发送**
|
||||
|
||||
默认 GET，不携带数据，可从上下文中取数据设置进去。
|
||||
|
||||
**响应**
|
||||
|
||||
格式要求如下：
|
||||
|
||||
```json
|
||||
{
|
||||
"status": 0,
|
||||
"msg": "",
|
||||
"data": {
|
||||
"options": [
|
||||
{
|
||||
"label": "描述",
|
||||
"value": "值"
|
||||
},
|
||||
|
||||
{
|
||||
"label": "描述2",
|
||||
"value": "值2"
|
||||
}
|
||||
],
|
||||
|
||||
"value": "值" // 默认值，可以获取列表的同时设置默认值。
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -47,7 +47,21 @@
|
|||
|
||||
#### initApi
|
||||
|
||||
Page 渲染器可以配置 initApi 来拉取后端数据。格式要求：data 返回是对象即可。
|
||||
Page 渲染器可以配置 initApi 来拉取后端数据。
|
||||
|
||||
**发送：**
|
||||
|
||||
默认不发送任何参数，如果有需要，在这可以取地址栏上的参数，假如地址栏携带了 id=1 这个参数, 那么接口这么配置就能把 id 作为 query 参数发送给后端。
|
||||
|
||||
```json
|
||||
{
|
||||
"initApi": "/api/xxx?id=${id}"
|
||||
}
|
||||
```
|
||||
|
||||
**响应：**
|
||||
|
||||
data 返回是对象即可。
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
|
|||
|
|
@ -73,3 +73,54 @@
|
|||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 接口说明
|
||||
|
||||
开始之前请你先阅读[整体要求](../api.md)。
|
||||
|
||||
|
||||
#### initApi
|
||||
|
||||
可以用来初始化表单数据。
|
||||
|
||||
**发送**
|
||||
|
||||
默认不携带任何参数，可以在上下文中取变量设置进去。
|
||||
|
||||
**响应**
|
||||
|
||||
要求返回的数据 data 是对象，不要返回其他格式，且注意层级问题，data 中返回的数据正好跟 form 中的变量一一对应。
|
||||
|
||||
```
|
||||
{
|
||||
status: 0,
|
||||
msg: '',
|
||||
data: {
|
||||
a: '123'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果有个表单项的 name 配置成 a，initApi 返回后会自动填充 '123'。
|
||||
|
||||
#### api
|
||||
|
||||
用来保存表单结果。
|
||||
|
||||
**发送**
|
||||
|
||||
默认为 `POST` 方式，会将所有表单项整理成一个对象发送过过去。
|
||||
|
||||
**响应**
|
||||
|
||||
如果 返回了 data 对象，且是对象，会把结果 merge 到表单数据里面。
|
||||
|
||||
#### initAsyncApi
|
||||
|
||||
这个接口的作用在于解决接口耗时比较长导致超时问题的情况，当配置此接口后，初始化接口的时候先请求 initApi 如果 initApi 接口返回了 data.finished 为 true，则初始化完成。如果返回为 false 则之后每隔 3s 请求 initAsyncApi，直到接口返回了 data.finished 为 true 才结束。 用这种机制的话，业务 api 不需要完全等待操作完成才输出结果，而是直接检测状态，没完成也直接返回，后续还会发起请求检测。
|
||||
|
||||
格式要求就是 data 是对象，且 有 finished 这个字段。返回的其他字段会被 merge 到表单数据里面。
|
||||
|
||||
##### asyncApi
|
||||
|
||||
保存同样也可以采用异步模式，具体请参考 initAsyncApi。
|
||||
Loading…
Reference in New Issue