自定义控件开发API篇

# 1 用户场景 随着开发的自定义控件越来越多，不少开发对自定义控件的开发流程已经有了大概的认识。但是对自定义控件的API还不是很熟悉，因此本文将详细介绍自定义控件相关API。 # 2 功能介绍 ## 2.1控件方案（属性ID：schemaInfo）：Map类型 每一个自定义控件对应一个控件方案，选择或者新建一个控件方案，自定义控件会根据关联的方案的渲染对应的页面 | 属性名 | 属性ID | 类型 | 说明 | | --- | --- | --- | --- | | 控件方案id | ```
schemaId | String | 必填项，不同控件的方案id不同，schemaId是控件唯一性的标识 | | 开发商标识 | ```
isvId | String | 必填项，例如：kingdee，kddep等 | | 领域标识 | ```
moduleId | String | 必填项，例如：hr，fi等 | | 控件方案名称 | ```
schemaName | String | 非必填项，设置描述控件的名称 | ## 2.2 配置项（属性ID：ci）：List类型 用于在设计时给自定义控件配置自定义参数，可用于自定义业务属性和样式属性，自定义控件内部逻辑可根据不同的属性值来处理不同的渲染逻辑。 建议配置项用来配置控件的元数据，不推荐通过此属性传输业务数据给控件 ## 2.3 模型（`model`） 模型对象，自定义控件默认提供，值不能修改，model中的内容通常是包含该自定义控件的外部属性，其中包含以下内容 | 属性名 | 属性ID | 类型 | 说明 | | --- | --- | --- | --- | | 页面标识 | pageId | `string` | 自定义控件所在表单的`data-page-id` | | 控件标识 | key | `string` | 设计时配置的标识，是唯一的 | | DOM元素 | dom | `Node` | 自定义控件提供的可供设置`innerHTML`的DOM节点 | | 控件方案id | scheamId | `string ` | 新建方案时填写的控件方案id | | 开发商标识 | isvId | `string` | 新建方案时填写的isvId（一般默认） | | 领域标识 | moduleId | `string` | 新建方案时填写的领域标识 | | 指令函数 | invoke | `function` | 将自定义控件事件发送给平台后端，接收两个参数，`eventName` 执行事件名称，`eventArgs` 执行事件所需参数，推荐使用字符串 | ## 2.4 数据（`props`） 数据对象，props里面描述的通常是该控件的内部属性，直接和控件渲染逻辑相关，常用如下: | 属性名 | 属性ID | 类型 | 说明 | | --- | --- | --- | --- | | 主题色 | themeColor | `string` | 可以根据该主题色标示实现自定义控件多主题 | | 锁定性 | lock | `boolean` | 可以在设计时的业务属性上配置锁定性，根据该属性控件控件是否可编辑 | | 数据对象 | data | `any` | 插件中setData接口设置的数据 | | 配置项 | configItems | `List` | 控件设计时自定义属性 | | 卡片行数据 | cardRowData | `object` | 当自定义控件放在卡片列表、卡片分录中时，通过cardRowData就能获取到卡片的相关信息，包括卡片里的字段、控件，还有卡片行号 | ## 2.5 前端 KDApi 在 window 下面封装了一个对象`KDApi`，通过该对象可获取平台提供的自定义控件API，常用方法如下： ### 2.5.1 KDApi.register * 类型：`function` * 参数： * `type(String)` 自定义控件唯一标识，必须与schemaId的值一致 * `ctrl(Object)` 自定义控件对象，使用函数式声明，在运行时会生成实例 * 说明：将控件注册到平台中，该方法每个自定义控件必须调用。 * 用法： ```js // 创建控件对象 function MyComponent (model) { // ... } // 将控件注册到平台中 window.KDApi.register('schemaId的值', MyComponent) ``` ### 2.5.2 KDApi.loadFile * 类型：`function` * 参数： * `filePath(String|Array) `文件路径或者文件路径数组，支持相对路径 * `model(Object)` 控件model对象 * `callback(Function)` 回调方法 * 说明：动态加载`JS`、`CSS`文件 * 用法： ```js // 加载单个JS文件 window.KDApi.loadFile('./js/a.js', model, callback).then(function () { // do something callback() }) // 如多个文件没有先后依赖关系的，可以并行加载多个文件，如 window.KDApi.loadFile(['./js/a.js', './js/b.js', './css/c.css'], model, callback).then(function () { // do something callback() }) ``` ### 2.5.3 KDApi.getHTMLStringBytemplate * 类型：`function` * 参数： * `tpl(String)` HTML模板 * `data(object)` 生成HTML字符串所需要的数据对象 * 说明：通过HTML模板和数据，生成`HTML`字符串，可以赋值给`innerHTML` * 用法： ```js const tpl = ''const data = {name: '张三'} const result = window.KDApi.getHTMLStringBytemplate(tpl, data) // => '' ``` ### 2.5.4 KDApi.getTemplateStringByFilePath * 类型：`function` * 参数： * `filePath(String)` HTML模板文件路径，支持相对路径 * `model(Object)` 控件model对象， * `data(Object) `数据对象 * 说明：根据字符串模板的文件路径和数据，获取