XPUI 框架文档

XPCMS 自研 UI 组件库，11个CSS文件 + 22个JS文件，纯原生JS+CSS，无第三方依赖。

一、引入方式

XPUI 框架由 11 个 CSS 文件 和 22 个 JS 文件 组成，统一存放在 /public/static/xpui/ 目录下。

1.1 完整引入（推荐）

在页面 <head> 中引入 CSS，在 </body> 前引入 JS：

<link rel="stylesheet" href="/static/xpui/css/xp-all.css">
<script src="/static/xpui/js/xp-all.js"></script>

1.2 按需引入

如果只需要部分组件，可以单独引入对应的 CSS 和 JS 文件。所有文件清单如下：

类型	文件名	说明
CSS	xp-base.css	基础重置、CSS变量、全局样式
CSS	xp-layout.css	布局系统（容器/栅格/间距）
CSS	xp-general.css	通用组件（按钮/颜色/图标/动画）
CSS	xp-nav.css	导航组件（顶部/侧边/面包屑/分页）
CSS	xp-form.css	表单组件（输入框/选择器/开关）
CSS	xp-table.css	表格组件
CSS	xp-panel.css	面板/卡片/标签页容器
CSS	xp-interactive.css	交互组件（弹窗/下拉/提示）
CSS	xp-interactive-advanced.css	高级交互（上传/滑块/评分）
CSS	xp-display-advanced.css	高级展示（代码预览/树形/穿梭框）
CSS	xp-all.css	全部CSS合集
JS	xp-core.js	核心库（请求/工具/DOM/事件总线）
JS	xp-toast.js	消息提示
JS	xp-modal.js	弹窗管理
JS	xp-form.js	表单提交与验证
JS	xp-table.js	表格复选框与列表管理
JS	xp-upload.js	文件上传
JS	xp-dropdown.js	下拉菜单
JS	xp-tabs.js	标签页切换
JS	xp-code-preview.js	代码预览与语法高亮
JS	xp-color-picker.js	颜色选择器
JS	xp-datepicker.js	日期选择器
JS	xp-slider.js	滑块组件
JS	xp-rate.js	评分组件
JS	xp-carousel.js	轮播图
JS	xp-tree.js	树形结构
JS	xp-tree-table.js	树形表格
JS	xp-transfer.js	穿梭框
JS	xp-pagination.js	分页组件
JS	xp-template.js	模板引擎
JS	xp-infinite-scroll.js	无限滚动
JS	xp-utils.js	工具函数集
JS	xp-all.js	全部JS合集

1.3 依赖说明

XPUI 图标系统依赖 Font Awesome 5，需在引入 XPUI 之前加载：

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css">

⚠ 注意：除 Font Awesome 外，XPUI 不依赖任何第三方 JS/CSS 框架（如 jQuery、Bootstrap、Layui 等），请勿混用。

二、xp-base.css —— 基础重置与全局样式

xp-base.css 是 XPUI 的底层基石，包含 CSS 变量定义、全局重置样式和通用工具类，所有其他 CSS 文件均依赖此文件。

2.1 CSS 变量（设计令牌）

所有颜色、圆角、阴影、间距均通过 CSS 变量定义，方便全局统一调整：

分类	变量名	默认值/说明
主色调	--xp-primary	#10b981（翡翠绿，品牌色）
	--xp-primary-hover	#059669（悬停加深）
	--xp-primary-active	#047857（点击更深）
	--xp-primary-light	#d1fae5（浅色背景）
	--xp-primary-bg	#ecfdf5（极浅背景）
功能色	--xp-success	#10b981（成功绿）
	--xp-warning	#f59e0b（警告橙）
	--xp-danger	#ef4444（危险红）
	--xp-info	#3b82f6（信息蓝）
	--xp-gray	#6b7280（中性灰）
文字色	--xp-text-primary	#1f2937（主要文字）
	--xp-text-regular	#374151（常规文字）
	--xp-text-secondary	#6b7280（次要文字）
	--xp-text-placeholder	#9ca3af（占位符）
	--xp-text-disabled	#d1d5db（禁用文字）
边框	--xp-border-color	#e5e7eb（默认边框）
	--xp-border-color-light	#f3f4f6（浅边框）
	--xp-border-color-dark	#d1d5db（深边框）
圆角	--xp-radius-sm	4px（小圆角）
	--xp-radius	6px（默认圆角）
	--xp-radius-lg	8px（大圆角）
	--xp-radius-xl	12px（超大圆角）
	--xp-radius-full	9999px（全圆角/胶囊）
阴影	--xp-shadow-sm	0 1px 2px rgba(0,0,0,.05)
	--xp-shadow	0 1px 3px rgba(0,0,0,.1)
	--xp-shadow-md	0 4px 6px rgba(0,0,0,.1)
	--xp-shadow-lg	0 10px 15px rgba(0,0,0,.1)
