代码设计

1. 简介

1.1 功能简介

代码编辑就是为配置的参数设置具体的执行规则，这里的规则需要使用代码语言自定义编写。

1.2 代码语言

简道云自建插件目前支持的代码语言有：

1.3 预期效果

1）后端函数插件配置及执行效果如下所示：

2）前端扩展插件配置及执行效果如下所示：

2. 插件函数

2.1 函数类型

插件新建完成后，需要新增对应的函数。插件中的函数分为以下 2 种类型，在「插件设计」页面中，点击左下角的「新增函数」，您可根据自己的需求选择不同的函数进行创建：

2.2 复制函数

若需要对函数进行复用，点击函数右侧的三个小圆点，选择「复制」，即可复制函数。

3. 代码编辑

3.1 设计页面

参数设计确定后，您就需要为函数编写代码来实现其功能。在编程语言选择处（下图 1）选择您熟悉的编程语言，在代码编辑器（下图 2）中编写函数代码。在您的代码中，可以引用您在入参声明中定义的参数，参数列表和值的类型可以参考右侧的（下图 3）中的提示。

3.2 后端函数-示例代码及说明

Python 3.6

# 可以引用一些第三方库.
import json
import requests

# 可以通过读取预定义的全局变量中的属性来获取您定义的参数.
# agentConf 含义是通用参数, 其结构为一个字典(dict), key 为您在入参模板中为控件定义的 ID, 值为用户指定的配置值.
# triggerConf 含义是请求参数, 其结构为一个字典(dict), key 为您在入参模板中为控件定义的 ID, 值为用户指定的配置值或表单字段的值.
api_key = str(agentConf.get('apiKey'))
dept_no = triggerConf.get('deptNo')

# 您需要对输入参数的类型, 格式做校验, 以增强函数逻辑的健壮性.
# 如下方对可能拿到的不同值格式进行处理，保证最终dept_no的准确性，具体值格式见本文「5.1 triggerConf (请求参数）结构」
try:
    if isinstance(dept_no, str):
        dept_no = json.loads(dept_no)
    if isinstance(dept_no, list):
        dept_no = dept_no[0] if 0 < len(dept_no) else None
    if isinstance(dept_no, dict):
        dept_no = dept_no.get('dept_no')
    if dept_no is None:
        dept_no = 1
    dept_no = int(dept_no)
except:
    raise ValueError('部门编号格式错误')

# 可以利用第三方库和请求参数, 在服务端环境中调用相关接口并获取结果.
url = ' https://api.jiandaoyun.com/api/v5/corp/department/user/list'
payload = {'dept_no': dept_no}
headers = {'Authorization': 'Bearer ' + api_key}
response = requests.post(url, json=payload, headers=headers)
if 300 <= response.status_code < 500:
    # 对特定结果主动抛错, 定义抛错文案.
    body = response.json()
    code = body.get('code', -1)
    message = body.get('message', '未知错误')
    message = '参数错误(%s): %s' % (code, message)
    raise ValueError(message)
# 对结果进行处理, 定义返回参数值.
# 您需要返回一个dict, dict的key和返回参数ID一一对应. 若返回为数组, 则对应出参需设置为object[]类型.
body = response.json()
users = [{'name': user.get('name'), 'username': user.get(
    'username')} for user in body.get('users', [])]
count = len(users)
return {
    "users": users,
    "count": count
}

# 可引用的全局变量, 支持的第三方库, 请求参数数据存储格式, 见本文「5.相关信息」.

Node.js 20

// 可以引用一些第三方库.
const _ = require('lodash');
const axios = require('axios');

// 可以通过读取预定义的全局变量中的属性来获取您定义的参数.
// agentConf 含义是通用参数, 其结构为一个对象(Object), key 为您在入参模板中为控件定义的 ID, 值为用户指定的配置值.
// triggerConf 含义是请求参数, 其结构为一个对象(Object), key 为您在入参模板中为控件定义的 ID, 值为用户指定的配置值或表单字段的值.
const apiKey = _.chain(agentConf).get(['apiKey']).trim().value();
let deptNo = _.get(triggerConf, ['deptNo']);

// 您需要对输入参数的类型, 格式做校验, 以增强函数逻辑的健壮性.
// 如下方对可能拿到的不同值格式进行处理，保证最终dept_no的准确性，具体值格式见本文「5.1 triggerConf (请求参数）结构」
try {
    if (_.isString(deptNo)) deptNo = JSON.parse(deptNo);
    if (_.isArray(deptNo)) deptNo = _.first(deptNo);
    if (_.has(deptNo, ['dept_no'])) deptNo = _.get(deptNo, ['dept_no']);
    deptNo = _.toInteger(deptNo);
} catch (e) {
    throw new Error('请输入正确的部门编号');
}

