传参处理

Edge主题中所有组件都支持 DOM 传参，部分组件使用 new 构造语法的时候支持 JS 传参，具体表现为下面这几种。

原生或自定义 HTML 属性

原生 HTML 属性

LuLu UI 中非常多的组件是基于原生 HTML 元素构建的，对于这类组件，参数的改变是通过设置原生的 HTML 属性值实现的。

例如表单验证规则、日期或滑杆的选择范围，例如下面是一个不限制日期范围的输入框：

<input type="date" id="date" is="ui-datetime">

实时效果如下所示：

当我们希望只能选择今天及其之后的日期，就可以设置 min 属性为今天的日期（需要是 0000-00-00 格式），例如： 

date.setAttribute('min', new Date().toArray().join('-'));

实时效果如下所示（点击查看可选择的日期范围）：

toArray()方法是 Datetime.js 内置方法，可以将 Date 对象转换成补 0 后的[年, 月, 日]数组格式。

自定义 HTML 属性

所谓自定义 HTML 属性，指的是可以影响 UI 组件的样式，但是属于开发者自定义的属性，自定义 HTML 属性多出现在自定义元素上，例如分页、下拉、选项卡切换等。

拿下拉自定义元素 <ui-drop> 举例，比方说有下面这段 HTML 代码：

<ui-drop id="drop" target="t1">点击我</ui-drop>
<textarea id="t1" disabled hidden>目标元素1</textarea>
<textarea id="t2" disabled hidden>目标元素12</textarea>
点击我

其中的 target 属性就属于自定义 HTML 属性，是组件开发者自己定义的一个属性规则。此时，如果使用者希望改变下拉按钮对应的展示元素，只需要修改 target 属性值即可，如下所示：

drop.setAttribute('target', 't2');

此时的效果如下所示，显示的会是“目标元素2”：

点击我

HTML 属性参数合集

下表整理了各个 UI 组件都可以使用哪些原生 HTML 属性进行参数设置。

组件名称 原生属性 自定义属性 含义说明
Select下拉 selected、value -
  • selected 设置在 <option> 元素上，表示选中项。
Range范围选择 min、max、value、step data-tips、multiple、from、to、range、vertical、reverse
  • data-tips 表示黑色提示信息；
  • reverse 表示黑色提示信息是否反方向展示；
  • multiple 表示是否是区域范围选择；
  • from、to、range 表示区域范围选择中的起止区域；
  • vertical 表示是否是垂直范围选择。
Color颜色选择 type、value -
  • type 属性值是 'color-opacity' 的时候支持 RGBA 色值设置。
Datetime日期选择 type、min、max、value、step -
  • step 主要出现在 time 类型的时间选择中，可以影响时间选择是精确到秒还是分钟，以及会影响上下快捷键选择日期的值。
Datalist数据列表 list、results -
  • list 属性值是对应的 <datalist> 元素的 id，指代数据源；
  • results 表示显示的最大列表个数。
Dialog弹框 open -
  • open 是布尔属性，表示弹框显示与否。
Tips提示 title reverse、align
  • title 表示提示信息；
  • reverse 是布尔属性值，表示是否反方向提示；
  • align 表示指定其他的定位方位。
ErrorTip出错提示 - -
LightTip轻提示 - open、type、time
  • open 是布尔属性，表示轻提示元素显示与否；
  • type 表示提示的类型，例如 'success'、'error'、'warning' 等；
  • time 表示轻提示出现的时间。
Pagination分页 - total、current、per、mode、href
  • total 表示分页总数；
  • current 表示当前分页数；
  • per 表示每页的数量；
  • mode 表示长分页还是短分页；
  • href 表示点击分页刷新的页面地址。
Drop下拉 - target、eventtype、position、open
  • open 是布尔属性，表示下拉元素显示与否；
  • target 表示目标下拉元素的 id；
  • eventtype 表示下拉交互的事件类型；
  • position 表示定位方位。
Validate表单验证 type、min、max、step、required、pattern、maxlength minlength -
Tab切换 - open、name、target、history、eventtype、autoplay
  • open 是布尔属性，表示选项卡元素激活态与否；
  • target 表示目标选项卡面板元素的 id；
  • eventtype 表示选项卡交互的事件类型；
  • history 表示选项卡切换发生时候 URL 地址是否进行记录；
  • autoplay 表示选项卡定时播放执行的时间间隔；
  • name 表示分组。

基于 DOM 对象传参

Edge 主题中组件即 DOM 本身，因此，给组件传参其实就是通过 DOM 元素进行参数传递。

在Edge 主题中，无论是原生组件、自定义元素组件还是内置自定义元素组件，均在主体 DOM 元素上扩展了一个名为 params 的对象，通过改变此 params 对象中的参数值，可以达到给组件传参的目的。

因为有些参数不是单纯的字符串，基于 HTML 属性传参这种方式是受限制的，拿 Datalist 数据列表中的邮箱自动补全功能举例，此功能需要两个重要的参数，一个是邮箱列表，是个数组，一个是过滤方法，是个函数，使用 HTML 属性表示是非常受限的，因为 LuLu UI 对于业务代码是无侵入的，无法基于字符属性和业务中具体的逻辑关联，因此，只能基于 DOM 对象进行传参。

例如：

邮箱：<input type="email" id="e1" class="ui-input" size="30" is="ui-datalist">

此时输入框输入任何内容都不会有列表显示的，因为缺少对应的数据源，如下所示：

邮箱：

此时，就可以直接对 e1.params 对象设置参数实现目标效果，例如：