背景	--xp-bg-page	#f9fafb（页面背景）
背景	--xp-bg-white	#ffffff（白色背景）

2.2 全局重置

xp-base.css 自动重置所有元素的默认内外边距、统一盒模型为 border-box、设置默认字体和行高。无需手动编写任何重置代码。

2.3 使用示例

// 使用 CSS 变量自定义主题色（在引入 xp-base.css 之后定义）
<style>
:root {
    --xp-primary: #6366f1;      /* 改为紫色主题 */
    --xp-primary-hover: #4f46e5;
    --xp-primary-active: #4338ca;
    --xp-primary-light: #e0e7ff;
    --xp-primary-bg: #eef2ff;
}
</style>

三、xp-layout.css —— 布局系统

提供容器、栅格、Flex 布局、间距等核心布局能力。

3.1 容器

Class	说明	典型宽度
xp-container	固定宽度容器，水平居中	1200px（响应式自适应）
xp-container-fluid	全宽容器，始终100%宽度	100%

<div class="xp-container">
    <!-- 内容自动限制在1200px内并居中 -->
</div>

<div class="xp-container-fluid">
    <!-- 内容撑满全宽 -->
</div>

3.2 栅格系统

基于 Flexbox 的 12 列栅格系统，用法简洁：

Class	说明
xp-row	栅格行容器，flex布局
xp-col-1 ~ xp-col-12	栅格列，等分12列。xp-col-6 = 50%宽度
xp-col-auto	自适应宽度列

<div class="xp-row">
    <div class="xp-col-4">左侧 33.3%</div>
    <div class="xp-col-8">右侧 66.6%</div>
</div>

<div class="xp-row">
    <div class="xp-col-3">25%</div>
    <div class="xp-col-3">25%</div>
    <div class="xp-col-3">25%</div>
    <div class="xp-col-3">25%</div>
</div>

3.3 Flex 布局工具类

Class	对应 CSS	说明
xp-flex	display: flex	弹性布局
xp-flex-col	flex-direction: column	垂直排列
xp-flex-wrap	flex-wrap: wrap	允许换行
xp-flex-center	justify-content: center; align-items: center	水平垂直居中
xp-flex-between	justify-content: space-between	两端对齐
xp-flex-1	flex: 1	弹性填充剩余空间

四、按钮组件（xp-general.css）

按钮组件位于 xp-general.css，提供多种语义变体和尺寸。

4.1 按钮变体

按钮样式展示

Class	说明	使用场景
xp-btn	基础按钮（必须）	所有按钮的基类
xp-btn-primary	主色调按钮（绿色背景白字）	主要操作：保存、提交、确认
xp-btn-default	默认按钮（白色背景边框）	次要操作：取消、返回
xp-btn-danger	危险按钮（红色）	删除、清空等不可逆操作
xp-btn-warning	警告按钮（橙色）	需谨慎的操作
xp-btn-info	信息按钮（蓝色）	信息类操作
xp-btn-success	成功按钮（深绿色）	审核通过、发布等正向操作

4.2 按钮尺寸与形态

Class	说明
xp-btn-sm	小尺寸按钮（紧凑场景）
xp-btn-lg	大尺寸按钮（突出操作）
xp-btn-block	块级按钮（100%宽度）
xp-btn-loading	加载中状态（显示旋转图标+禁用点击）
disabled	原生 disabled 属性，50%透明度+禁止点击

4.3 代码示例

<!-- 带图标的按钮 -->
<button class="xp-btn xp-btn-primary">
    <i class="fas fa-plus"></i> 新增文章
</button>

<!-- 小尺寸按钮（表格操作栏常用） -->
<button class="xp-btn xp-btn-primary xp-btn-sm">编辑</button>
<button class="xp-btn xp-btn-danger xp-btn-sm">删除</button>

<!-- 加载中状态 -->
<button class="xp-btn xp-btn-primary xp-btn-loading">提交中...</button>

<!-- 块级按钮 -->
<button class="xp-btn xp-btn-primary xp-btn-block">确认提交</button>

五、卡片组件（xp-panel.css）

卡片是后台管理中最常用的内容容器，配合阴影和圆角提供层次感。

5.1 卡片 Class

Class	说明
xp-card	基础卡片：白色背景 + 边框 + 内边距
xp-card-shadow	叠加使用，添加阴影效果
xp-card-header	卡片头部（含标题和操作按钮）
xp-card-body	卡片主体内容区
xp-card-footer	卡片底部（常用于按钮区）

5.2 代码示例

<div class="xp-card xp-card-shadow">
    <div class="xp-card-header">
        <h3>基本信息</h3>
        <button class="xp-btn xp-btn-primary xp-btn-sm">编辑</button>
    </div>
    <div class="xp-card-body">
        <p>这里是卡片的主体内容区域。</p>
    </div>
    <div class="xp-card-footer">
        <button class="xp-btn xp-btn-primary">保存</button>
        <button class="xp-btn xp-btn-default">取消</button>
    </div>
