common.js（sx 函数库）API 清单

src/common.js 是用户上传的 sx 函数库（xueluo.cn，2019-11-05 创建，2023-07-21 更新），全局名是 window.sx 与 window.SX（同一个函数）。

它不是 jQuery。 它提供的是一套自定义的 DOM 操作 API，思路和 jQuery 类似但命名与签名都不同。飞立（plui）的所有交互组件都基于它的真实 API 编写，不引入 jQuery。

1. 基本用法

// sx(选择器) 返回一个「集合对象」：有 length，有下标，方法是原型上的
sx('p');                       // 所有 p
sx('#id');                     // 指定 id
sx('.cls', container);         // 在 container 内查找
sx(document.getElementById('x'));   // 直接包 DOM 节点
sx(document.querySelectorAll('p')); // 包 NodeList
sx(function () { /* DOM 就绪后执行 */ });

// 静态方法也可以直接用
sx.each(nodeList, fn);
sx.ajax({ url: '...' });

集合对象上可用的实例方法（sx.init.prototype）：

方法说明与 jQuery 的差别
each(fn)遍历回调是 (i, 元素, 集合, 总数)，与 jQuery 一致
i(n)取第 n 个元素jQuery 用 eq()
find(name)查找后代jQuery 同名
children(name) / childrens()直接子元素 / 全部后代childrens() 是 jQuery 没有的
parent() / parents()父元素 / 所有祖先jQuery 同名
siblings() / prev() / next()兄弟节点jQuery 同名
index()在父元素中的序号jQuery 同名
isChildren(el)是否为直接子元素jQuery 无
addCss(name)加类名jQuery 是 addClass()
delCss(name)删类名jQuery 是 removeClass()
hasCss(name)判断类名语义是「列出的类名必须全部存在」，不是 jQuery 的 hasClass()
toggleCss(a, b, fnA, fnB)两个类名互换jQuery 无直接对应
attr(name[, value])读 / 写属性读不到时返回 false，不是 undefined
delAttr(name)删属性jQuery 同名
style(name[, value]) / style(obj)读写行内样式jQuery 是 css()
getCss(attr)读计算样式jQuery 是 css()
html([v])读写 innerHTMLjQuery 同名
val([v])读 / 写表单值只作用于第一个元素
form()收集表单值成对象jQuery 无
append / prepend / before / after插入节点jQuery 同名
clone()深拷贝jQuery 同名
del()移除节点jQuery 是 remove()
on(type, fn[, bool])绑定事件回调是 (i, 元素, 事件)；没有 off()
click(fn)绑定点击回调是 (事件, i)，与 on 的参数顺序不一致
show / hide / toggle显隐jQuery 同名
fadeIn / fadeOut / fadeToggle淡入淡出jQuery 同名
slideDown / slideUp / slideToggle滑动jQuery 同名
offset()相对位置jQuery 同名

静态方法（挂在 sx 上）：

分类方法
基础each、isFunction、isWindow、isArrayLike、toDom、c、sp（阻止冒泡）、pd（阻止默认）、isMobile、isJson
取值getUrl、getCss、getDisplay、hasStyle、html、val、attr、offset、index、data、storage、localData、time、obj2str、str2obj
设置style、attr、addCss、delCss、hasCss、toggleCss、html、val、setDisplay、opacity、loadJs
DOMappend、prepend、before、after、find、children、childrens、siblings、prev、next、parent、parents、clone、del、dom2arr、arr2dom、form
事件on、click、keydown、scroll、scrollAni、page
动画show、hide、toggle、fadeIn、fadeOut、fadeToggle、slideDown、slideUp、slideToggle
网络ajax、upload、pjax
界面pop（轻提示）、alert（模态）、prompt、confirm
其他drag、ready、start、CONF、href、jump、import、delArticle、reply、cancelReply、delStorage、delData、delLocalData

2. 与 jQuery 的对应关系