e1.params.data = ['qq.com', 'gmail.com', '126.com', '163.com'];
e1.params.filter = (data, value) => {
    value = value.split('@')[0];

    if (!value) {
        return [];
    }

    return data.map(function (domain) {
        return {
            value: value + '@' + domain
        };
    });
};

此时输入文字就可以看到邮箱匹配功能了：

邮箱：

在本例中，也可以使用 setParams 方法批量设置参数，示意如下：

// 邮箱匹配
e1.setParams({
  data: ['qq.com', 'gmail.com', '126.com', '163.com'],
  filter: (data, value) => {
      value = value.split('@')[0];

      if (!value) {
          return [];
      }

      return data.map(function (domain) {
          return {
              value: value + '@' + domain
          };
      });
  }
});

下表为整理的所有组件 params 对象支持的可选参数。

组件名称 params 可选参数 支持 setParams 方法 含义说明
Select下拉 - - 无可选参数
Range范围选择 - - 无可选参数
Color颜色选择 color [Object] -

  • color 参数表示基础颜色选择的基础色和固定色数组，对象结构示意：

    color: {
    basic: [],
    basicPreset: [],
    fixed: []
}
Datetime日期选择 type [String] -
  • type 参数值为日期选择的类型，此参数只读，不建议进行设置。
Datalist数据列表 index [Number]
width [Number|String|Function]
placeholder [String|Boolean]
twice [Boolean]
encode [Boolean]
data [Any]
filter [Function]
 ✔
  • index 参数表示选中列表项的索引；
  • width 参数表示列表宽度，支持任意单位，也支持 Function 类型，用来每次展示的宽度需要计算的场景；
  • placeholder 参数表示聚焦的时候，输入框内容是否以占位符方式显示；
  • twice 参数是是否二次点击的标志量；
  • encode 参数表示列表内容是否 HTML 转义；
  • data 参数表示列表展示内容，格式任意，最终都会转换成 Function 类型；
  • filter 参数是源数据过滤函数，可以实现各类列表匹配效果。
Dialog弹框 title [String]
content [String|Node]
buttons [Array]
width [Number|String]
height [Number|String]
 ✔ Dialog 弹框的参数设置是即时响应的。
  • title 参数表示弹框标题；
  • content 参数表示弹框主体内容；
  • buttons 参数表示弹框按钮；
  • width 参数表示弹框尺寸；
  • height 参数表示弹框高度。
Tips提示 - - 无可选参数
ErrorTip出错提示 unique [Boolean] -
  • unique 参数表示出错提示是否唯一显示。
LightTip轻提示 - - 无可选参数
Pagination分页 - - 无可选参数
Drop下拉 width [Number|String]
offsets [Object]
position [Boolean]
edgeAdjust [Boolean] 		✔
  • width 参数表示下拉浮层的元素；
  • offsets 参数表示下拉浮层的偏移大小；
  • position 参数表示定位的的方位；
  • edgeAdjust 参数表示是否进行边缘调整。
Validate表单验证 - - Validate是实例对象，参数不在 DOM 上
Tab切换 name [String]
target [String]
history [Boolean]
eventtype [String]
autoplay [Number] 		✔ 所有参数只读，作用较弱
Table列表 ajax [Object]
form [Element]
list [Array]
page [Element]
parse [Function] 		✔
  • ajax 参数表示列表数据请求时候的地址和参数等；
  • form 参数表示关联的表单的请求和验证数据；
  • list 参数表示每页数量的下拉的列表值；
  • page 参数表示分页相关的数据；
  • parse 参数是对请求返回值进行处理的方法。

以上参数都包含子参数，更详细的含义参见文档。
Form表单 validate [Object]
data [Object]
avoidSend [Function] 		-
  • validate 是表单验证实例对象；
  • data 是表单提交时候附加的额外数据；
  • avoidSend 是表单提交之前组织提交的逻辑处理。

element 对象参数

几乎所有的 HTML 组件 DOM 对象上都暴露了一个名为 element 的对象，这个对象中的属性值全部都是和当前 DOM 元素有关联的元素，对于高级应用场景，可能需要到，详见各个组件对应的文档。

callback 对象参数

在 Pure 主题中，callback 对象上会暴露所有的回调方法，但是在 Edge 主题中，虽然极个别组件依然有 callback 对象，但是基本上都只是形式而已，请全部使用 DOM 事件代替。

JavaScript 函数传参

JS 传参用在使用 new 语法进行组件构造的时候。

在Edge主题中，所有自定义元素组件，均暴露了可供全局构造的对象，包括 Dialog 弹框、Tips 提示、ErrorTip 出错提示、LightTip 轻提示、Drop 下拉、Validate 表单验证、Tab 切换、Table 列表和Form 表单，构造对象的名称就是各个组件的前缀称呼，首字母大写。

例如 Tips 提示，可以使用下面的语法进行参数传递：

new Tips(trigger, content, options);

JS 传参和 DOM 传参是同时作用于 UI 组件的，还是拿 Tips 组件举例，如果提示元素自身就有 title 属性，则 content 参数是可以省略的。

例如：

<button type="primary" id="tip" is="ui-button" title="感谢关注LuLu UI！">Hover Me</button>
new Tips('tip', {
    align: '6-8'
});

实际效果如下，鼠标经过按钮，会看到黑色提示信息在右侧显示：

各个组件具体的参数值可以参见各个文档，基本上，所有这些参数都有对应的 HTML 属性相呼应。

本页贡献者：

zhangxinxu