</div>

六、导航组件（xp-nav.css）

6.1 主要导航 Class

Class	说明
xp-navbar	顶部导航栏容器
xp-sidebar	侧边栏导航
xp-breadcrumb	面包屑导航
xp-pagination	分页组件容器
xp-tabs	标签页切换导航（配合 xp-tabs.js）

6.2 面包屑示例

<nav class="xp-breadcrumb">
    <span class="xp-breadcrumb-item"><a href="/">首页</a></span>
    <span class="xp-breadcrumb-separator">/</span>
    <span class="xp-breadcrumb-item"><a href="/admin">后台</a></span>
    <span class="xp-breadcrumb-separator">/</span>
    <span class="xp-breadcrumb-item xp-active">文章管理</span>
</nav>

6.3 分页组件

分页由后端渲染 HTML 传入，容器使用 xp-pagination：

<div class="xp-pagination">
    <a href="?page=1">首页</a>
    <a href="?page=2">上一页</a>
    <span class="xp-active">3</span>
    <a href="?page=4">4</a>
    <a href="?page=4">下一页</a>
    <a href="?page=10">末页</a>
</div>

七、表单组件（xp-form.css）

7.1 表单 Class 一览

Class	说明
xp-form-group	表单项分组容器（含 label + 控件）
xp-form-label	表单标签
xp-input	文本输入框
xp-input-sm	小尺寸输入框
xp-textarea	多行文本框
xp-select	下拉选择框
xp-switch	开关切换组件
xp-checkbox	复选框
xp-radio	单选框
xp-input-error	输入框错误状态（红色边框+提示）
xp-input-success	输入框成功状态（绿色边框）
xp-form-required	必填标记（红色星号）
xp-form-help	帮助文字（灰色小字）
xp-form-error	错误提示文字（红色小字）

7.2 完整表单示例

<form id="editForm">
    <!-- 文本输入 -->
    <div class="xp-form-group">
        <label class="xp-form-label">
            文章标题 <span class="xp-form-required">*</span>
        </label>
        <input type="text" class="xp-input" name="title"
               placeholder="请输入文章标题" maxlength="100">
        <span class="xp-form-help">不超过100个字符</span>
    </div>

    <!-- 下拉选择 -->
    <div class="xp-form-group">
        <label class="xp-form-label">所属分类</label>
        <select class="xp-select" name="category_id">
            <option value="">请选择分类</option>
            <option value="1">新闻资讯</option>
            <option value="2">技术文章</option>
        </select>
    </div>

    <!-- 多行文本 -->
    <div class="xp-form-group">
        <label class="xp-form-label">文章内容</label>
        <textarea class="xp-textarea" name="content" rows="8"
                  placeholder="请输入文章内容"></textarea>
    </div>

    <!-- 开关 -->
    <div class="xp-form-group">
        <label class="xp-form-label">发布状态</label>
        <label class="xp-switch">
            <input type="checkbox" name="status" value="1" checked>
            <span class="xp-switch-slider"></span>
        </label>
    </div>
</form>

八、表格组件（xp-table.css）

8.1 表格 Class

Class	说明
xp-table	基础表格：全宽、斑马纹、悬停高亮
xp-table-bordered	带完整边框的表格
xp-table-sm	紧凑型表格（更小内边距）
xp-table-fixed	固定表头、内容区可滚动的表格
xp-select-all	全选复选框（放在th中）
xp-row-check	行选择复选框（放在td中）
xp-table-toolbar	表格上方操作工具栏
xp-search-form	表格上方搜索表单

8.2 表格示例

<table class="xp-table" id="dataTable">
    <thead>
        <tr>
            <th width="40"><input type="checkbox" class="xp-select-all"></th>
            <th>ID</th>
            <th>标题</th>
            <th>状态</th>
            <th>创建时间</th>
            <th width="180">操作</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><input type="checkbox" class="xp-row-check" value="1"></td>
            <td>1</td>
            <td>示例文章</td>
            <td><span class="xp-tag xp-tag-success">已发布</span></td>
            <td>2026-07-31</td>
            <td>
                <button class="xp-btn xp-btn-primary xp-btn-sm">编辑</button>
                <button class="xp-btn xp-btn-danger xp-btn-sm">删除</button>
            </td>
        </tr>
    </tbody>
</table>

九、标签与徽章（xp-general.css）

9.1 标签 Tag

用于状态标记，如"已发布""待审核"：

Class	说明
xp-tag	基础标签
xp-tag-primary	主色标签（绿色）
xp-tag-success	成功标签（绿色）
xp-tag-danger	危险标签（红色）
xp-tag-warning	警告标签（橙色）
xp-tag-info	信息标签（蓝色）
xp-tag-gray	灰色标签

9.2 徽章 Badge

