docs/tab/index.md
📣 <span style="color: #ff5722;">升级提示：我们在 2.10 版本中新增了全新的 tabs 标签页组件，用于替代原
element模块中的tab组件，建议过渡到全新的 tabs 组件，旧的tab组件将在后续合适的版本中移除。</span> 前往全新 tabs 组件
<h2 id="examples" lay-toc="{hot: true}" style="margin-bottom: 0;">示例</h2> <div class="ws-detail"> {{- d.include("/tab/detail/demo.md") }} </div> <h2 id="skin" lay-toc="{hot: true}">风格</h2>选项卡组件
tab是指可进行标签页切换的一段容器，常广泛应用于 Web 页面。由于为了向下兼容等诸多历史原因，在 2.x 版本中，tab组件属于element模块的子集。
tab 组件提供了三种 UI 风格，分别为：
| 风格 | className |
|---|---|
| 默认风格 | class="layui-tab" |
| 简约风格 | class="layui-tab layui-tab-brief" |
| 卡片风格 | class="layui-tab layui-tab-card" |
| API | 描述 |
|---|---|
| var element = layui.element | 获得 element 模块。 |
| element.render('tab', filter) | 渲染 tab 组件 |
| element.tabAdd(filter, options) | 添加 tab 选项 |
| element.tabDelete(filter, layid, force) | 删除 tab 选项 |
| element.tabChange(filter, layid, force) | 切换 tab 选项 |
| element.tab(options) | 绑定自定义 tab 元素 |
| 属性 | 描述 |
|---|---|
| lay-allowclose | 是否开启删除图标。设置在 tab 容器 <ul class="layui-tab"> 上。 |
<sup>2.9.11+</sup>: 若需要单独关闭某一个选项卡的删除图标，可在选项卡标题元素 <li> 上设置 lay-allowclose="false" | |
| lay-id | tab 选项唯一 ID，一般用于外部对 tab 的删除和切换等操作。设置在 tab 中的 <li> 元素上。在外部附加选项卡拖拽排序时，layui-tab-item 元素也要设置 ID |
element.render('tab', filter);
'tab' 是渲染 tab 的固定值。filter : 对应 tab 容器 lay-filter 的属性值或<sup>2.9.15+</sup>指定元素的 jQuery 对象。tab 组件会在元素加载完毕后，自动对 tab 元素完成一次渲染，因此该方法主要用于对动态插入的 tab 元素的初始化渲染。
<div id="test"></div>
<!-- import layui -->
<script>
layui.use(function(){
var element = layui.element;
var $ = layui.$;
// 动态插入 tab 元素
$('#test').html(`
<div class="layui-tab" lay-filter="demo-filter-tab">
<!-- … -->
</div>
`);
// 渲染 tab 组件
element.render('tab', 'demo-filter-tab');
});
</script>
element.tabAdd(filter, options);
filter : tab 容器（class="layui-tab"）的 lay-filter 属性值options : 添加 tab 时的属性选项，见下表：| options | 描述 | 类型 | 默认 |
|---|---|---|---|
| title | 选项卡的标题 | string | - |
| content | 选项卡的内容，支持传入 html | string | - |
| id | 选项卡标题元素的 lay-id 属性值 | string | - |
| change | 是否添加 tab 完毕后即自动切换 | boolean | false |
| allowClose <sup>2.9.11+</sup> | 是否开启删除图标 | boolean | false |
该方法用于添加 tab 选项。用法详见 : #示例
<h3 id="element.tabDelete" lay-toc="{level: 2}" class="ws-bold">删除 tab</h3>element.tabDelete(filter, layid, force);
filter : tab 容器（class="layui-tab"）的 lay-filter 属性值layid : 选项卡标题元素的 lay-id 属性值force <sup>2.9.21+</sup>
: 是否强制删除 tab。若设置 true 将忽略 tabBeforeDelete 事件行为。默认 false该方法用于删除 tab 选项。用法详见 : #示例
<h3 id="element.tabChange" lay-toc="{level: 2}" class="ws-bold">切换 tab</h3>element.tabChange(filter, layid, force);
filter : tab 容器（class="layui-tab"）的 lay-filter 属性值layid : 选项卡标题元素的 lay-id 属性值force <sup>2.9.15+</sup>
: 是否强制执行 tab 切换。设置 true 将忽略 tabBeforeChange 事件行为。默认 false该方法用于切换到对应的 tab 选项。用法详见 : #示例
<h3 id="element.tab" lay-toc="{level: 2}" class="ws-bold">自定义 tab</h3>element.tab(options);
options : 属性选项，见下表：| options | 描述 | 类型 |
|---|---|---|
| headerElem | 指定自定义的 tab 头元素项选择器 | string / DOM |
| bodyElem | 指定自定义的 tab 主题内容元素项选择器 | string / DOM |
该方法用于绑定自定义 tab 元素（即非 class="layui-tab 定义的结构）。示例如下：
element.on('tab(filter)', callback);
tab(filter) 是一个特定结构。
tab 为 tab 切换事件固定值；filter 为 tab 容器属性 lay-filter 对应的值。callback 为事件执行时的回调函数，并返回一个 object 类型的参数。点击 tab 选项切换时触发。#参考示例
var element = layui.element;
// tab 切换事件
element.on('tab(filter)', function(data){
console.log(this); // 当前 tab 标题所在的原始 DOM 元素
console.log(data.index); // 得到当前 tab 项的所在下标
console.log(data.elem); // 得到当前的 tab 容器
console.log(data.id); // 得到当前的 tab ID(2.9.11+)
});
element.on('tabBeforeChange(filter)', callback);
tabBeforeChange(filter) 是一个特定结构。
tabBeforeChange 为 tab 切换前事件固定值；filter 为 tab 容器属性 lay-filter 对应的值。callback 为事件执行时的回调函数，并返回一个 object 类型的参数。点击 tab 选项切换前触发。
var element = layui.element;
// tab 切换前的事件
element.on('tabBeforeChange(filter)', function(data){
console.log(data.elem); // 得到当前的 tab 容器
console.log(data.from.index); // 得到切换前的 tab 项所在下标
console.log(data.from.id); // 得到切换前的 tab 项所在ID
console.log(data.to.index); // 得到切换后的 tab 项所在下标
console.log(data.to.id); // 得到切换后的 tab 项所在ID
if(data.to.id === 'home') return false; // 返回 false 时阻止切换到对应的选项卡
});
element.on('tabDelete(filter)', callback);
tabDelete(filter) 是一个特定结构。
tabDelete 为 tab 删除事件固定值；filter 为 tab 容器属性 lay-filter 对应的值。callback 为事件执行时的回调函数，并返回一个 object 类型的参数。点击 tab 选项删除时触发。
var element = layui.element;
// tab 删除事件
element.on('tabDelete(filter)', function(data){
console.log(data.index); // 得到被删除的 tab 项的所在下标
console.log(data.elem); // 得到当前的 tab 容器
console.log(data.id); // 得到被删除的 tab 项的 ID(2.9.11+)
});
element.on('tabBeforeDelete(filter)', callback);
tabBeforeDelete(filter) 是一个特定结构。
tabBeforeDelete 为 tab 删除前事件固定值；filter 为 tab 容器属性 lay-filter 对应的值。callback 为事件执行时的回调函数，并返回一个 object 类型的参数。点击 tab 选项删除前触发。 示例：
<pre class="layui-code" lay-options="{preview: true, layout: ['code', 'preview'], tools: ['full'], done: function(obj){ obj.render(); }}"> <textarea> <div class="layui-tab" lay-allowclose="true" lay-filter="test-tabs"> <ul class="layui-tab-title"> <li lay-id="1" class="layui-this">标签1</li> <li lay-id="2">标签2</li> <li lay-id="3">标签3</li> <li lay-id="4">标签4</li> <li lay-id="5">标签5</li> </ul> <div class="layui-tab-content"> <div class="layui-tab-item layui-show">删除标签，弹出确认提示框</div> <div class="layui-tab-item">内容-2</div> <div class="layui-tab-item">内容-3</div> <div class="layui-tab-item">内容-4</div> <div class="layui-tab-item">内容-5</div> </div> </div> <!-- import layui --> <script> layui.use(function(){ var layer = layui.layer; var element = layui.element; // tab 删除前的事件 element.on('tabBeforeDelete(test-tabs)', function(data){ console.log(data.index); // 得到被删除的 tab 项的所在下标 console.log(data.elem); // 得到当前的 tab 容器 console.log(data.id); // 得到被删除的 tab 项的 ID(2.9.11+) // 确认删除 layer.confirm(`确认删除【${this.innerText}】吗？`, function (index) { element.tabDelete('test-tabs', data.id, true); // 确认后强制删除 - 2.9.21+ layer.close(index); }); return false; // 返回 false 时阻止默认删除选项卡行为 }); }); </script> </textarea> </pre>