amis/docs/types/api.md
2020-07-28 10:03:53 +08:00

18 KiB
Executable File
Raw Blame History

title description type group menuName icon order
API 0 🔧 类型 API 20

API 类型用于配置请求接口的格式,涉及请求方式、请求地址、请求数据体等等相关配置

简单配置

如果你只需要配置简单的 ajax 接口,可以使用简单字符串格式,如下:

[<method>:]<url>
  • methodget、post、put、delete默认为get
  • url:接口地址,即模板字符串

示例:

{
  "api": "get:/api/initData",     // get 请求
  "api": "post:/api/initData",    // post 请求
  "api": "put:/api/initData",     // put 请求
  "api": "delete:/api/initData",  // delete 请求
}

接口返回格式(重要)

所有配置在 amis 组件中的接口,都要符合下面的返回格式

{
  "status": 0,
  "msg": "",
  "data": {
    ...其他字段
  }
}
  • status: 返回 0,表示当前接口正确返回,否则按错误请求处理;
  • msg: 返回接口处理信息,主要用于表单提交或请求失败时的 toast 显示;
  • data: 必须返回一个具有 key-value 结构的对象。

statusmsgdata 字段为接口返回的必要字段;

正确的格式

{
  "status": 0,
  "msg": "",
  "data": { // 正确
    "text": "World!"
  }
}

错误的格式

直接返回字符串或者数组都是不推荐的

{
  "status": 0,
  "msg": "",
  "data": "some string" // 错误,使用 key 包装
}

不推荐的格式

部分组件为了可以兼容,支持下面这种直接返回数组的用法,但并不推荐这种方式。

{
  "status": 0,
  "msg": "",
  "data": ["a", "b"] // 不推荐,使用 key 包装
}

复杂配置

API 还支持配置对象类型

基本用法

{
    "api": {
        "method": "get",
        "url": "xxxx",
        "data": {
            xxx
        },
        ... // 其他配置
    }
}

配置请求方式

可以配置method指定接口的请求方式,支持:getpostputdelete

method值留空时:

  • 在初始化接口中,默认为get请求
  • form提交接口,默认为post请求

配置请求地址

可以配置url指定接口请求地址,支持模板字符串

配置请求数据

可以配置data,配置自定义接口请求数据体。

{
    "type": "form",
    "api": {
        "method": "post",
        "url": "https://houtai.baidu.com/api/mock2/form/saveForm",
        "data": {
            "myName": "${name}",
            "myEmail": "${email}"
        }

    },
    "controls": [
      {
        "type": "text",
        "name": "name",
        "label": "姓名:"
      },
      {
        "name": "email",
        "type": "email",
        "label": "邮箱:"
      }
    ]
}

支持数据映射

method配置为get时,data中的值默认会添加到请求路径中

配置请求数据格式

可以配置dataType,来指定请求的数据体格式,默认为json

下面例子中api没有配置data属性,因为form会默认将所有表单项的值进行提交。

application/json

默认是application/json,不需要额外配置

{
    "type": "form",
    "title": "默认JSON格式",
    "api": {
        "method": "post",
        "url": "https://houtai.baidu.com/api/mock2/form/saveForm",
        "data":{
            "&": "$$" // 获取表单数据域中的所有值
        }
    },
    "controls": [
      {
        "type": "text",
        "name": "name",
        "label": "姓名:"
      },
      {
        "name": "email",
        "type": "email",
        "label": "邮箱:"
      }
    ]
  }

application/x-www-form-urlencoded

配置"dataType": "form",可配置发送体格式为application/x-www-form-urlencoded

{
    "type": "form",
    "api": {
        "method": "post",
        "url": "https://houtai.baidu.com/api/mock2/form/saveForm",
        "dataType": "form"
    },
    "controls": [
      {
        "type": "text",
        "name": "name",
        "label": "姓名:"
      },
      {
        "name": "email",
        "type": "email",
        "label": "邮箱:"
      }
    ]
  }

multipart/form-data

配置"dataType": "form-data",可配置发送体格式为multipart/form-data

{
    "type": "form",
    "api": {
        "method": "post",
        "url": "https://houtai.baidu.com/api/mock2/form/saveForm",
        "dataType": "form-data"
    },
    "controls": [
      {
        "type": "text",
        "name": "name",
        "label": "姓名:"
      },
      {
        "name": "email",
        "type": "email",
        "label": "邮箱:"
      }
    ]
  }