圆角小标签，常用于计数或轻量标记（如"Hot""精华""99+"）：

Class	说明
xp-badge	基础徽章
xp-badge-primary	主色徽章
xp-badge-success	成功徽章
xp-badge-danger	危险徽章
xp-badge-warning	警告徽章
xp-badge-gray	灰色徽章

9.3 使用示例

<span class="xp-tag xp-tag-success">已发布</span>
<span class="xp-tag xp-tag-primary">待审核</span>
<span class="xp-tag xp-tag-danger">已删除</span>

<span class="xp-badge xp-badge-danger">Hot</span>
<span class="xp-badge xp-badge-warning">精华</span>
<span class="xp-badge xp-badge-primary">99+</span>

弹窗的交互逻辑由 xp-modal.js 的 XpModal 管理（详见 JS 章节），CSS 层面提供以下关键 class：

Class	说明
xp-modal-overlay	遮罩层（半透明黑色背景）
xp-modal-container	弹窗容器（白色背景+圆角+阴影）
xp-modal-header	弹窗头部（标题+关闭按钮）
xp-modal-body	弹窗主体内容区
xp-modal-footer	弹窗底部按钮区
xp-modal-close	关闭按钮（右上角×）

<!-- XpModal.open() 自动生成的弹窗结构如下： -->
<div class="xp-modal-overlay">
    <div class="xp-modal-container">
        <div class="xp-modal-header">
            <h3>弹窗标题</h3>
            <button class="xp-modal-close">×</button>
        </div>
        <div class="xp-modal-body">
            <!-- 自定义HTML内容 -->
        </div>
        <div class="xp-modal-footer">
            <button class="xp-btn xp-btn-default">取消</button>
            <button class="xp-btn xp-btn-primary">确定</button>
        </div>
    </div>
</div>

⚠ 注意：不推荐手动写弹窗 HTML，应使用 XpModal API（alert / confirm / open）来创建弹窗，框架会自动处理遮罩、动画、层级管理等。

十一、上传样式（xp-interactive-advanced.css）

上传区域的交互逻辑由 xp-upload.js 的 XpUpload 管理，CSS 层面提供关键 class：

Class	说明
xp-upload-area	上传拖拽区域（虚线边框+居中提示）
xp-upload-dragover	拖拽文件悬停状态（高亮边框）
xp-upload-list	已选文件列表容器
xp-upload-item	单个文件项（含缩略图+进度条+删除按钮）
xp-upload-progress	上传进度条
xp-upload-remove	移除文件按钮
xp-upload-placeholder	占位上传框（点击选择文件）

十二、辅助工具类（xp-base.css + xp-general.css）

提供常用的间距、文本、显示、颜色等原子化工具类，覆盖高频样式需求。

12.1 间距工具类

Class	说明	等效 CSS
xp-m-0 ~ xp-m-8	外边距（0~8级）	margin: 0~32px
xp-p-0 ~ xp-p-8	内边距（0~8级）	padding: 0~32px
xp-mt-*	上外边距	margin-top
xp-mb-*	下外边距	margin-bottom
xp-ml-*	左外边距	margin-left
xp-mr-*	右外边距	margin-right

12.2 文本工具类

Class	说明
xp-text-left	左对齐
xp-text-center	居中
xp-text-right	右对齐
xp-text-primary	主文字色（#1f2937）
xp-text-secondary	次要文字色（#6b7280）
xp-text-muted	弱化文字色（#9ca3af）
xp-text-sm	小号文字
xp-text-lg	大号文字
xp-text-bold	加粗
xp-text-truncate	文字溢出省略号
xp-text-nowrap	文字不换行

12.3 显示与背景

Class	说明
xp-hidden	隐藏元素（display: none）
xp-invisible	不可见但仍占位（visibility: hidden）
xp-block	块级元素
xp-inline-block	行内块元素
xp-bg-primary	主色背景
xp-bg-success	成功色背景
xp-bg-danger	危险色背景
xp-bg-warning	警告色背景
xp-bg-info	信息色背景
xp-bg-primary-light	主色浅色背景（#d1fae5）
xp-bg-white	白色背景
xp-bg-page	页面背景色（#f9fafb）

12.4 交互辅助

Class	说明
xp-loading	加载中遮罩层
xp-empty	空数据占位提示
xp-tooltip	鼠标悬停提示
xp-backtop	返回顶部按钮
xp-cursor-pointer	鼠标手型指针
xp-transition	统一过渡动画（all 0.2s ease）

十三、XpCore 核心 API（xp-core.js）

XpCore 是 XPUI 的核心库，提供 HTTP 请求、DOM 操作、事件总线等全局能力。所有组件均依赖 XpCore。

13.1 request —— HTTP 请求

统一的异步请求方法，基于 fetch 封装，自动处理 JSON 解析和错误提示。

// 签名：XpCore.request(url, options)
// 返回值：Promise

