amis2/docs/zh-CN/components/service.md

title	description	type	group	menuName	icon	order
Service 功能型容器		0	⚙ 组件	Service		63

amis 中部分组件，作为展示组件，自身没有使用接口初始化数据域的能力，例如：Table、Cards、List等，他们需要使用某些配置项，例如source，通过数据映射功能，在当前的 数据链 中获取数据，并进行数据展示。

而Service组件就是专门为该类组件而生，它的功能是：：配置初始化接口，进行数据域的初始化，然后在Service内容器中配置子组件，这些子组件通过数据链的方法，获取Service所拉取到的数据

基本使用

最基本的使用，是配置初始化接口api，将接口返回的数据添加到自身的数据域中，以供子组件通过数据链进行获取使用。

{
    "type": "service",
    "api": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/page/initData",
    "body": {
        "type": "panel",
        "title": "$title",
        "body": "现在是：${date}"
    }
}

你可以通过查看网络面板看到，service接口返回的数据结构为：

{
  "status": 0,
  "msg": "",
  "data": {
    "title": "Test Page Component",
    "date": "2017-10-13"
  }
}

在service的子组件中，就可以使用${title}和${date}展示数据

展示列表

另外一种使用较为频繁的场景是：serivce + table 进行列表渲染

{
    "type": "service",
    "api": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/crud/table?perPage=5",
    "body": [
        {
            "type": "table",
            "title": "表格1",
            "source": "$rows",
            "columns": [
                {
                    "name": "engine",
                    "label": "Engine"
                },
                {
                    "name": "version",
                    "label": "Version"
                }
            ]
        },
        {
            "type": "table",
            "source": "$rows",
            "columns": [
                {
                    "name": "engine",
                    "label": "Engine"
                },
                {
                    "name": "version",
                    "label": "Version"
                }
            ]
        }
    ]
}

上例中 service 接口返回数据结构如下：

{
  "status": 0,
  "msg": "ok",
  "data": {
    "count": 57,
    "rows": [
      {
        "engine": "Trident",
        "browser": "Internet Explorer 4.0",
        "platform": "Win 95+",
        "version": "4",
        "grade": "X",
        "id": 1
      },
      {
        "engine": "Trident",
        "browser": "Internet Explorer 5.0",
        "platform": "Win 95+",
        "version": "5",
        "grade": "C",
        "id": 2
      },
      {
        "engine": "Trident",
        "browser": "Internet Explorer 5.5",
        "platform": "Win 95+",
        "version": "5.5",
        "grade": "A",
        "id": 3
      },
      {
        "engine": "Trident",
        "browser": "Internet Explorer 6",
        "platform": "Win 98+",
        "version": "6",
        "grade": "A",
        "id": 4
      },
      {
        "engine": "Trident",
        "browser": "Internet Explorer 7",
        "platform": "Win XP SP2+",
        "version": "7",
        "grade": "A",
        "id": 5
      },
      {
        "engine": "Trident",
        "browser": "AOL browser (AOL desktop)",
        "platform": "Win XP",
        "version": "6",
        "grade": "A",
        "id": 6
      },
      {
        "engine": "Gecko",
        "browser": "Firefox 1.0",
        "platform": "Win 98+ / OSX.2+",
        "version": "1.7",
        "grade": "A",
        "id": 7
      },
      {
        "engine": "Gecko",
        "browser": "Firefox 1.5",
        "platform": "Win 98+ / OSX.2+",
        "version": "1.8",
        "grade": "A",
        "id": 8
      },
      {
        "engine": "Gecko",
        "browser": "Firefox 2.0",
        "platform": "Win 98+ / OSX.2+",
        "version": "1.8",
        "grade": "A",
        "id": 9
      },
      {
        "engine": "Gecko",
        "browser": "Firefox 3.0",
        "platform": "Win 2k+ / OSX.3+",
        "version": "1.9",
        "grade": "A",
        "id": 10
      }
    ]
  }
}

table中配置source属性为${rows}就可以获取到rows变量的数据，并用于展示。

动态渲染页面

Service 还有个重要的功能就是支持配置 schemaApi，通过它可以实现动态渲染页面内容。

{
  "type": "service",
  "schemaApi": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/service/schema?type=tabs"
}

同样观察schemaApi接口返回的数据结构：

{
  "status": 0,
  "msg": "",
  "data": {
    "type": "tabs",
    "tabs": [
      {
        "title": "TabA",
        "body": "卡片A内容"
      },
      {
        "title": "TabB",
        "body": "卡片B内容"
      }
    ]
  }
}

它将data返回的对象作为 amis 页面配置，进行了解析渲染，实现动态渲染页面的功能。

动态渲染表单项

默认 Service 可以通过配置schemaApi 动态渲染页面内容，但是如果想渲染表单项，请返回下面这种格式：

