自定义动态控件

1 概述

lczExcel拥有二次开发的能力，用户可基于报表JS脚本+扩展控件实现根据其他单元格来动态控制某个单元格的控件类型，目前支持的控件类型包括：单行文本输入框、数值输入框、日期控件、下拉控件、树控件。

本文档适合的读者：
● 掌握了一定的Html、JavaScript、CSS基础知识；
● 希望通过乐创者报表扩展控件实现动态控件功能的用户。

2 典型案例

简单案例，如下图所示：

预期E5单元格的控件类型可以跟随D5单元格动态构建。
即：

• 如果D5扩展出来的单元格值是数值型，则E5同行的单元格显示为数值输入框，并能指定数值相关的控制，如最大值、最小值等；
• 如果D5扩展出来的单元格值是字符型，则E5同行的单元格显示为单行文本输入框，并能指定数值相关的控制，如最大长度、最小长度等；

3 设计实现步骤

3.1 引入报表JS脚本

点击报表“JS脚本”弹出JS脚本设置窗口，进行JS文件引用，也可进行JS脚本编辑：

extendEditor.js的内容格式为：

var extendEditorOptions = {
    "文本输入框" : {
        "type" : "input",
        "show" : true, //控件是否直接显示，true:直接显示（适合于控件不是特别多的情况）；false：点击单元格时显示，焦点离开后控件消失
        "defaultValue" : {  //默认值
                "value" : "",  //值
                "calculated" : false  //值是否表达式
        },
        "input" : {
        },
        "dataRule" : {
            "dataType" : 1,
            "allowEmpty" : false,  //是否允许为空
            "minLen" : 1,
            "maxLen" : 100
        }
    },
    "数值输入框" : {
        "type" : "input",
        "show" : true,
        "defaultValue" : {
                "value" : "",
                "calculated" : false
        },
        "input": {
        },
        "dataRule":{
            "dataType" : 3,
            "allowEmpty" : false,
            "minValue" : 1,     //最小值
            "maxValue" : 100,   //最大值
            "allowMinus" : true, //是否允许输入负数
            "decimalCount" : 2   //支持的小数位数
        }
    },
    "日期" : {
        "type" : "date",
        "show" : true,
        "defaultValue" : {
               "value" : "",
               "calculated" : false
        },
        "date": {
            "formatPatten": "yyyy-MM-dd"
        }
    },
    "下拉框" : {
        "type" : "select",
        "show" : true,
        "defaultValue" : {
                "value" : "0", //编码值
                "displayValue" : "否", //显示值
                "calculated" : false //编码值是否表达式
        },
        "select": {
            "allowInput" : true,
            "emptyItemTitle" : "",
            "maxItemCount" : 1000,
            "dataset" : {
                "adapterName" : "数据源名称",
                "codeField" : "编码字段",
                "nameField" : "名称字段"
             }
        }
    },
    "树" : {
        "type" : "tree",
        "show" : true,
        "defaultValue" : {
                "value" : "", 
                "displayValue" : "",
                "calculated" : false
        },
        "dataRule" : {
            "dataType" : 1,
            "allowEmpty" : false, //是否允许为空
            "minLen" : 1,
            "maxLen" : 100
        },
        "tree": {
            "dataset": {
                "adapterName" : "【必填】数据源名称",
                "codeField" : "【必填】编码字段",
                "nameField" : "【必填】名称字段",
                "parentField" : "父编码字段",
                "valueField" : "取值字段",
                "leafField" : "叶子字段",
             },
             "multiSelect": false, //允许选择多个值,缺省：true
             "rootNodeValue": "", //根节点父编码值
             "selectRange" : {
                 "rootNode" : false, //根节点是否允许选择
                 "trunkNode" : false, //枝节点是否允许选择
                 "leafNode" : true   //叶子节点允许选择
             },
             "selectMode" : 0 , //允许多选时，选择模式，0 - 当前节点(默认)，1 - 当前节点及子孙节点，2 - 仅子孙节点，3 - 上下递归
             "loadMode" : 0, //获取树数据时，数据加载模式，0 - 一次性加载，1 - 逐层加载
             "expandMode" : 0, //树渲染后，节点展开模式，0 - 不展开，1 - 根节点展开，2 - 全部展开
             "window" : {
                 "title" : "标题",
                 "width" : 640,
                 "height" : 480
             }
        }
    }
};

dataType : 1:字符型， 2：整型， 3：数值型， 4：日期

1、extendEditorOptions中的控件定义范围可按照需要的类型进行配置；
2、为防止js缓存，可以在引入的js文件后面加一个版本号，如上图中的”?v=1”，js文件内容变化后，调整v的值即可；
3、同一类控件，如果数据规则不同，可以配置多个。例如：假设有两个不同的数值（金额和数量），可以定义两种控件，如：

var extendEditorOptions = {
    "金额控件" : {
        "type" : "input",
        "show" : true,
        "defaultValue" : {
                "value" : "",
                "calculated" : false
        },
        "input": {
        },
        "dataRule":{
            "dataType" : 3,
            "allowEmpty" : false,
            "minValue" : 1,
            "maxValue" : 100000,
            "allowMinus" : false,
            "decimalCount" : 2
        }
    },
    "数量控件" : {
        "type" : "input",
        "show" : true,
        "defaultValue" : {
                "value" : "",
                "calculated" : false
        },
        "input": {
        },
        "dataRule":{
            "dataType" : 3,
            "allowEmpty" : false,
            "minValue" : 1,
            "maxValue" : 100,
            "allowMinus" : false,
            "decimalCount" : 0
        }
    }
}

3.2 设置单元格别名

选中动态控件所在单元格，在单元格属性的“名称”中设置一个有业务含义的值（为此单元格起个名字，方便后续的JS脚本中能找到这个单元格）：

3.3 设置扩展控件

选中动态控件所在单元格，在顶部工具栏【控件】-》【高级控件】中点击“扩展控件”：


在扩展控件弹窗中点击“事件配置”：

• 添加一个“初始化后”事件，选择“JS事件”；
• 添加相关的参数（如上图所示，添加一个“valueType”参数，从D5单元格获取值）；
• 添加JS脚本

  ER.widget.extend(this, {
    type: 'component',
    init: function(element, row, col) {
        //根据valueType，获取控件配置型
        var extendEditorOption = extendEditorOptions['金额控件'];
        if(1 == valueType) {
            extendEditorOption = extendEditorOptions['数量控件'];
        }
        return this.showCellEditor(extendEditorOption,"值",row,"Sheet1")
    }
  })