amis
amis 使用(模板 + 数据)
1 index.html
1.1 amis.embed 渲染 json 为前端页面
当前使用的 amis SDK 方式
amis.embed()有4个参数
// 1、容器id
// 2、schema：即页面配置
// 3、props：初始值
// 4、可选的外部控制函数，其中包含了 theme：主题；当然还有其他的可选项1.2 左侧菜单
static/pages/site.json
visible 属性可以控制是否显示左侧菜单
2 Schema (页面配置)
{
"type": "page",
"title": "这是标题部分",
"subTitle": "这是子标题",
"remark": "这是小提示信息",
"aside": "这是侧边栏部分",
"body": "这是内容区",
"toolbar": "这是工具栏部分"
}2.1 容器类型
aside、body 和 toolbar这三个配置都是容器类型，容器类型即可以把其他渲染类型放进来。
容器内可以直接放一个渲染器，也可以放多个，用数组包起来即可如：
{
"type": "page",
"body": [
{
"type": "tpl",
"tpl": "<p>段落1</p>"
},
{
"type": "tpl",
"tpl": "<p>段落2</p>"
},
"<p>段落3</p>"
]
}3 数据域
{
"type": "page",
"body": "Hello ${text}"
}上面的配置要做的很简单：使用 Page 组件，在内容区内渲染一段模板文字，其中${text}是模板变量，它会去到当前组件的数据域中，获取text变量值。
3.1 通过接口初始化数据域
配置初始化接口 initApi：
{
"type": "page",
"initApi": "/amis/api/initData",
"body": "Hello ${text}"
}接口必须按照下面的格式返回：
{
"status": 0,
"msg": "",
"data": {
"text": "World!"
...其他字段
}
}3.2 显式配置 data 属性值
{
"data": {
"text": "World!",
"name": "amis"
},
"type": "page",
"body": "Hello ${text}, my name is ${name}."
}4 API
4.1 格式要求
AMIS 要求 API 返回的格式是 Json 格式。
4.1.1 推荐格式
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息 包括失败和成功
data: {
// ...
// 具体的数据
}
}status: 返回
0，表示当前接口正确返回，否则按错误请求处理；msg: 返回接口处理信息，主要用于表单提交或请求失败时的
toast显示；data: 必须返回一个具有
key-value结构的对象。
4.1.2 兼容格式
amis 支持直接返回数据的方式，无需返回 status 和将数据放在 data 字段中，比如下面的例子：
{
"username": "amis",
"email": "amis@amis.com"
}但这种方式无法显示错误信息，只能通过返回 http 状态码来标识错误。
4.2 自定义适配器
如 butterfly 返回的 {"stat": "OK", "data":{"list"[], "total":0}}
而 amis 需要 {"status": 0, msg:"OK", "data":{"items": [], "count":0}}
则可以通过如下适配器完成
"api": {
"method": "get",
"url": "/baice/source_list",
"adaptor": "if (payload.stat == 'OK') {return {status: 0, msg:'OK', data:{items: payload.data.list,count: payload.data.total}};} else {return {status: 1, msg:payload.stat, data:{items: [],count: 0}};};"
}4.3 API 配置--Form
4.3.1 api
当表单提交时，会把 Form 数据发送给指定 API，API 只需要返回状态信息（成功或失败）即可。如果返回了其他数据如 {id: 1}，返回的数据会被合并到 Form 数据中，可以用来做其他操作，比如跳转的新建数据的详情页面。
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息
data: {
// 可选
// 如果返回了，会被 Merge 到 Form 数据中。
}
}4.3.2 initApi
当表单初始化的时候，如果有设置 initApi, 则发起一个请求，并携带表单当前的数据。接口返回的值会被合并到表单数据中。
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息
data: {
// 表单初始数据
}
}4.3.3 asyncApi
正常情况下，表单提交时，把数据发送给 api，通过 api 返回的状态就能知道表单提交完成与否。但是有些情况下并不能知道，比如这个提交是一个异步过程，需要等待其他服务处理完后，才能算真正的完成。
针对这种情况，如果配置了 asyncApi, 表单提交不会马上结束，而是隔 3s（可配置） 轮询 asyncApi 接口，直到返回成功了才结束。
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息
data: {
finished: true
// 默认将判断 finished 这个返回值，但是可以在 form 中配置 finishedField: 'is_success' 改成判断其他字段。
// form 会不停的请求这个接口，直到 finished 返回为 true 才结束
}
}4.3.4 schemaApi
正常情况下，一个表单有哪些配置项都是固定的，万一如果不能固定，希望通过 API 来返回，则可以通过配置 schemaApi 来实现。
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息
data: {
// form schema 配置，会被合并到到现有 schema 配置中。
}
}4.4 API 配置--Wizard
Wizard 可用 API 跟 Form 差不多，同样可以设置 api 和 initApi。但是目前不支持 asyncApi 和 schemaApi。
关于 api 和 initApi 说明，请参考 Form 部分。
4.5 API 配置--CRUD
增删改查模型可用 API 说明。
4.5.1 api
获取列表 API，发送时会携带 url params、配置的 fitler 数据和分页数据。要求目标接口返回列表数据。
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息
data: {
rows: [
{}, // 用来展示每一项时需要的数据。
],
count: 10 // 用来展示一共有多少数据，同时能自动生成分页信息。
}
}4.5.2 quickSaveApi
CRUD 中，支持部分列快速编辑。当数据被修改后，默认会以数组的格式，把所有修改的行信息给出。
默认发送数据格式如下：（结构可调整，具体请参考 schema 配置。）
rows: [
{
id: 1 // 原始 list 数据中返回的数据。
key: value // 新修改的键值对。
}
]此接口只需要返回状态信息即可。返回 data 数据将被无视。
4.5.3 quickSaveItemApi
默认快速编辑都是批量保存，所以一般配置 quickSaveApi 即可。如果你想单个及时保存，则需要配置 quickSaveItemApi。
当单个保存时，传入参数不再是数组，而是修改的当前项数据。
4.5.4 saveOrderApi
当开启排序功能后，新的排序结果会通过 saveOrderApi 发送给后端。
比如我将 ID 为 3 的数据拖拽放到 ID 为 5 的数据后面，这次保存将会发送以下信息。
{
ids: '5,3,2,1...' // 新的 id 顺序。
insertAfter: { // 详细的插入位置
ID1: [ID2, ID3]
},
insertBefore: {
ID1: [ID2, ID3]
},
order: [ // 新的位置信息。weight 变量可配置。
{id: 5, weight: 1},
{id: 3, weight: 2},
...
],
rows: [// 新的顺序，在没有 id（primaryField） 字段的时候有用。
{...来自 list 接口}
]
}4.5.5 批量修改 API
CRUD 还支持批量修改，当选中多条数据进行变量修改时，发送的数据格式如下。
{
browser: 'Test 123', // 修改后的数据1.
foo: 'boom', // 修改后的数据2.
... // 根据批量修改的表单配置来。
ids: '1,2,3', // 如果有 primaryField 则，会把选中的数据 id 保存在 ids 中。
rows: [ // 当没有 primaryField 时候有用。
{/*选中的数据1*/},
{/*选中的数据1*/}
]
}4.6 API 配置--FormItem
4.6.1 Select
sourceSelect 支持动态获取 options，要求返回格式为。{ status: 0, // 0 表示成功，非0 表示失败 msg: '', // 提示信息 data: { options: [ { label: 'Option Name', // 选项说明 value: 'value', // 选项值 disabled: false // 是否可选。 }, ... ], value: 'value' // 同时可以指定默认值。 } }autoCompleteSelect 还支持根据用户输入自动自动搜索结果，并选中. 用户输入值请通过$term变量获取，返回格式要求如下。{ status: 0, // 0 表示成功，非0 表示失败 msg: '', // 提示信息 data: [ { label: 'Option Name', // 选项说明 value: 'value', // 选项值 disabled: false // 是否可选。 }, ... ] }
4.6.2 级联 Select (chained-select)
级联 Select，也是通过 source 接口拉取结果的，当前选中值请通过 $value 变量获取，多层值已用逗号隔开。要求返回格式如下。
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息
data: [
{
label: 'Option Name', // 选项说明
value: 'value', // 选项值
disabled: false // 是否可选。
},
...
]
}每次变动都会重新拉取一次，只要能拉到数组，就可以一直级联选择下去。
4.6.3 Tree
Tree 也支持动态拉取选项，跟 Select 格式一样，不过多了一层 children。
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息
data: {
options: [
{
label: 'Option Name', // 选项说明
value: 'value', // 选项值
disabled: false // 是否可选。
children: [
...options // 子 options
]
},
...
],
value: 'value' // 同时可以指定默认值。
}
}4.6.4 Matrix
矩阵类型的表单也是通过 source 动态拉取选项的，格式如下。
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息
data: {
columns: [
{
label: '列标题',
... // 其他任意值
},
...
],
rows: [
{
label: '行标题',
... // 其他任意值
},
...
]
value: [ // 可选，如果要指定，请按这个格式来。
{
checked: true,
...
},
{
checked: false,
...
},
] // 同时可以指定默认值。
}
}4.7 API 配置--Page
4.7.1 initApi
当页面初始化的时候，如果有设置 initApi, 则发起一个请求。接口返回的值可用于整个页面。
{
status: 0, // 0 表示成功，非0 表示失败
msg: '', // 提示信息
data: {
// 表单初始数据
}
}5 接口调试信息
request请求信息，包含请求类型，地址，以及参数。responseAPI 的实际返回结果。
5.1 template/index.html
// 全局请求适配器。参考：官网 -> 快速开始 -> 控制 amis 的行为
requestAdaptor(api) {
api.headers["Authorization"] = "Bearer: " + Cookies.get('butterfly_token');
console.log("全局请求适配器", api);
return api;
},
// 全局响应适配器。参考：官网 -> 快速开始 -> 控制 amis 的行为
responseAdaptor(api, payload, query, request, response) {
console.log("全局响应适配器", response);
if (response.status == 401) {
window.location.href = "/auth/ssologin";
return {
status: 401,
msg: "请登录"
}
}
return payload;
}5.2 page json
...
"api": {
"method": "get",
"url": "/ruqi/job_history_list",
"adaptor": "if (payload.stat == 'OK') {return {status: 0, msg:'OK', data:{items: payload.data.list,count: payload.data.total}};} else {return {status: 1, msg:payload.stat, data:{items: [],count: 0}};};"
},
"pageField": "page_index",
"perPageField": "page_size",
...5.3 console log
5.3.1 requestAdaptor
api
{
"headers": {"Authorization": "Bearer: xxx"}
"pageField": "page_index",
"perPageField": "page_size",
"method": "get",
"url": "/ruqi/job_history_list?page_index=1&job_id=%2Fqingnang%2Fsense_check&page_size=10",
""
}5.3.2 responseAdaptor
response
{
"data": {"stat": "OK", "data": {…}}, // butterfly 返回内容
"headers": {
"butterfly": "1.1.21.13",
"connection": "keep-alive",
"content-length": "3098",
"date": "Wed, 30 Apr 2025 08:42:22 GMT",
"job_history_list": "1.0.1",
"server": "nginx/1.16.1",
"x-cost": "0.721726",
"x-reqid": "6CCA9F4BC3BE1268_0"
}
"status": 200,
"statusText": "OK",
...
}payload
{"stat": "OK", "data": {…}}, // butterfly 返回内容6 最佳实践
6.1 某个操作完如何刷新页面
给响应的action上配置reload:'window'
{
type: 'action',
reload: 'window'
}6.2 crud 设置默认参数
{
"type“: “crud",
"defaultParams": {
"perPage": 20,
...xxx
}
}6.3 crud批量操作如何指定id
配置：primaryField: "xxx"，然后通过${ids}去取，ids默认格式为："id1,id2,id3"
6.4 接口超时时间
默认90秒，报错500，无法修改
6.5 sendOn使用说明和原理
原理是这样的， 比如接口1 返回一个 a 字段，这个 a 字段一开始是要没有值的。
接口2 的 url 上写上 '/api/xxxx?a=${a}' 然后配置 sendOn: 'this.a'
这样，接口2 在第一次尝试请求的时候，发现 this.a 不满足，所以不请求了，后续 接口数据回来了，会让 a 这个值发生变化， amis 会监控接口2 的 url ，发现接口2的运算结果变了，就会再次请求。
Last updated