当表单项中文件类型数据,则自动使用multipart/form-data数据体

{
    "type": "form",
    "api": {
        "method": "post",
        "url": "https://houtai.baidu.com/api/mock2/form/saveForm"
    },
    "controls": [
      {
        "type": "text",
        "name": "name",
        "label": "姓名:"
      },
      {
        "name": "file",
        "type": "file",
        "label": "附件:",
        "asBlob": true
      }
    ]
  }

asBlob配置项会指定当前 File 控件不再自己上传了,而是直接把文件数据作为表单项的值,文件内容会在 Form 表单提交的接口里面一起带上。

配置自定义请求头

可以配置headers对象,添加自定义请求头

{
    "type": "form",
    "api": {
        "method": "post",
        "url": "https://houtai.baidu.com/api/mock2/form/saveForm",
        "headers": {
            "my-header": "aaa"
        }
    },
    "controls": [
      {
        "type": "text",
        "name": "name",
        "label": "姓名:"
      },
      {
        "name": "email",
        "type": "email",
        "label": "邮箱:"
      }
    ]
  }

配置请求条件

可以配置表达式sendOn来实现:当符合某个条件的情况下,接口才触发请求

{
    "title": "",
    "type": "form",
    "mode": "horizontal",
    "controls": [
      {
        "label": "选项1",
        "type": "radios",
        "name": "a",
        "inline": true,
        "options": [
          {
            "label": "选项A",
            "value": 1
          },
          {
            "label": "选项B",
            "value": 2
          },
          {
            "label": "选项C",
            "value": 3
          }
        ]
      },
      {
        "label": "选项2",
        "type": "select",
        "size": "sm",
        "name": "b",
        "source": {
            "method": "get",
            "url": "https://houtai.baidu.com/api/mock2/options/level2?a=${a}",
            "sendOn": "data.a === 2"
        },
        "description": "只有<code>选项1</code>选择<code>B</code>的时候,才触发<code>选项2</code>的<code>source</code>接口重新拉取"
      }
    ],
    "actions": []
}

查看 选项2source属性他是API类型值支持配置sendOn 表达式,实现根据条件请求接口。

配置接口缓存

当你在某种情况下,需要非常频繁的请求同一个接口,例如列表中,每一行中都有一个 Service 进行数据拉取操作,

{
    "type": "crud",
    "api": "https://houtai.baidu.com/api/sample?waitSeconds=1",
    "columns": [
        {
            "name": "id",
            "label": "ID"
        },
        {
            "type": "service",
            "label": "数据",
            "api": "https://houtai.baidu.com/api/mock2/page/initData",
            "body": {
                "type": "tpl",
                "tpl": "当前日期是:${date}"
            }
        }
    ]
}

如上,如果你打开浏览器网络面板,会发现/api/mock2/page/initData接口将重复请求多次,次数为你当前列表的数据条数。

这往往并不理想,你可以设置cache来设置缓存时间,单位是毫秒,在设置的缓存时间内,同样的请求将不会重复发起,而是会获取缓存好的请求响应数据。

{
    "type": "crud",
    "api": "https://houtai.baidu.com/api/sample?waitSeconds=1",
    "columns": [
        {
            "name": "id",
            "label": "ID"
        },
        {
            "type": "service",
            "label": "数据",
            "api": {
                "method": "get",
                "url": "https://houtai.baidu.com/api/mock2/page/initData",
                "cache": 2000
            },
            "body": {
                "type": "tpl",
                "tpl": "当前日期是:${date}"
            }
        }
    ]
}

这下我们再打开网络面板,发现只有一条请求了

配置请求适配器

amis的API配置如果无法配置出你想要的请求结构那么可以配置requestAdaptor发送适配器

发送适配器是指在接口请求前,对请求进行一些自定义处理,例如修改发送数据体、添加请求头、等等,基本用法是,获取暴露的api参数,并且对该参数进行一些修改,并return出去:

字符串形式

如果在JSON文件中配置的话requestAdaptor只支持字符串形式,如下:

{
    "type": "form",
    "api": {
        "method": "post",
        "url": "https://houtai.baidu.com/api/mock2/form/saveForm",
        "requestAdaptor": "return {\n    ...api,\n    data: {\n        ...api.data,    // 获取暴露的 api 中的 data 变量\n        foo: 'bar'      // 新添加数据\n    }\n}"
    },
    "controls": [
      {
        "type": "text",
        "name": "name",
        "label": "姓名:"
      },
      {
        "name": "email",
        "type": "email",
        "label": "邮箱:"
      }
    ]
  }

