|

标签页组件 2.10+

tabs 是 2.10 版本新增的加强型组件，可替代原 element 模块中的 tab 组件。tabs 广泛应用于 Web 页面。

示例

动态操作

方法渲染

即通过方法设置 tabs 标签，而非默认的自动渲染页面中的 class="layui-tabs" 的容器模板。

卡片风格

自定义事件

通过 HASH 匹配选中标签

切换 tabs 标签项后，地址栏同步 hash 值，当页面刷新时，tabs 仍保持对应的切换状态。

标签嵌套

给任意元素绑定 tabs 切换功能

API

API 描述
var tabs = layui.tabs 获得 tabs 模块。
基础接口 该组件由 component 构建，因此继承其提供的基础接口。
tabs.render(options) tabs 组件渲染，核心方法。
tabs.add(id, opts) 新增一个标签项。
tabs.close(id, index, force) 关闭指定的标签项。
tabs.closeMult(id, mode, index) 批量关闭标签项。
tabs.change(id, index, force) 切换到指定的标签项。
tabs.data(id) 获取当前标签页相关数据。
tabs.getHeaderItem(id, index) 获取指定的标签头部项。
tabs.getBodyItem(id, index) 获取指定的标签内容项。
tabs.refresh(id) 刷新标签视图。

渲染

tabs.render(options)

组件支持以下三种渲染方式：

1. 自动渲染

tabs 组件会在元素加载完毕后，自动对 class="layui-tabs" 目标元素完成一次渲染，若无法找到默认的目标元素（如：动态插入的标签元素的场景），则可通过该方法完成对标签页的初始化渲染。

// 对 class="layui-tabs" 所在标签进行初始化渲染
tabs.render();

2. 方法渲染

通过方法动态渲染一个 tabs 组件，无需在 HTML 中书写标签页的 HTML 结构。

<div id="test"></div>
<!-- import layui -->
<script>
layui.use(function(){
  var tabs = layui.tabs;
  tabs.render({
    elem: '#test',
    header: [
      { title: 'Tab1' },
      { title: 'Tab2' }
    ],
    body: [
      { content: 'Tab content 1' },
      { content: 'Tab content 2' }
    ],
    index: 0, // 初始选中标签索引
  })
});
</script>

3. 为任意元素渲染 tabs 功能

当 header 和 body 参数传入元素选择器时，可为任意元素绑定标签切换功能。

// 给任意元素绑定 Tab 功能
tabs.render({
  elem: '#demoTabs3', // 目标主容器选择器
  header: ['#demoTabsHeader', '>button'], // 标签头部主元素选择器、标签头部列表选择器
  body: ['#demoTabsBody', '>.test-item'] // 标签内容主元素选择器、标签内容列表选择器
});

具体用法可直接参考上述示例：给任意元素绑定 tabs 切换功能

属性

属性名 描述 类型 默认值
elem

组件渲染指定的目标元素选择器或 DOM 对象

 string/DOM -
id

组件渲染的唯一实例 ID

 string -
className

给主容器追加 CSS 类名，以便自定义样式

 string -
trigger

标签切换的触发事件

 boolean

click
headerMode

标签头部的显示模式。可选值有：

  • auto 自动模式，根据标签头部是否溢出自动显示不同模式
  • scroll 始终滚动模式
  • normal 始终常规模式，不渲染头部滚动结构
 string

auto
index

初始选中的标签索引或标签 lay-id 属性值

 number -
closable

是否开启标签项关闭功能

 boolean

false
header

设置标签头部列表，通常在「非自动渲染」的场景下使用：

1. 方法渲染

若 header 传入一个数组，且成员值为对象，即为方法渲染时传入的头部列表数据。如：

header: [
  { title: 'Tab1' }, // 除 `title` 为必传项外，也可传入其他任意字段。
  { title: 'Tab2' }
]

2. 任意元素渲染

若 header 传入一个数组，则成员值为元素选择器，即为绑定标签头部列表元素。如：

header: ['#tabsHeader', '>li'],
body

设置标签内容列表，通常在「非自动渲染」的场景下使用：

1. 方法渲染

若 body 传入一个数组，且成员值为对象，即为方法渲染时传入的标签内容列表数据。如：

body: [
  { content: 'Tab1' }, // `content` 为必传项
  { content: 'Tab2' }
]

2. 任意元素渲染

若 body 传入一个数组，则成员值为元素选择器，即为绑定标签内容列表元素。如：

body: ['#tabsBody', '>div'],

新增标签

tabs.add(id, opts)

  • 参数 id : 组件的实例 ID
  • 参数 opts : 标签配置项。可选项详见下表
opts 描述 类型 默认值
title 标签标题。必填项 string -
content 标签内容。必填项 string -
id 标签的 lay-id 属性值 string -
index 活动标签的索引或 lay-id 属性值，默认取当前选中标签的索引 number -
mode 标签的插入方式。支持以下可选值：
  • append 插入标签到最后
  • prepend 插入标签到最前
  • before 在活动标签前插入
  • after 在活动标签后插入
 string append
closable 标签是否可关闭。初始值取决于 options.closable boolean false
headerItem 自定义标签头部元素，如 headerItem: '<li></li>' string -
bodyItem 自定义标签内容元素，如 bodyItem: '<div></div>' string -
done 标签添加成功后执行的回调函数 Function -

该方法用于给对应的 tabs 实例新增一个标签

tabs.add('test', {
  title: 'New Tab 1',
  content: 'New Tab Content 1',
});

关闭标签

tabs.close(id, index, force)

  • 参数 id : 组件的实例 ID
  • 参数 index : 标签索引或标签的 lay-id 属性值
  • 参数 force : 是否强制关闭。若设置 true 将忽略 beforeClose 事件行为。默认 false

