McrbHttpClient.commfn.createEl命令式建 DOM

McrbHttpClient.commfn.createEl(tag, props, ...children) 是命令式创建 DOM 元素的工具函数,用来替代冗长的 document.createElement + setAttribute + appendChild 样板代码。一行调用即可构建一棵 DOM 树。

1.基础用法

McrbHttpClient.commfn.createEl(tag, props, ...children)

2.参数说明

参数名类型必填说明
tagstring是标签名,如 'div'、'button'、'img'
propsObject否属性、样式、dataset、事件等配置对象,可省略或传 null
...childrenNode | string | number | Array | null | false否子节点或文本,支持多个、支持嵌套数组、支持条件跳过

返回值:HTMLElement(创建好的 DOM 节点,但不会自动挂载到页面,需自己 appendChild)。

3.props 支持的配置项

key类型行为示例
styleObjectObject.assign(el.style, val){ width: '200px', backgroundColor: '#fff' }
datasetObjectObject.assign(el.dataset, val){ id: '1001' } → data-id="1001"
onXxxFunctionaddEventListener('xxx', val){ onClick: fn } → 绑定 click
className/classstringel.className = val{ className: 'card' }
textstringel.textContent = val{ text: 'hello' }
htmlstringel.innerHTML = val(⚠️ 注意 XSS){ html: '<b>hi</b>' }
其他任意 keystring | numberel.setAttribute(key, val){ type: 'button', disabled: true }
跳过规则:val == null 或 val === false 的属性会被自动跳过,方便条件渲染。

4.children 支持的写法

写法说明
createEl('div', {}, 'hello')字符串 → 自动转文本节点
createEl('div', {}, 100)数字 → 自动转文本节点
createEl('div', {}, childNode)Node → 直接 append
createEl('div', {}, 'a', 'b', 'c')多个子节点
createEl('div', {}, [n1, n2, n3])数组 → 自动拍平
createEl('div', {}, [n1, [n2, [n3]]])嵌套数组 → 递归拍平(flat(Infinity))
createEl('div', {}, null)null → 跳过
createEl('div', {}, false)false → 跳过(常用于 cond ? el : false)
createEl('div', {}, undefined)undefined → 跳过
createEl('div')无子节点,创建空元素

5.事件绑定

createEl('button', { onClick: fn }, 'click') // → addEventListener('click', fn)

createEl('div', { onMouseenter: fn }, 'hover') // → addEventListener('mouseenter', fn)

createEl('input', { onInput: fn, onChange: fn }) // 多事件

createEl('div', { onDblclick: fn }, '双击') // → dblclick

规则:key.slice(2).toLowerCase() → 事件名。所以 onClick、onclick、onCLICK 都转成 click,大小写随意。

6. 样式写法

// ✅ 对象写法(推荐)

createEl('div', { style: { width: '200px', height: '100px', backgroundColor: '#f0f7ff' } })

// ✅ 字符串写法(等价,但不如对象可读)

createEl('div', { style: 'width:200px;height:100px;' })

对象 key 用驼峰:backgroundColor 而不是 background-color;marginTop 而不是 margin-top。

7. dataset 写法

// ✅ 对象写法

createEl('div', { dataset: { id: '1001', type: 'user' } })

// 渲染为:<div data-id="1001" data-type="user">

// 取值
el.dataset.id // '1001'
el.dataset.type // 'user'

 

dataset 的 key 不要写 data- 前缀,{ id: '1001' } 会自动生成 data-id。

8. text vs html vs 子节点

写法行为安全性
子节点 'hello'自动 createTextNode✅ 安全
{ text: 'hello' }el.textContent = 'hello'✅ 安全
{ html: '<b>hi</b>' }el.innerHTML = ...⚠️ XSS 风险
安全规则:用户输入 → 用子节点或 text,绝不走 html;只有框架内部已知安全的 HTML 字符串才用 html。

如果同时传了 text 和 children,children 会追加在 text 后面:createEl('div', { text: 'A' }, 'B') → 结果 AB。一般二选一即可。

9. 挂载说明

createEl 只创建,不挂载。创建后需自己 appendChild / append:

var box = createEl('div', {}, 'hello')

// 挂载方式一

document.body.appendChild(box)

// 挂载方式二(推荐,可挂多个)

document.body.append(box)

// 挂载到指定容器

document.getElementById('app').appendChild(box)

10.常见使用场景与示例

https://mhc.ixiera.com/html/componentDemo/demo_creatEl.html

本文档来自—microbee-http 丨 软件开发框架平台