// 可以利用第三方库和请求参数, 在服务端环境中调用相关接口并获取结果.
try {
    const response = await axios({
        method: 'post',
        url: ' https://api.jiandaoyun.com/api/v5/corp/department/user/list',
        headers: {
            Authorization: `Bearer ${apiKey}`,
            'Content-Type': 'application/json'
        },
        data: { dept_no: deptNo }
    });
    const { data } = response;
    // 对结果进行处理, 定义返回参数值.
  	// 您需要返回一个object, object的key和返回参数ID一一对应. 若返回为数组, 则对应出参需设置为object[]类型.
    const users = _.chain(data)
    	.get(['users'])
    	.map((it) => ({ name: it.name, username: it.username }))
    	.value();
    return { users, count: users.length };
} catch (e) {
    // 对特定结果主动抛错, 定义抛错文案.
    const code =
        _.get(e, ['response', 'data', 'code']) || _.get(e, ['code']) || -1;
    let message =
        _.get(e, ['response', 'data', 'msg']) ||
        _.get(e, ['message']) ||
        '未知错误';
    message = `参数错误(${code}): ${message}`;
    throw new Error(message);
}

// 可引用的全局变量, 支持的第三方库, 请求参数数据存储格式, 见本文「6.相关信息」

3.3 前端扩展-示例代码及说明

// closeModal
const close = () => {
    $g.utils.closeModal();
    console.log('4s后模态框关闭');
};

const reportUrl = $g.env.baseUrl;

setTimeout(() => close(), 4000);

// GET
let response = await fetch(reportUrl, {method: 'GET'});
const resText = await response.text()
console.log(resText);

let message;

$g.ui.onmessage = function (msg) {
    message = msg
}

// openModal
// openModal：弹窗后继续代码执行，执行完结束 Worker。
// await openModal：弹窗后阻塞代码执行，按照开发者代码规定执行后续动作。
await $g.utils.openModal({
    title: '如果您对插件有任何需求，欢迎在本表单填写',
    url: reportUrl
});

// 调用后端函数
await $g.utils.callFunction({
    name: 'func.ID',
    data: {}
})

return {
    resText,
    message
}

3.4 参数提示的使用

代码编辑器右侧可展开参数提示，点击对应参数/函数，将添加对应调用语法到代码编辑器中。

3.5 参数校验提示信息

编写请求参数/返回参数/通用参数时，若出现代码错误，对应代码将用红色波浪线标注，且当鼠标放在对应代码上时，会显示详细的配置错误信息，便于开发者校验修改代码内容，提升编辑体验。效果如下所示：

3.6 语法错误提示信息

在前端扩展/后端函数的 Python 代码视图下，编辑器中支持在保存代码时提示语法错误。帮助开发者快速定位具体问题，为开发者提供更为直观、高效的开发体验。效果如下图所示：

4. 相关信息

4.1 全局变量

您在代码中可以直接引用全局变量 agentConf、triggerConf、triggerContext。

4.1.1 agentConf (通用参数）结构

agentConf 即插件对应的通用参数。

其结构为对应编程语言的键值数据结构，如 Python 的 dict 或 Node.js 的 Object。在该结构中，键为您在入参声明中为变量指定的 ID，值为用户配置或引用的数据。

4.1.2 triggerConf (请求参数）结构

triggerConf 即插件函数对应的请求参数。

其结构为对应编程语言的键值数据结构，如 Python 的 dict 或 Node.js 的 Object。在该结构中，键为您在入参声明中为变量指定的 ID，值为用户配置或引用的数据(具体结构见下文)。

举例，您正在开发一个图像识别类的插件，并在该插件的请求参数中加入了一个文本字段用以接受用户的图片附件，那么基于不同的用户配置，您有可能得到不同的值:

您应该结合自己插件的功能和预期服务的用户场景，在代码中妥善处理上述情况，并在不计划支持该类型时通过抛出错误并附加消息向用户提示原因。

请求参数储值格式

1）保存自定义值

当用户在插件配置时直接保存「自定义值」时（如上图），请求参数中不同控件的储值格式如下表：

2）保存字段

当用户在简道云表单数据场景中使用插件时，可保存字段值(如上图)，入参声明中各个控件的储值格式如下表：

4.1.3 triggerContext 结构

triggerContext 中存储了运行环境的基本信息，如简道云的开放 API 域名等。

4.2 内置库支持列表

4.2.1 Node.js内置库

4.2.2 Python内置库

以下列表里包括可调用的内置库和第三方库。

4.3 可用前端扩展API

5. 注意事项

5.1 插件运行限制

插件在运行时有相应的限制。插件本身的超时时间为 60 s，但是不同使用场景本身也有自己的超时时间，比如前端事件的 15 s。

5.2 前端扩展调用后端函数

进行自建插件设计时，若在「前端扩展函数 >> 代码」处调用了后端函数，则插件执行时，前端扩展中的后端函数执行上限为 5 次。

以中奖通知为例，在表单内点击「新建邮件」便会打开编辑窗口，填写并点击「发送邮件」即可完成通知。其中，「新建邮件」为前端扩展，「发送邮件」为后端函数，则每次打开新建邮件弹窗后，发送邮件的上限为 5 次。