体系说明

宜搭单据、流程、展示类型页面中，页面设计 ->页面渲染的能力，借力于阿里巴巴企业智能事业部 Vision 可视化解决方案。
Vision中以设计引擎(VisualEngine, 以下简称VE)和渲染引擎(RenderEngine, 以下简称RE)为核心，在页面设计到用户访问的过程中，遵循以下流程：
(高级) JS - 功能定制 - 图1

渲染过程

RE渲染时，主要分为以下几个过程：

  1. 初始化ctx；创建上下文对象Context，并加载子模块 存储模型(ctx.store)、数据池(ctx.dp)、外部插件(ctx.fn)等

  2. 初始化动作面板；执行动作面板中可执行的代码，并将export导出的方法整理到ctx.pageActions列表中

  3. 初始化数据池；加载数据池中定义的变量/参数/远程接口，并整理到ctx.dp中

  4. 渲染页面；渲染组件内容，同时为各个组件绑定独立的状态管理器(State)，并将State整理到ctx.store中

  5. 执行回调队列；此队列默认按照 公式/数据联动请求发送(异步回调)、宜搭系统逻辑、页面初始化(didMount)执行的顺序依次执行。

以下将按照上述过程，依次介绍相关功能模块。

API列表

参见 (高级) JS - 基础API

动作面板

动作面板是 JS 代码的主要编辑入口，负责定义页面事件函数、执行渲染前的初始化逻辑。

使用

(高级) JS - 功能定制 - 图2

上图中，动作面板中编入以下三类代码

  • 渲染前的初始化代码。
    • 如正常的JS一样执行，但代码逻辑应当与页面渲染无关(此时数据源、页面内容还未初始化)。
    • 若需要在页面内容加载完成后执行回调函数，请在 页面初始化 模块中编辑代码。
  • 动作面板内的公共函数。
    • 可在动作面板内任意调用，但在其它模块无法使用。
  • export导出的模块方法。
    • 可以在各个组件的动作设置中，设置当组件的指定事件触发时，执行此方法。
    • 由事件触发时，默认传递的第一个参数为ctx。断点调试/控制台输出arguments查看所有参数。
    • 也可在其它模块中，通过 ctx.execAction(String :: fnName, …params) 正常调用执行

注意点

  • 动作面板中的ES6语法通过Babel编译为ES5语法
    • 提供了 Promise、asyn/await 的 polyfill，但未提供Symbol、generate等其它特性的兼容
    • chrome支持 debugger; 语句插入断点进行调试。
    • 存在约400ms的编译时间，修改内容后可稍候再点击保存（Ctrl/Command+S）。
    • Babel编译失败时(如const变量重定义)，编译结果为空，此时控制台存在报错信息。代码不生效时可查看控制台是否有报错信息。
  • 编译后，动作面板被视作ES6模块，于闭包环境中执行。
    • 因此未被 export 导出的方法无法在其它模块（页面初始化、自定义校验等）中调用。
    • export导出的方法将被ctx.pageActions整合，再通过 ctx.execAction 在其它模块如正常函数调用。

(高级) JS - 功能定制 - 图3

数据池

数据池的介绍及相关api见 数据池

注意点

  • NAME 作为数据源在页面中的唯一标识
    • 不能与组件的唯一标识 fieldId 重复
    • 数据初始化或接口成功返回后，获得的数据以此 NAME 为key存入ctx中。
  • 自动类型的远程数据源，会在接口返回前，阻断页面的渲染
    • 若接口抛出异常，此数据源初始化失败，且目前会导致所有数据源初始化失败
  • 可通过 ctx.dp.getValue(key) 获取指定数据源的值
  • 可以在 变量 系统中使用${key}的方式，调用指定数据源的值。

远程数据源

从一个远程 URL 中获取的数据。
请求远程接口数据，数据由FIT函数适配，didFetch回调处理后，以NAME为key存入到ctx.dp中。

接口数据格式约定

若目标接口返回的数据不满足以下接口，请自行使用 FIT 函数配置转换逻辑。

  1. // 返回成功的标准
  2. {
  3.   content   : {
  4.     data    : [
  5.       {
  6.         name: '张三'
  7.       }
  8.     ],
  9.     totalCount: 1000,
  10.     currentPage: 3
  11.   },
  12.   success   : true,
  13.   errorMsg  : '',
  14.   errorCode : '',
  15.   errorLevel: ''
  16. }
  18. // content any 返回值
  19. // success Boolean 表示请求成功还是失败
  20. // errorMsg String 错误信息，不是error数组. 如果需要返回error数组的时候
  21. // errorLevel String ['info’, 'warn’, 'error’, 'fault’]
  22. // errorCode Number 错误编码

以人员搜索接口为例：
(高级) JS - 功能定制 - 图4
(高级) JS - 功能定制 - 图5

共享给所有页面：勾选后默认将数据源共享到当前应用下其它页面的数据池中（报表页除外），但此共享变量仅能够在当前页面的设计器中进行变更修改。

