amis

amis 使用(模板 + 数据)

1 index.html

1.1 amis.embed 渲染 json 为前端页面

amis - 低代码前端框架

当前使用的 amis SDK 方式

amis.embed()有4个参数
// 1、容器id
// 2、schema：即页面配置
// 3、props：初始值
// 4、可选的外部控制函数，其中包含了 theme：主题；当然还有其他的可选项

1.2 左侧菜单

static/pages/site.json

visible 属性可以控制是否显示左侧菜单

visible 属性 issue

2 Schema (页面配置)

{
  "type": "page",
  "title": "这是标题部分",
  "subTitle": "这是子标题",
  "remark": "这是小提示信息",
  "aside": "这是侧边栏部分",
  "body": "这是内容区",
  "toolbar": "这是工具栏部分"
}

Page是 amis 页面配置中 必须也是唯一的顶级节点

2.1 容器类型

aside、body 和 toolbar这三个配置都是容器类型，容器类型即可以把其他渲染类型放进来。

上面例子字符串类型内部是把他当成了 tpl 渲染器来处理

{
  "type": "page",
  "body": "这是内容区"
}

等同于:

{
  "type": "page",
  "body": {
    "type": "tpl",
    "tpl": "这是内容区"
  }
}

容器内可以直接放一个渲染器，也可以放多个，用数组包起来即可如：

{
  "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!"
    ...其他字段
  }
}

注意:

1. 并不是所有组件都支持配置初始化接口来实现数据域初始化操作，对于那些不支持配置初始化接口的组件来说，一般会使用 Service 组件 来辅助实现数据域初始化；
2. status、msg 和 data 字段为接口返回的必要字段；

3. data必须返回一个具有key-value结构的对象

3.2 显式配置 data 属性值

{
  "data": {
    "text": "World!",
    "name": "amis"
  },
  "type": "page",
  "body": "Hello ${text}, my name is ${name}."
}

同时配置 初始化接口 和 data属性 时，数据域将会合并初始化接口返回的数据和data属性值

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": "[e-mail]"
}

但这种方式无法显示错误信息，只能通过返回 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

• source Select 支持动态获取 options，要求返回格式为。

  {
      status: 0,  // 0 表示成功，非0 表示失败
      msg: '',    // 提示信息
      data: {
          options: [
              {
                  label: 'Option Name', // 选项说明
                  value: 'value', // 选项值
                  disabled: false // 是否可选。
              },
              ...
          ],
          value: 'value' // 同时可以指定默认值。
      }
  }

• autoComplete Select 还支持根据用户输入自动自动搜索结果，并选中. 用户输入值请通过 $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 请求信息，包含请求类型，地址，以及参数。

• response API 的实际返回结果。

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的运算结果变了，就会再次请求。