mini-jq-tools

轻量级类 jQuery 语法的 DOM 操作工具集，提供统一、安全的 DOM API，所有方法均为静态方法。

内部按功能分文件管理：

• events.js：事件监听、解绑、Vue 风格事件名解析、事件清理器（MiniJqEventBinder）。
• props.js：DOM 属性、dataset、style、class、children 设置，继承事件能力。
• nodes.js：节点查询、追加、聚焦、移除和尺寸读取，继承属性能力。
• index.js：将 MiniJqNodes 以默认导出，是唯一对外入口。

继承关系：MiniJqNodes extends MiniJqProps extends MiniJqEvents。对外入口不额外包一层空类，也不重复代理方法。

使用

import $ from 'mini-jq-tools';

const button = $.createElement(document, 'button', {
  class: 'toolbar-button',
  text: '保存',
  '@click.prevent': () => save(),
});

API 参考

事件系统

| 方法 | 说明 | |------|------| | $.on(target, type, handler, options) | 绑定事件，返回解绑函数。非 EventTarget 时返回空函数。 | | $.off(target, type, handler, options) | 解绑事件。 | | $.bindEvents(target, events, defaultOptions) | 批量绑定 Vue 风格事件，如 { '@click.prevent': fn }，返回统一清理函数。 | | $.bindEventList(bindings) | 批量绑定事件列表，每个绑定项为 { target, type, handler, options }。 | | $.createCleanup(cleanups) | 将多个清理函数合并为一个统一清理函数。 | | $.createEventBinder() | 创建 MiniJqEventBinder 实例，用于集中管理事件生命周期（适用于组件销毁场景）。 |

事件名修饰符：

• 行为修饰符：prevent（阻止默认行为）、stop（阻止冒泡）、self（仅响应 target 自身事件）
• 选项修饰符：capture、once、passive

事件值支持三种格式：

'@click': handler                              // 函数
'@click': [handler, { capture: true }]         // 数组 [handler, options]
'@click': { handler: fn, options: {...} }      // 对象

MiniJqEventBinder

const binder = $.createEventBinder();

binder.on(target, 'click', handler, { capture: true });  // 绑定单个事件
binder.bind(target, { '@click.prevent': fn });           // 批量绑定
binder.bindAll([                                          // 绑定事件列表
  { target: el, type: '@keydown.enter', handler: fn },
]);
binder.cleanup();  // 一次性移除所有通过此 binder 绑定的事件

元素创建 & 属性设置

| 方法 | 说明 | |------|------| | $.createElement(documentRef, tagName, props, children) | 创建元素，设置属性，追加子节点。props 和 children 可选。 | | $.setProps(element, props) | 批量设置元素属性，自动区分 event / class / style / dataset / attrs / property。返回事件清理函数。 | | $.setProp(element, key, value) | 智能设置单个属性，根据 key 的类型自动路由到对应处理方法。 |

setProp 的 key 路由规则：

| key | 处理方式 | |-----|----------| | class / className | → setClass | | text / textContent | → setText | | html / innerHTML | → setHtml | | style | → setStyle | | dataset | → setDataset | | attrs | → setAttrs（批量设置 attribute） | | @eventName | 收集为事件，最终调用 bindEvents | | :propName | 强制作为 DOM property 设置 | | data-* / aria-* / role | → setAttr（attribute） | | 其他 | → setProperty（优先 DOM property，否则 attribute） |

Property 别名映射： for → htmlFor、readonly → readOnly、tabindex → tabIndex

Class 操作

| 方法 | 说明 | |------|------| | $.setClass(element, value) | 设置 className。支持 string、string[]、{ className: boolean } 对象格式。 | | $.addClass(element, ...classNames) | 添加 class，支持多参数和嵌套数组。 | | $.removeClass(element, ...classNames) | 移除 class，支持多参数和嵌套数组。 | | $.toggleClass(element, className, force) | 切换 class，可选 force 参数强制开关。 | | $.hasClass(element, className) | 检查是否包含某个 class。 |

Style 操作

| 方法 | 说明 | |------|------| | $.setStyle(element, style) | 设置样式。支持对象（自动 camelCase→kebab-case 转换）、字符串（cssText）、null/false（移除 style 属性）。 | | $.getStyleValue(element, name) | 读取 CSS 属性值（包括 CSS 自定义属性 --*）。 |

Dataset 操作

| 方法 | 说明 | |------|------| | $.setDataset(element, dataset) | 批量设置 dataset。 | | $.setData(element, key, value) | 设置单个 data 属性，自动处理含连字符的 key。 | | $.getData(element, key, fallback) | 读取 data 属性值，未找到时返回 fallback（默认 ''）。 | | $.removeData(element, key) | 移除 data 属性。 |

Attribute 操作

| 方法 | 说明 | |------|------| | $.setAttr(element, name, value) | 设置 attribute。null/undefined/false 时自动移除。true 时设为空字符串。 | | $.setAttrs(element, attrs) | 批量设置 attribute。 | | $.removeAttr(element, name) | 移除 attribute。 |

文本 & HTML

| 方法 | 说明 | |------|------| | $.setText(element, value) | 设置 textContent，null/undefined 时设为空字符串。 | | $.setHtml(element, value) | 设置 innerHTML，null/undefined 时设为空字符串。 | | $.setProperty(element, key, value) | 设置 DOM property，key 不存在于元素上时回退为 attribute。 |

节点操作

| 方法 | 说明 | |------|------| | $.querySelector(root, selector, fallback) | 安全查询单个节点，无效输入时返回 fallback（默认 null）。 | | $.querySelectorAll(root, selector) | 安全查询节点列表，无效输入时返回 []。 | | $.appendChild(parent, child) | 追加子节点，string/number 类型自动转为文本节点。 | | $.appendChildren(element, children) | 批量追加子节点，支持嵌套数组（自动拍平）。 | | $.getBoundingClientRect(element, fallback) | 读取元素尺寸，无效元素返回 fallback（默认零值冻结对象）。 | | $.focus(element, options) | 聚焦元素，返回是否成功。 | | $.remove(element) | 安全移除元素（优先 .remove()，回退 parentNode.removeChild()）。 |

注意事项

• 所有方法均为静态方法，无需实例化 $。
• 所有方法对无效输入（null、undefined等）均有安全防护，不会抛出异常。
• setProps 返回事件清理函数（若有绑定事件），其余事件方法也均返回清理函数。
• style 属性名支持 camelCase（自动转 kebab-case）和 CSS 自定义属性 --*。
• 子节点追加时 null、undefined、false 会被自动跳过。