// GET 请求
XpCore.request('/api/user/list', {
    method: 'GET',
    params: { page: 1, keyword: 'test' }
}).then(function(res) {
    console.log(res.data);
});

// POST 请求——重点：body 直接传对象，不要 JSON.stringify
XpCore.request('/api/user/save', {
    method: 'POST',
    body: { name: '张三', email: 'test@qq.com' }
}).then(function(res) {
    if (res.code === 200) {
        XpToast.success(res.msg);
    }
});

// DELETE 请求
XpCore.request('/api/user/delete', {
    method: 'DELETE',
    body: { id: 1 }
});

⚠ 重点警告：body 参数直接传 JS 对象即可，XpCore 内部会自动调用 JSON.stringify 并设置 Content-Type: application/json。请勿手动 JSON.stringify，否则会导致请求异常！

参数	类型	必填	说明
url	string	是	请求地址
options.method	string	否	请求方式（GET/POST/PUT/DELETE），默认 GET
options.params	object	否	URL 查询参数（仅 GET）
options.body	object	否	请求体（POST/PUT/DELETE），直接传对象
options.headers	object	否	自定义请求头
options.showLoading	boolean	否	是否显示加载动画，默认 false
options.showError	boolean	否	是否自动弹出错误提示，默认 true

13.2 工具方法

方法	说明	示例
XpCore.isObject(val)	判断是否为对象	XpCore.isObject({}) // true
XpCore.isArray(val)	判断是否为数组	XpCore.isArray([]) // true
XpCore.isFunction(val)	判断是否为函数	-
XpCore.isEmpty(val)	判断是否为空（null/undefined/空串/空对象/空数组）	-
XpCore.deepClone(obj)	深拷贝对象	-
XpCore.formatDate(date, fmt)	格式化日期	XpCore.formatDate(new Date(), 'yyyy-MM-dd')
XpCore.escapeHtml(str)	HTML 字符转义，防 XSS	XpCore.escapeHtml('<script>')

13.3 DOM 操作

方法	说明
XpCore.$(selector)	选择单个 DOM 元素，等同于 document.querySelector
XpCore.$$(selector)	选择多个 DOM 元素，返回 NodeList
XpCore.addClass(el, className)	添加 class
XpCore.removeClass(el, className)	移除 class
XpCore.hasClass(el, className)	判断是否有指定 class
XpCore.toggleClass(el, className)	切换 class

13.4 事件委托

无需担心动态生成的元素，使用事件委托自动绑定：

// 签名：XpCore.on(parentSelector, event, childSelector, handler)
XpCore.on('#table-body', 'click', '.xp-btn-delete', function(e) {
    var id = this.dataset.id;
    // 处理删除逻辑
});

13.5 EventBus 事件总线

跨组件通信机制，发布/订阅模式：

// 订阅事件
XpCore.onEvent('user:updated', function(data) {
    console.log('用户已更新', data);
});

// 发布事件
XpCore.emit('user:updated', { id: 1, name: '新名称' });

// 取消订阅
XpCore.offEvent('user:updated');

十四、XpToast 消息提示（xp-toast.js）

轻量级消息提示组件，右上角弹出，自动消失，支持四种预设类型。

14.1 快捷方法

方法签名	说明
XpToast.success(msg, duration)	成功提示（绿色图标）
XpToast.error(msg, duration)	错误提示（红色图标）
XpToast.warning(msg, duration)	警告提示（橙色图标）
XpToast.info(msg, duration)	信息提示（蓝色图标）
XpToast.show(msg, type, duration)	通用方法，type: success/error/warning/info

14.2 参数说明

参数	类型	必填	默认值	说明
msg	string	是	-	提示文本内容
type	string	否	success	提示类型
duration	number	否	3000	显示时长（毫秒），设为 0 则不会自动消失

14.3 特性说明

多个 Toast 自动向上堆叠，不会互相覆盖
支持手动点击关闭
出场带有滑入+淡入动画，消失带有滑出+淡出动画
单例模式：相同消息在显示期间不会重复弹出

模态弹窗管理组件，支持 alert 提示、confirm 确认、open 自定义内容三种模式。

15.1 方法签名

方法	说明	返回值
XpModal.alert(content, options)	提示弹窗（仅确认按钮）	Promise<void>
XpModal.confirm(options)	确认弹窗（确认+取消按钮）	Promise<boolean>
XpModal.open(options)	自定义弹窗（完全自定义内容）	Promise<object>

15.2 配置项

配置项	类型	默认值	说明
title	string	提示	弹窗标题
content	string/HTMLElement	-	弹窗内容（支持 HTML 字符串或 DOM 元素）
width	string/number	500px	弹窗宽度
confirmText	string	确定	确认按钮文字
cancelText	string	取消	取消按钮文字
showCancel	boolean	true	是否显示取消按钮
closeOnOverlay	boolean	true	点击遮罩层是否关闭
onOpen	function	-	弹窗打开后的回调
onClose	function	-	弹窗关闭后的回调