详细设置说明：

加载方式

远程数据源有三种加载方式：

  1. 「自动」：页面在渲染之前就会阻塞加载，加载完毕之后再渲染页面。
  2. 「手动」：由用户通过 API ctx.dp.exec(‘NAME’,params).then(callback) 来手动发送请求并添加回调方法。
  3. 「异步」：远程请求被在页面初始加载过程中不被依赖，可以与页面初始化渲染同时进行。

URL
请求的接口地址。支持相对地址或绝对地址。
注意：宜搭线上环境统一为HTTPS页面，出于浏览器安全限制，http的接口将无法被发送。如有http的接口，请自行寻找后端开发转为https，内部环境可以尝试使用epaas进行转换。

METHOD
请求的发送方式。
默认为JSONP方式，同样请注意上述协议问题。

PARAMS
请求默认携带的参数。
params中添加的name和value将作为请求接口的参数。
此处value的输入框输入内容同样支持 变量 系统。但额外的不同点在于，若${}中的内容执行时存在错误，则退出执行并连带外部${}一起，以字符串类型作为请求的参数值。见下图：
(高级) JS - 功能定制 - 图6
(高级) JS - 功能定制 - 图7

注意事项：

  • 例子中取当前登录用户的工号，${window.pageConfig.loginUserId}

SHOULD
是否允许发送这个请求。
默认为空时视为true。仅支持 变量 系统的输入方式(即 ${js表达式} )。任何非变量的输入都视为true。
可参照PARAMS中的示例。

WILL(willFetch)
请求发送前执行的方法。
此方法默认接受 vars, config, ctx 三个参数。通常用于确认请求参数。

  • vars：实际请求的参数。包含vars.data(配置的参数)和vars.mark(ajax标记参数)两部分。强烈建议只读。
  • config：当前ajax库(natty-fetch)的配置信息。强烈建议只读。
  • ctx：同window.LeGao.getContext()。

注意：自动/异步模式下此时页面仍处在初始化阶段，ctx.store、ctx.dp等模块相关的API无法使用。

FIT(fit)
请求接受到数据后，为使数据符合natty-fetch默认的接口数据格式约定，提供的适配处理函数。
默认为空，即不作处理。若接口返回的数据不符合约定，请自行编辑fit函数，见下图 EXPORTS 所示。

DID(didFetch)
请求处理函数。
接受请求返回数据中的content字段，处理后存入ctx.dp对应的’NAME’数据源中。
此方法默认接受 content, ctx 两个参数。
content即接口返回(或经过fit函数处理后)的content字段。
函数return的内容将存入对应’NAME’的数据源中。
同样，注意：自动/异步模式下此时页面仍处在初始化阶段，ctx.store、ctx.dp等模块相关的API无法使用。

EXPORTS
对didFetch处理后数据对象，某个固定子数据的引用固定路径另起别名，以方便引用。
(高级) JS - 功能定制 - 图8
(高级) JS - 功能定制 - 图9

变量数据源

在页面中定义的本地变量。
初始设置变量数据DATA的输入框，其中输入的内容会先按字符串格式取出，并尝试用JSON.parse()方法格式化。
若格式化成功，则该变量数据将保存为对象类型。否则保存为字符串类型。
因此无法设置初始值为 null、数字类型。若需要设为此类类型请使用 ctx.dp.setValue 。

(高级) JS - 功能定制 - 图10

参数数据源

从 window.location.search 中解析获得的{key:value}对象。以NAME的方式为此对象定义别名。

(高级) JS - 功能定制 - 图11

断开数据同步：请勿使用。Vision体系默认支持线上线下两套数据源分开配置，以方便线上与日常环境独立测试。但宜搭当前正式环境皆为线上环境，断开同步后额外的线下环境数据源没有实际效果，且断开后暂无法移除线下环境界面。请避免使用。

案例1：
【需求描述】
希望从url中获取请求参数，并将其设置为表单中某个组件的默认值，并且通过这个默认值进行数据联动，关联出其他数据。

【解决方案】
新版的设计器已经默认在参数数据源中增加了一个名为urlParams的参数数据源，老版的页面设计器需要手动创建一个，它可以解析url中的参数。
image.png

接下来我们去给需要从url中获取参数的组件去设置默认值，预发为：

${urlParams.name}

其中，urlParams来自于参数数据源，而name则是url中承载需要获取值的key，这里只是一个示例，这个key可以换成用户url中任意携带参数的字段。
image.png

为了测试，我们在原来表单填写的url后面附加上了一个参数”name=sam”，它与访问地址之间采用”?”进行连接。
image.png

将访问地址输入到浏览器中，点击回车访问页面，可以看到，url中的name参数被成功获取到姓名的输入框中作为默认值了。至于数据联动的功能，不是本小结的重点，感兴趣的读者可以参考：数据联动。

页面初始化