jQuery 写法sx 等价写法注意事项
$(sel)sx(sel)一致
$(el) / $(nodeList)sx(el)一致
$(fn)sx(fn)都会在 DOM 就绪后执行
$(sel).each(fn)sx(sel).each(fn)一致
$(sel).on('click', fn)sx(sel).on('click', fn)回调参数顺序不同：sx 是 (i, el, e)，jQuery 是 (e, el)
$(sel).click(fn)sx(sel).click(fn)sx 的 click 回调是 (e, i)，和它的 on 不一致
$(sel).addClass('x')sx(sel).addCss('x')名字不同
$(sel).removeClass('x')sx(sel).delCss('x')名字不同
$(sel).hasClass('x')sx(sel).hasCss('x')语义不同：sx 要求全部类名同时存在
$(sel).attr('x')sx(sel).attr('x')读不到时 sx 返回 false
$(sel).css('x', v)sx(sel).style('x', v)名字不同；读计算样式用 getCss()
$(sel).html()sx(sel).html()一致
$(sel).val()sx(sel).val()一致，只取第一个元素
$(sel).find(x)sx(sel).find(x)一致
$(sel).eq(2)sx(sel).i(2)名字不同
$(html)sx.toDom(html) / sx.c('div')sx 不能用字符串直接造节点
$.ajax({...})sx.ajax({...})返回 Promise，无全局 $ 别名
$(sel).closest(x)无用原生 el.closest(x)
$(sel).off()无无法解绑事件，sx 只能靠 el.onclick = null 覆盖点击绑定

3. common.js 没有的 jQuery 能力

  1. off() / 事件解绑：on() 内部是 addEventListener，没有任何移除入口。所以 plui 的事件全部只在初始化时绑定一次，不做解绑；重复初始化靠幂等处理。
  2. closest()：只有 parent() 与 parents()，plui 用原生 Element.closest()。
  3. 单类名判断：hasCss() 是「全部存在」语义，判断「有没有某一个类」用原生 classList.contains() 更准确。
  4. prop()、data() 的 DOM 语义：sx.data() 实际是 sessionStorage 包装（sx.storage(sessionStorage, ...)），跟 jQuery 的 data() 完全不是一回事。
  5. filter() / map() / not() / is() / eq()（i() 部分等价）。
  6. wrap() / unwrap() / detach()。
  7. .animate() 通用动画系统：只有 fade / slide 两组预设。
  8. $.trim / $.isNumeric / $.parseJSON 等小工具。
  9. HTML 字符串直接转节点：sx.toDom(html) 会先塞进临时 div 再取 childNodes。
  10. 无全局 $ 别名：只有 sx 与 SX。

4. plui.js 里怎么用它

场景用什么原因
选择元素、限定作用域sx(sel) / sx(sel, root)原生 querySelectorAll 封装
遍历集合sx.each(el, fn)回调签名与 jQuery 一致
绑定事件（全局委托）sx.on(document, 'click', fn)内部是 addEventListener，冒泡正常
加 / 删类名sx.addCss / sx.delCss框架统一走 sx
单类判断与取反原生 classList.containssx.hasCss 语义是「全部存在」，不适合单类判断
找最近的祖先原生 el.closest(sel)sx 没有 closest
读 data 属性原生 getAttributesx 的 attr 读不到时返回 false，需要区分「没有」与「值为 false」
创建元素sx.c('div')sx 的节点工厂
键盘监听原生 addEventListener('keydown')sx.keydown() 有缺陷：它内部用 sx.on 的回调当事件对象，实际拿到的是索引，导致 e.keyCode 恒为 undefined，不能用于 Esc 关闭
焦点管理原生 focus()sx 没有对应方法

5. common.js 的自动副作用（重要）

common.js 在 DOM 就绪后会自动执行 sx.start() 与一段配置拉取逻辑，这些行为与页面无关但会真实发生：

自动行为说明对 plui 的影响
sx('.back').click(...)给 .back 元素绑后退plui 不使用 .back 类名
sx('.tab') 自动选项卡查找 .tab-menu a 与 .tab-content，用 active 类切换plui 的标签页叫 .plui-nav-tabs，类名不同，不会被它接管
sx('.menu a') 改写 className直接 el.className = 'active' 或 ''，会覆盖掉 a 元素原有的 classplui 不使用 .menu 类名
.header .icon-menu 切换 .sidebar给 .sidebar 加删 sidebar-openplui 不使用这些类名
POST 当前页 getConf=1向当前页面地址发一个 POST，取站点配置在 ui.phli.cn 上会拿到 HTML 页面内容（不是 JSON），不会报错，但 sx.CONF 里存的是 HTML 字符串；plui 不使用 sx.CONF
sx('#pjax-content') 局部刷新若页面存在该 id 会接管plui 不使用该 id

因此 plui 全部使用 plui- 前缀的类名，既避免与 common.js 的自动逻辑冲突，也避免与页面里其他第三方样式撞名。

6. 版本与授权

文件头保留了原库的版权声明（该版权完全归 xueluo.cn 官方所有，可转载使用和学习，但请务必保留版权信息）。plui 只做只读引用，未改动其内容。

本页由 build/build-docs.mjs 从同名 Markdown 生成，请修改 .md 后重新生成，不要手工编辑本文件。