15.3 使用示例

// 简单提示
XpModal.alert('操作成功！', { title: '提示' });

// 确认删除
XpModal.confirm({
    title: '确认删除',
    content: '此操作不可恢复，确定要删除吗？',
    confirmText: '确认删除',
    cancelText: '我再想想'
}).then(function(ok) {
    if (ok) XpToast.success('删除成功');
});

// 自定义弹窗
XpModal.open({
    title: '编辑用户',
    width: 650,
    content: '<div id="editForm">...自定义表单...</div>',
    onOpen: function() { /* 弹窗打开后初始化 */ }
});

十六、XpForm 表单提交与验证（xp-form.js）

表单组件封装了 AJAX 提交、前端验证和交互状态管理。

16.1 XpForm.create(options) 配置项

配置项	类型	必填	说明
el	string/HTMLElement	是	表单元素或选择器
url	string	是	提交地址
method	string	否	请求方式，默认 POST
loadUrl	string	否	编辑时加载数据的地址（GET 请求）
rules	object	否	验证规则对象
onSuccess	function(res)	否	提交成功回调
onError	function(err)	否	提交失败回调
beforeSubmit	function(data)	否	提交前处理函数，可修改 data

16.2 验证规则

验证 rules 对象配置，key 为字段名，value 为规则数组或字符串：

var rules = {
    title: [{ required: true, message: '请输入标题', trigger: 'blur' },
            { min: 2, max: 100, message: '标题长度为2-100个字符' }],
    email: [{ required: true, message: '请输入邮箱' },
            { type: 'email', message: '邮箱格式不正确' }],
    url:   [{ type: 'url', message: '请输入正确的URL' }],
    password: [{ required: true, message: '请输入密码' },
               { min: 6, max: 20, message: '密码长度为6-20位' }]
};

16.3 完整示例

var form = XpForm.create({
    el: '#editForm',
    url: '/admin/article/save',
    loadUrl: '/admin/article/edit?id=5',   // 编辑模式自动加载
    rules: {
        title: [{ required: true, message: '请输入文章标题' },
                { max: 100, message: '标题不能超过100字' }],
        category_id: [{ required: true, message: '请选择分类' }]
    },
    onSuccess: function(res) {
        XpToast.success(res.msg);
        setTimeout(function() { location.reload(); }, 1500);
    },
    onError: function(err) {
        XpToast.error(err.msg || '提交失败');
    }
});

// 手动触发表单提交
form.submit();

十七、XpTable 表格管理（xp-table.js）

封装表格选择、全选、批量操作等功能。

17.1 核心方法

方法	说明
XpTable.init(tableId)	初始化表格选择功能（绑定全选/反选事件）
XpTable.getSelected(tableId)	获取所有选中的 checkbox value 数组
XpTable.selectAll(tableId)	全选
XpTable.deselectAll(tableId)	取消全选

17.2 使用示例

// 初始化表格
var table = XpTable.init('dataTable');

// 批量删除
document.getElementById('batchDeleteBtn').onclick = function() {
    var ids = XpTable.getSelected('dataTable');
    if (ids.length === 0) {
        XpToast.warning('请先选择要删除的数据');
        return;
    }
    XpModal.confirm({ title: '批量删除', content: '确定删除选中的'+ids.length+'条数据？' })
        .then(function(ok) {
            if (ok) {
                XpCore.request('/admin/article/batchDelete', {
                    method: 'POST', body: { ids: ids }
                });
            }
        });
};

⚠ 注意：XPUI 还提供更强大的 xp-tree-table.js（树形表格）和 xp-pagination.js（分页组件），适用于更复杂的表格场景。

十八、XpUpload 文件上传（xp-upload.js）

支持图片/文件上传，内置拖拽、进度条、缩略图预览功能。

18.1 XpUpload.create(trigger, options) 配置项