页面内容渲染完成后，执行的回调函数。
入口：大纲树 (或点击页面空白处) -> 页面-> 高级 -> 页面初始化
通常用于判断页面状态，修改组件的值/显隐状态等。
此时动作面板、数据源已初始化完毕，可调用ctx.execAction, ctx.dp.getValue等api执行相关操作

(高级) JS - 功能定制 - 图15

注意点

  • 初始化函数 function didMount 默认只接收一个参数 ctx 对象。
  • 此代码块中，若最外层存在多个函数，只会取第一个函数作为页面初始化的回调函数。
  • 公式/数据联动等数据获取操作为异步执行，此时还无法获取到公式/联动所得到的组件值。若需要在公式/数据联动更新组件内容后执行额外操作，请参照一下联动监听内容。

image.png

变量

变量 {var} 是设计器中提供的快速设置 局部配置项 的方式。

使用方式

image.png

基础使用如上图所示。变量支持在以下区域中，通过 ${} 的方式进行使用：

  • 国际化文本框 (上图 标题/提示文案)、富文本编辑框 (上图 编辑描述)
  • {var} 标记的配置项，点击激活变量输入
  • 数据池，详细：
    • 远程数据源 - Params - value，Should
    • 变量数据源 - Data
  • 动作设置 - 响应动作 - 参数设置 (示例)

变量语法

${} 中的变量内容必须是合法的 JS 语句，其执行结果将作为配置项的值。

  • 若 变量内容 在尝试执行时报错，整个变量内容 (包括${}部分) 将作为字符串类型，原样输出。
  • 变量中可以直接使用 数据池 中定义的 数据源变量。
    • 当 数据源变量 被 ctx.dp 相关api修改时，所有变量内容都会被重新计算
  • 变量中可以使用非明细内的 组件 的唯一标志(fieldId)。
    • 此使用方式需要对 组件底层数据结构 有一定了解。可console命令在控制台输出查看。
    • 通常可用 ${textField_xxxx.fieldData.value} 获取目标组件textField_xxx的值，并作为当前组件的默认值
    • 当任意组件被 用户操作 或 state.set/merge 修改时，所有变量内容都会被重新计算

动作设置

组件的动作设置一般与组件能够触发的事件有关，通常用于指定事件触发后执行额外的功能或操作。
除部分展示类组件外，大多数组件具都有高级->动作设置的配置项。
响应动作的可选项有：

  • 动作面板中export的函数

  • 自定义动作

  • 打开URL

  • 打开/关闭弹窗 (宜搭暂无弹窗组件，请忽略)

  • 显示/隐藏组件 (不推荐使用，见组件属性-Visibility)

  • 发起令箭请求 (数据埋点相关，暂无说明)

export的函数与自定义动作都会在指定事件触发后被调用，实际功能相同。

  1. 参数设置可以添加事件触发后额外传递的数据，此数据将作为回调函数中 ctx.params 字段而存在，并非回调函数实际接受的参数。

  2. 回调函数第一个参数为ctx，此ctx中额外包含了当前组件的State，可以通过 ctx.state 直接获取，但部分API在此ctx中无法使用。

  3. 自定义动作默认的回调函数参数为let {store, fn} = ctx的解构展示，实际可以整体替换为ctx。

  4. 参数设置内容中，可以使用 ${} 方式引用变量系统中已定义的变量的值。不推荐尝试。

(高级) JS - 功能定制 - 图18

自定义校验

该函数会在表单类组件值改变/获取所有表单数据时触发，判断显示错误信息并阻断提交。
入口为 表单类组件 -> 校验 -> 自定义函数。
默认参数：value(组件实际值，即fieldData/value)，state(组件的State)，ctx(封装过的ctx，部分API不存在)
返回值：true(校验通过) or false(校验不通过，展示错误提示)。
state.set/state.merge 修改组件的 fieldData/value 后默认会触发组件的校验。也可由 state.forceValid 强制触发。

选择类表单组件选项配置

网关数据

选择“网关数据”后，需要填写url地址，示例测试地址如下：
http://dip.alibaba-inc.com/api/v2/services/schema/mock/59422?formUuid=${formUuid}&jsonp

数据结构约定

  1. {
  2.     success: true,
  3.     content: [
  4.         {
  5.             text: '选项label',
  6.             value: '选项value'，
  7.             defaultChecked: true
  8.         },
  9.         {
  10.             text: '选项label2',
  11.             value: '选项value2'
  12.         }
  13.     ]，
  14.     errorCode: '',
  15.     errorMsg: ''
  16. }

如何携带参数

  1. ?formUuid=${formUuid}&loginUserId=${loginUserId}&limit=20

需自行拼接参数到url地址后，参数支持变量的形式${formUuid}，不存在则会置空

参数来源:

  1. url（location.search）
  2. 系统内置（window.systemParams）目前支持loginUserId和formUuid

如何设置默认值

见数据结构约定，设置选项的defaultChecked属性为true即可

jsonp支持

  1. 可识别地址如“getOption.jsonp”
  2. 其它情况可在请求参数上加上“jsonp”，如“getOption?jsonp”