{
  "status": 0,
  "msg": "",
  "data": {
    "type": "container",
    "body": [
      {
        "type": "input-text",
        "name": "text",
        "label": "文本输入"
      }
    ]
  }
}

例如下例：

{
  "type": "service",
  "schemaApi": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/service/schema?type=controls"
}

schemaApi 除了能返回表单项之外，还能同时返回表单数据，如果你这样返回接口

{
  "status": 0,
  "msg": "",
  "data": {
    "data": {
      "a": "b" // 这样返回的选项会选中第二个选项B
    },
    "body": [
      {
        "type": "select",
        "name": "a",
        "label": "选项",
        "options": [
          {"label": "A", "value": "a"},
          {"label": "B", "value": "b"}
        ]
      }
    ]
  }
}

接口联动

api和schemaApi都支持接口联动

{
    "title": "",
    "type": "form",
    "api": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock/saveForm?waitSeconds=1",
    "mode": "horizontal",
    "body": [
        {
        "label": "数据模板",
        "type": "select",
        "name": "tpl",
        "value": "tpl1",
        "size": "sm",
        "options": [
            {
            "label": "模板1",
            "value": "tpl1"
            },
            {
            "label": "模板2",
            "value": "tpl2"
            },
            {
            "label": "模板3",
            "value": "tpl3"
            }
        ],
        "description": "<span class=\"text-danger\">请修改该下拉选择器查看效果</span>"
        },
        {
        "type": "service",
        "api": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/form/initData?tpl=${tpl}",
        "body": [
            {
            "label": "名称",
            "type": "input-text",
            "name": "name"
            },
            {
            "label": "作者",
            "type": "input-text",
            "name": "author"
            },
            {
            "label": "请求时间",
            "type": "input-datetime",
            "name": "date"
            }
        ]
        }
    ],
    "actions": []
}

上例可看到，变更数据模板的值，会触发 service 重新请求，并更新当前数据域中的数据

更多相关见接口联动

定时轮询刷新

设置 interval 可以定时刷新 api 接口，单位是毫秒，最小间隔是 1 秒。

通过 WebSocket 实时获取数据

Service 支持通过 WebSocket 获取数据，只需要设置 ws（由于无示例服务，所以无法在线演示）。

{
  "type": "service",
  "api": "https://3xsw4ap8wah59.cfc-execute.bj.baidubce.com/api/amis-mock/mock2/page/initData",
  "ws": "ws://localhost:8777",
  "body": {
    "type": "panel",
    "title": "$title",
    "body": "随机数：${random}"
  }
}

可以只设置 ws，通过 ws 来获取所有数据，也可以同时设置 api 和 ws，让 api 用于获取全部数据，而 ws 用于获取实时更新的数据。

后端实现示例，基于 ws：

const WebSocket = require('ws');

const ws = new WebSocket.Server({port: 8777});

ws.on('connection', function connection(ws) {
  setInterval(() => {
    const random = Math.floor(Math.random() * Math.floor(100));
    // 返回给 amis 的数据
    const data = {
      random
    };
    // 发送前需要转成字符串
    ws.send(JSON.stringify(data));
  }, 500);
});

WebSocket 客户端的默认实现是使用标准 WebSocket，如果后端使用定制的 WebSocket，比如 socket.io，可以通过覆盖 env.wsFetcher 来自己实现数据获取方法，默认实现是：

wsFetcher(ws, onMessage, onError) {
  if (ws) {
    const socket = new WebSocket(ws);
    socket.onmessage = (event: any) => {
      if (event.data) {
        onMessage(JSON.parse(event.data));
      }
    };
    socket.onerror = onError;
    return {
      close: socket.close
    };
  } else {
    return {
      close: () => {}
    };
  }
}

通过 onMessage 来通知 amis 数据修改了，并返回 close 函数来关闭连接。

属性表

属性名	类型	默认值	说明
type	string	"service"	指定为 service 渲染器
className	string		外层 Dom 的类名
body	SchemaNode		内容容器
api	api		初始化数据域接口地址
ws	string		WebScocket 地址
initFetch	boolean		是否默认拉取
schemaApi	api		用来获取远程 Schema 接口地址
initFetchSchema	boolean		是否默认拉取 Schema
messages	Object		消息提示覆写，默认消息读取的是接口返回的 toast 提示文字，但是在此可以覆写它。
messages.fetchSuccess	string		接口请求成功时的 toast 提示文字
messages.fetchFailed	string	"初始化失败"	接口请求失败时 toast 提示文字
interval	number		轮询时间间隔(最低 3000)
silentPolling	boolean	false	配置轮询时是否显示加载动画
stopAutoRefreshWhen	表达式		配置停止轮询的条件