配置项	类型	默认值	说明
url	string	必填	上传地址
accept	string	image/*	允许的文件类型（MIME）
maxSize	number	10	最大文件大小（MB）
maxCount	number	1	最大上传数量
showPreview	boolean	true	是否显示图片缩略图预览
onSuccess	function(file, res)	-	单个文件上传成功回调
onError	function(file, err)	-	上传失败回调
onRemove	function(file)	-	移除文件回调

18.2 使用示例

// 图片上传
var upload = XpUpload.create('#uploadBtn', {
    url: '/admin/upload/image',
    accept: 'image/*',
    maxSize: 5,
    maxCount: 3,
    onSuccess: function(file, res) {
        // res.data.url 为上传后的文件URL
        var img = document.createElement('img');
        img.src = res.data.url;
        document.getElementById('previewBox').appendChild(img);
    }
});

💡 XpUpload 还提供了 XpPicker.openFilePicker(accept, multiple, callback) 快捷方法，用于只需选择文件（不自动上传）的场景。详见下方演示区域。

下拉菜单组件，支持点击/悬停触发，自动计算位置，点击外部自动关闭。

19.1 核心方法

方法	说明
XpDropdown.create(trigger, items, placement, triggerType)	创建下拉菜单
XpDropdown.init(selector)	批量初始化（基于 data 属性自动构建）
XpDropdown.hideAll()	关闭所有打开的下拉菜单

19.2 参数说明

参数	类型	默认值	说明
trigger	string/HTMLElement	必填	触发器元素
items	Array<{label, value, icon, disabled, divider}>	必填	菜单项数组
placement	string	bottom-start	弹出位置：bottom-start / bottom / bottom-end / top-start
triggerType	string	click	触发方式：click / hover

19.3 使用示例

// 创建下拉菜单
var dropdown = XpDropdown.create('#moreBtn', [
    { label: '编辑', value: 'edit', icon: 'fas fa-edit' },
    { label: '复制', value: 'copy', icon: 'fas fa-copy' },
    { label: '---', divider: true },
    { label: '删除', value: 'delete', icon: 'fas fa-trash', class: 'xp-text-danger' }
], 'bottom-end');

// 监听菜单项点击
XpCore.onEvent('dropdown:selected', function(data) {
    console.log('选中：', data.value, data.label);
});

// 手动关闭
XpDropdown.hideAll();

19.4 零代码初始化（推荐）

通过 HTML 属性声明式配置，一行 JS 即可批量初始化所有下拉：

<!-- HTML 声明式配置 -->
<button class="xp-btn xp-btn-default" data-dropdown='[
    {"label":"编辑","icon":"fas fa-edit","value":"edit"},
    {"label":"删除","icon":"fas fa-trash","value":"delete"}
]' data-dropdown-placement="bottom-end">
    更多操作 <i class="fas fa-chevron-down"></i>
</button>

<script>
// 一行代码批量初始化
XpDropdown.init('[data-dropdown]');
</script>

二十、XpTabs 标签页切换（xp-tabs.js）

标签页组件，支持动态新增、关闭和异步加载内容。

20.1 核心方法

方法	说明
XpTabs.create(container, tabs, active, onChange, onClose)	创建标签页实例
XpTabs.init(container)	从已有 DOM 结构初始化
XpTabs.createTabBar(options)	创建浏览器标签栏式 UI（支持右键菜单）

20.2 参数说明

参数	类型	说明
container	string/HTMLElement	标签页容器元素
tabs	Array	标签页数组 [{title, content, closable}, ...]
active	number	默认激活的索引（0-based），默认 0
onChange	function(tab, index)	切换标签页时的回调
onClose	function(tab, index)	关闭标签页时的回调

20.3 使用示例

// 创建标签页
var tabs = XpTabs.create('#tabContainer', [
    { title: '基本信息', content: '<p>这里是基本信息</p>' },
    { title: '详细设置', content: '<p>这里是详细设置</p>' },
    { title: '操作日志', content: '<p>这里是操作日志</p>' }
], 0, function(tab, index) {
    console.log('切换到标签：' + tab.title);
});

// 动态添加标签
tabs.addTab({ title: '新标签', content: '<p>动态添加的内容</p>' });

// 关闭指定标签（closable 为 true 时才可关闭）
tabs.removeTab(1);

// 浏览器标签栏风格（支持右键关闭等操作）
var tabBar = XpTabs.createTabBar({ container: '#tabBarWrap' });

二十一、XpCodePreview 代码预览（xp-code-preview.js）

代码语法高亮与预览组件，支持多语言、行号、折叠、一键复制。

21.1 核心方法

方法	说明
XpCodePreview.create(code, language, title, ...)	创建代码预览实例
XpCodePreview.highlight(code, language)	对代码进行语法高亮处理

21.2 配置项

参数	类型	默认值	说明
code	string	必填	源代码字符串
language	string	javascript	语言类型：html/css/js/php/sql/json/xml/bash 等
title	string	-	代码块标题（显示在顶部栏）
collapsible	boolean	true	是否可折叠
showLineNumbers	boolean	true	是否显示行号
theme	string	dark	主题：dark / light
copyable	boolean	true	是否显示复制按钮
maxHeight	string/number	500px	代码区域最大高度，超出则滚动

21.3 使用示例

// 创建代码预览
var preview = XpCodePreview.create(
    '<?php echo "Hello World"; ?>',
    'php',
    'hello.php',
    false,    // collapsible
    true,     // showLineNumbers
    'dark',   // theme
    true,     // copyable
    '400px'   // maxHeight
);

// 挂载到页面
document.getElementById('codeArea').appendChild(preview);

// 仅做语法高亮
var html = XpCodePreview.highlight(
    'function hello() { return "world"; }',
    'javascript'
);

二十二、XpColorPicker 颜色选择器（xp-color-picker.js）

22.1 核心方法

// 签名：XpColorPicker.create(trigger, options)
// 返回值：colorPicker 实例

22.2 配置项

参数	类型	默认值	说明
trigger	string/HTMLElement	必填	触发器元素
format	string	hex	颜色格式：hex / rgb / hsl
showAlpha	boolean	false	是否支持透明度（RGBA/HSLA）
presets	Array<string>	[]	预设颜色列表
value	string	#000000	初始颜色值
onChange	function(color)	-	颜色变化回调
onClose	function()	-	选择器关闭回调

22.3 使用示例

var picker = XpColorPicker.create('#colorBtn', {
    format: 'hex',
    showAlpha: false,
    presets: ['#16a34a', '#ef4444', '#f59e0b', '#3b82f6', '#8b5cf6', '#ec4899'],
    value: '#16a34a',
    onChange: function(color) {
        // color.hex = "#16a34a"
        // color.rgb = "rgb(22, 163, 74)"
        // color.hsl = "hsl(142, 76%, 36%)"
        document.getElementById('previewBox').style.backgroundColor = color.hex;
        document.getElementById('colorInput').value = color.hex;
    }
});

二十三、图标选择器

XPUI 图标系统基于 Font Awesome 5，所有图标通过 <i> 标签 + class 名使用。如需图标选择器功能，可通过弹窗组件封装实现：

23.1 图标使用方式

<!-- 基础图标 -->
<i class="fas fa-home"></i>
<i class="fas fa-user"></i>
<i class="fas fa-edit"></i>
<i class="fas fa-trash"></i>
<i class="fas fa-plus"></i>
<i class="fas fa-cog"></i>

<!-- 图标 + 文字 -->
<button class="xp-btn xp-btn-primary">
    <i class="fas fa-plus"></i> 新增
</button>

<!-- 大小控制 -->
<i class="fas fa-star fa-lg"></i>  <!-- 大 -->
<i class="fas fa-star fa-2x"></i>  <!-- 2倍 -->
<i class="fas fa-star fa-3x"></i>  <!-- 3倍 -->

<!-- 旋转动画 -->
<i class="fas fa-spinner fa-spin"></i>  <!-- 加载旋转 -->
<i class="fas fa-circle-notch fa-spin"></i>  <!-- 另一种旋转 -->

23.2 常用图标速查

图标名	Class	使用场景
	fa-home	首页
	fa-user	用户/个人中心
	fa-edit	编辑
	fa-trash	删除
	fa-plus	新增
	fa-search	搜索
	fa-cog	设置
	fa-sync	刷新
	fa-download	下载
	fa-upload	上传
	fa-eye	查看
	fa-lock	锁定/权限
	fa-check	确认/成功
	fa-times	关闭/取消
	fa-exclamation-triangle	警告
	fa-info-circle	提示信息

💡 完整图标列表请参考 Font Awesome 5 Free 图标库。如需实现图标选择弹窗，可使用 XpModal.open() 加载图标网格，详见下方演示区。

二十四、视图模板规范

24.1 模板文件结构

{include file="common/_header" /}       <!-- 页面头部（导航/SEO/全局样式） -->
{// 设置当前模块标识，供 _header.html 自动高亮导航 }
{$xp_current_module = 'module_name'}

<!-- 页面主体内容 -->
<div class="xp-container">
    <!-- 业务内容 -->
</div>

{include file="common/_footer" /}       <!-- 页面底部（版权/脚本/统计） -->

24.2 常见模板标签

标签	用途	示例
{include file="..." /}	引入公共模板	引入 header/footer/侧边栏
{$var}	输出变量	{$title}
{if $condition}...{/if}	条件判断	权限判断、空值处理
{foreach $list as $item}...{/foreach}	循环遍历	文章列表、菜单遍历
{:url('path')}	生成URL	{:url('index/index')}
{:json_encode($data)}	JSON输出（不会转义HTML实体）	JS数据注入
{literal}...{/literal}	原样输出	输出代码示例

24.3 注意事项

禁止在模板中使用原生 <?php ?> 标签，使用 ThinkPHP 模板标签替代
JavaScript 中的 {$var} 会被模板引擎解析，需使用 {literal}...{/literal} 包裹
JSON 输出使用 {:json_encode($data)} 而非 {$data|json_encode}
变量使用前检查是否存在：{if !empty($data)}...{/if}

🧪 组件交互演示

以下演示可直接点击按钮交互，体验 XPUI 各组件的实际效果。

按钮展示

消息提示

确认弹窗

标签与徽章

Tag：待审核已发布草稿已删除置顶归档

Badge： Hot 精华 99+ New 关闭

表格复选框

ID	标题	状态
1	新闻标题示例一	已发布
2	产品发布公告	待审核
3	系统更新通知	草稿