From 2e4a8137535e1bfebfdfdfaffffa0815622b9f87 Mon Sep 17 00:00:00 2001 From: liaoxuezhi Date: Thu, 26 Sep 2019 18:49:32 +0800 Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E8=B7=9F=E5=A4=9A=20api=20?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api.md | 10 +- docs/renderers/CRUD.md | 154 +++++++++++++++++++++++++++++- docs/renderers/Form/Checkboxes.md | 37 +++++++ docs/renderers/Form/Form.md | 59 +++++++++++- docs/renderers/Form/List.md | 37 +++++++ docs/renderers/Form/Radios.md | 37 +++++++ docs/renderers/Form/Select.md | 38 ++++++++ docs/renderers/Page.md | 16 +++- docs/renderers/Wizard.md | 51 ++++++++++ 9 files changed, 425 insertions(+), 14 deletions(-) diff --git a/docs/api.md b/docs/api.md index 7665f31e..956915d5 100644 --- a/docs/api.md +++ b/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#接口说明) \ No newline at end of file +* [Wizard](./renderers/Wizard.md#接口说明) + +`TBD` + diff --git a/docs/renderers/CRUD.md b/docs/renderers/CRUD.md index d36a3cb5..7e79ed0a 100644 --- a/docs/renderers/CRUD.md +++ b/docs/renderers/CRUD.md @@ -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` 数组格式，新的顺序，数组里面包含所有原始信息。 +* `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` 通过序号的方式告知更新了哪些成员。 +* `rows` `Array` 修改过的成员集合，数组对象是在原有数据的基础上更新后的结果。 +* `rowsDiff` `Array` 跟 `rows` 不一样的地方是这里只包含本次修改的数据。 +* `unModifiedItems` `Array` 其他没有修改的成员集合。 + +默认发送的数据有点多，不过可以通过api的数据映射自己选择需要的部分。 + + +**响应：** + +响应没有什么特殊要求，只关注 status 状态。 + + +#### quickSaveItemApi + +跟 quickSaveApi 不一样的地方在于当你配置快速保存为立即保存的时候，优先使用此接口。因为只会保存单条数据，所以发送格式会不一样，直接就是整个更新后的成员数据。 + +**发送：** + +`POST` payload 中就是更新后的成员数据。 + +**响应：** + +响应没有什么特殊要求，只关注 status 状态。 \ No newline at end of file diff --git a/docs/renderers/Form/Checkboxes.md b/docs/renderers/Form/Checkboxes.md index b3963672..ac7193f1 100644 --- a/docs/renderers/Form/Checkboxes.md +++ b/docs/renderers/Form/Checkboxes.md @@ -48,3 +48,40 @@ } ] ``` + + +### 接口说明 + +开始之前请你先阅读[整体要求](../api.md)。 + +#### source + +**发送** + +默认 GET，不携带数据，可从上下文中取数据设置进去。 + +**响应** + +格式要求如下： + +```json +{ + "status": 0, + "msg": "", + "data": { + "options": [ + { + "label": "描述", + "value": "值" + }, + + { + "label": "描述2", + "value": "值2" + } + ], + + "value": "值" // 默认值，可以获取列表的同时设置默认值。 + } +} +``` \ No newline at end of file diff --git a/docs/renderers/Form/Form.md b/docs/renderers/Form/Form.md index da08375c..5f785b52 100644 --- a/docs/renderers/Form/Form.md +++ b/docs/renderers/Form/Form.md @@ -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。 \ No newline at end of file diff --git a/docs/renderers/Form/List.md b/docs/renderers/Form/List.md index 8e79df8b..b589cc9a 100644 --- a/docs/renderers/Form/List.md +++ b/docs/renderers/Form/List.md @@ -125,3 +125,40 @@ } ] ``` + + +### 接口说明 + +开始之前请你先阅读[整体要求](../api.md)。 + +#### source + +**发送** + +默认 GET，不携带数据，可从上下文中取数据设置进去。 + +**响应** + +格式要求如下： + +```json +{ + "status": 0, + "msg": "", + "data": { + "options": [ + { + "label": "描述", + "value": "值" + }, + + { + "label": "描述2", + "value": "值2" + } + ], + + "value": "值" // 默认值，可以获取列表的同时设置默认值。 + } +} +``` \ No newline at end of file diff --git a/docs/renderers/Form/Radios.md b/docs/renderers/Form/Radios.md index 3374c94e..4d8f49ae 100644 --- a/docs/renderers/Form/Radios.md +++ b/docs/renderers/Form/Radios.md @@ -45,3 +45,40 @@ } ] ``` + + +### 接口说明 + +开始之前请你先阅读[整体要求](../api.md)。 + +#### source + +**发送** + +默认 GET，不携带数据，可从上下文中取数据设置进去。 + +**响应** + +格式要求如下： + +```json +{ + "status": 0, + "msg": "", + "data": { + "options": [ + { + "label": "描述", + "value": "值" + }, + + { + "label": "描述2", + "value": "值2" + } + ], + + "value": "值" // 默认值，可以获取列表的同时设置默认值。 + } +} +``` \ No newline at end of file diff --git a/docs/renderers/Form/Select.md b/docs/renderers/Form/Select.md index 375f9130..585fbcc8 100644 --- a/docs/renderers/Form/Select.md +++ b/docs/renderers/Form/Select.md @@ -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": "值" // 默认值，可以获取列表的同时设置默认值。 + } +} +``` \ No newline at end of file diff --git a/docs/renderers/Page.md b/docs/renderers/Page.md index d6c364a7..c81a9854 100644 --- a/docs/renderers/Page.md +++ b/docs/renderers/Page.md @@ -47,7 +47,21 @@ #### initApi -Page 渲染器可以配置 initApi 来拉取后端数据。格式要求：data 返回是对象即可。 +Page 渲染器可以配置 initApi 来拉取后端数据。 + +**发送：** + +默认不发送任何参数，如果有需要，在这可以取地址栏上的参数，假如地址栏携带了 id=1 这个参数, 那么接口这么配置就能把 id 作为 query 参数发送给后端。 + +```json +{ + "initApi": "/api/xxx?id=${id}" +} +``` + +**响应：** + +data 返回是对象即可。 ```json { diff --git a/docs/renderers/Wizard.md b/docs/renderers/Wizard.md index 90bd2646..6bcb7893 100644 --- a/docs/renderers/Wizard.md +++ b/docs/renderers/Wizard.md @@ -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。 \ No newline at end of file