上例中的适配器实际上是如下代码的字符串形式:

return {
    ...api,
    data: {
        ...api.data,    // 获取暴露的 api 中的 data 变量
        foo: 'bar'      // 新添加数据
    }
}

函数形式

如果你的使用环境为js文件则可以直接传入函数如下

const schema = {
  type: 'form',
  api: {
    method: 'post',
    url: 'https://houtai.baidu.com/api/mock2/form/saveForm',
    requestAdaptor: function(api) {
      return {
        ...api,
        data: {
          ...api.data, // 获取暴露的 api 中的 data 变量
          foo: 'bar' // 新添加数据
        }
      };
    }
  },
  controls: [
    {
      type: 'text',
      name: 'name',
      label: '姓名:'
    },
    {
      name: 'text',
      type: 'email',
      label: '邮箱:'
    }
  ]
};

上面例子中,我们获取暴露的api对象中的data变量,并且为其添加了一个新的字段foo,并且一起返回出去就可以了,这样我们的请求数据体中就会加上我们这个新的字段。

api变量中一般会包含下面几个属性:

  • url:当前接口 Api 地址
  • method:当前请求的方式
  • data:请求的数据体
  • headers:请求的头部信息

你也可以使用debugger自行进行调试。

配置接收适配器

同样的如果后端返回的响应结构不符合amis的接口格式要求,而后端不方便调整时,可以配置adaptor实现接收适配器

接受欧适配器是指在接口请求后,对响应进行一些自定义处理,例如修改响应的数据结构、修改响应的数据等等。

例如:接口正确返回的格式中,会返回"code": 200而amis中接口返回格式需要"status": 0,这时候就需要接收适配器进行调整结构。

字符串形式

如果在JSON文件中配置的话adaptor只支持字符串形式,如下:

{
    "type": "form",
    "api": {
        "method": "post",
        "url": "https://houtai.baidu.com/api/mock2/form/saveForm",
        "adaptor": "return {\n    ...payload,\n    status: payload.code === 200 ? 0 : payload.code\n}"
    },
    "controls": [
      {
        "type": "text",
        "name": "name",
        "label": "姓名:"
      },
      {
        "name": "file",
        "type": "file",
        "label": "附件:",
        "asBlob": true
      }
    ]
  }

上例中的适配器实际上是如下代码的字符串形式:

return {
    ...payload,
    status: payload.code === 200 ? 0 : payload.code
}

函数形式

如果你的使用环境为js文件则可以直接传入函数如下

const schema = {
  type: 'form',
  api: {
    method: 'post',
    url: 'https://houtai.baidu.com/api/mock2/form/saveForm',
    adaptor: function(payload, response) {
        return {
            ...payload,
            status: payload.code === 200 ? 0 : payload.code
        }
    }
  },
  controls: [
    {
      type: 'text',
      name: 'name',
      label: '姓名:'
    },
    {
      name: 'email',
      type: 'email',
      label: '邮箱:'
    }
  ]
};

replaceData

返回的数据是否替换掉当前的数据,默认为 false(即追加),设置为true就是完全替换当前数据。

属性表

字段名 说明 类型 备注
method 请求方式 字符串 支持get、post、put、delete
url 请求地址 模板字符串 -
data 请求数据 对象或字符串 支持数据映射
dataType 数据体格式 字符串 默认为 json 可以配置成 form 或者 form-data。当 data 中包含文件时,自动会采用 form-datamultipart/form-data 格式。当配置为 form 时为 application/x-www-form-urlencoded 格式。
qsOptions -- 对象或字符串 当 dataType 为form或者form-data 的时候有用。具体参数请参考这里,默认设置为: { arrayFormat: 'indices', encodeValuesOnly: true }
headers 请求头 对象 -
sendOn 请求条件 表达式 -
cache 接口缓存时间 整型数字 -
requestAdaptor 发送适配器 字符串 ,支持字符串串格式,或者直接就是函数如:
adaptor 接收适配器 字符串 如果接口返回不符合要求,可以通过配置一个适配器来处理成 amis 需要的。同样支持 Function 或者 字符串函数体格式
replaceData 替换当前数据 布尔 返回的数据是否替换掉当前的数据,默认为 false,即:追加,设置成 true 就是完全替换。