该方法用于关闭指定的标签项。

tabs.close('test', 3); // 关闭索引为 3 的标签
tabs.close('test', 3, true); // 强制关闭索引为 3 的标签
tabs.close('test', 'abc'); // 关闭 lay-id="abc" 的标签

批量关闭标签

tabs.closeMult(id, mode, index)

  • 参数 id : 组件的实例 ID
  • 参数 mode : 关闭方式。支持以下可选值：
mode 描述
other 关闭除当前标签外的所有标签
right 关闭当前标签及右侧标签
all 关闭所有标签
  • 参数 index : 活动标签的索引或 lay-id 属性值，默认取当前选中标签的索引。一般用于标签右键事件。

该方法用于批量关闭标签。

tabs.closeMult(id, 'other'); // 关闭除当前标签外的所有标签
tabs.closeMult(id, 'other', 3); // 关闭除索引为 3 的标签外的所有标签
tabs.closeMult(id, 'right'); // 关闭当前标签及右侧标签
tabs.closeMult(id, 'right', 3); // 关闭索引为 3 的标签的右侧所有标签
tabs.closeMult(id, 'all'); // 关闭所有标签

切换标签

tabs.change(id, index, force)

  • 参数 id : 组件的实例 ID
  • 参数 index : 标签索引或标签的 lay-id 属性值
  • 参数 force : 是否强制切换。若设置 true 将忽略 beforeChange 事件行为。默认 false

该方法用于切换到指定的标签项。

tabs.change('test', 3); // 切换到索引为 3 的标签
tabs.change('test', 3, true); // 强制切换到索引为 3 的标签
tabs.change('test', 'abc'); // 切换到 lay-id="abc" 的标签
tabs.change('test', 'abc', true); // 强制切换到 lay-id="abc" 的标签

获取标签相关数据

tabs.data(id)

  • 参数 id : 组件的实例 ID

该方法用于获取标签相关数据。

var data = tabs.data('test');
console.log(data);

返回的 data 包含以下字段：

{
  options, // 标签配置信息
  container, // 标签容器的相关元素
  thisHeaderItem, // 当前标签头部项
  thisBodyItem, // 当前标签内容项
  index, // 当前标签索引
  length, // 当前标签数
}

获取标签头部项

tabs.getHeaderItem(id, index)

  • 参数 id : 组件的实例 ID
  • 参数 index : 标签索引或标签的 lay-id 属性值

该方法用于获取标签头部项元素。

var headerItem = tabs.getHeaderItem('test', 3); // 获取索引为 3 的标签头部项元素

获取标签内容项

tabs.getBodyItem(id, index)

  • 参数 id : 组件的实例 ID
  • 参数 index : 标签索引或标签的 lay-id 属性值

该方法用于获取标签内容项元素。

var bodyItem = tabs.getBodyItem('test', 3); // 获取索引为 3 的标签内容项元素

刷新标签视图

tabs.refresh(id)

  • 参数 id : 组件的实例 ID

该方法用于刷新标签视图，如标签头部的滚动结构等，一般通过非 API 方式对标签进行修改的场景中使用。

tabs.refresh('test'); // 刷新标签视图

事件

tabs.on('event(id)', callback)

  • 参数介绍详见 component 组件的事件定义。以下是组件提供的 event 事件列表
event 描述
afterRender 标签渲染后的事件
beforeChange 标签切换前的事件
afterChange 标签切换后的事件
beforeClose 标签关闭前的事件
afterClose 标签关闭后的事件

标签渲染后的事件

tabs.on('afterRender(id)', callback)

标签渲染成功后触发。

tabs.on('afterRender(testID)', function(data){
  console.log(data); // 标签相关数据
});

标签切换前的事件

tabs.on('beforeChange(id)', callback)

标签在切换前触发，通过在事件中 return false 可阻止默认标签切换行为。通常和 tabs.change() 方法搭配使用。

// tabs 切换前的事件
tabs.on(`beforeChange(testID)`, function(data) {
  console.log(data); // 标签相关数据
  console.log(data.from.index); // 切换前的选中标签索引
  console.log(data.from.headerItem); // 切换前的选中标签头部项
  console.log(data.to.index); // 切换后的选中标签索引
  console.log(data.to.headerItem); // 切换后的选中标签头部项
  // 阻止标签默认关闭
  return false;
});

示例演示：

标签切换后的事件

tabs.on('afterChange(id)', callback)

标签成功切换后触发。

// tabs 切换后的事件
tabs.on('afterChange(testID)', function(data) {
  console.log(data);
});

标签关闭前的事件

tabs.on('beforeClose(id)', callback)

标签在切换前触发，通过在事件中 return false 可阻止默认标签切换行为。通常和 tabs.close() 方法搭配使用。

标签关闭后的事件

tabs.on('afterClose(id)', callback)

标签被成功关闭后触发。

// tabs 关闭后的事件
tabs.on('afterClose(testID)', function(data) {
  console.log(data);
});

💖 心语

tabs 是通过 component 重构的首个组件，它来自于最早试图发布的 Layui 3.0（后因为 3.0 技术路线的变化，而整理放至 2.10+ 版本中），目的是将 element 模块中的 tab 组件进行解耦，增强其可扩展性。为了给开发者必要的时间缓冲，我们会将旧 tab 组件仍然保留在后续的若干版本中，但会在合适的时机对旧 tab 组件进行剔除，建议开发者尽量提前过渡到当前新的 tabs 组件。

Copyright © 2025 Layui MIT Licensed

鸣谢： 又拍云 Gitee iconfont