---
title: 标签页组件 tabs
toc: true
---

# 标签页组件 <sup>2.10+</sup>

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

<h2 id="examples" lay-toc="{anchor: null}" style="margin-bottom: 0;">示例</h2>

<div class="ws-docs-showcase"></div>

<div>
{{- d.include("/tabs/detail/demo.md") }}
</div>

<h2 id="api" lay-toc="{hot: true}">API</h2>

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

<h3 id="render" lay-toc="{level: 2}">渲染</h3>

`tabs.render(options)`

- 参数 `options` : 基础属性配置项。[#详见属性](#options)

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

#### 1. 自动渲染

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

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

#### 2. 方法渲染

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

```js
<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` 参数传入元素选择器时，可为任意元素绑定标签切换功能。

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

具体用法可直接参考上述示例：[给任意元素绑定 tabs 切换功能](#demo-custom)


<h3 id="options" lay-toc="{level: 2}">属性</h3>

<div>
{{- d.include("/tabs/detail/options.md") }}
</div>

<h3 id="add" class="ws-anchor ws-bold">新增标签</h3>

`tabs.add(id, opts)`

- 参数 `id` :  组件的实例 ID
- 参数 `opts` : 标签配置项。可选项详见下表

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

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

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

<h3 id="close" class="ws-anchor ws-bold">关闭标签</h3>

`tabs.close(id, index, force)`

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

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

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

<h3 id="closeMult" class="ws-anchor ws-bold">批量关闭标签</h3>

`tabs.closeMult(id, mode, index)`

- 参数 `id` : 组件的实例 ID
- 参数 `mode` : 关闭方式。支持以下可选值：

| mode | 描述 |
| --- | --- |
| other | 关闭除当前标签外的所有标签 |
| right | 关闭当前标签及右侧标签 |
| all | 关闭所有标签 |

- 参数 `index` : 活动标签的索引或 `lay-id` 属性值，默认取当前选中标签的索引。一般用于标签右键事件。

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

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

<h3 id="change" class="ws-anchor ws-bold">切换标签</h3>

`tabs.change(id, index, force)`

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

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

```js
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" 的标签
```

<h3 id="data" class="ws-anchor ws-bold">获取标签相关数据</h3>

`tabs.data(id)`

- 参数 `id` : 组件的实例 ID

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

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

返回的 `data` 包含以下字段：

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

<h3 id="getHeaderItem" class="ws-anchor ws-bold">获取标签头部项</h3>

`tabs.getHeaderItem(id, index)`

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

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

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

<h3 id="getBodyItem" class="ws-anchor ws-bold">获取标签内容项</h3>

`tabs.getBodyItem(id, index)`

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

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

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

<h3 id="refresh" class="ws-anchor ws-bold">刷新标签视图</h3>

`tabs.refresh(id)`

- 参数 `id` : 组件的实例 ID

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

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


<h2 id="on" lay-toc="{hot: true}">事件</h2>

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

- 参数介绍详见 `component` 组件的[事件定义](../component/#on)。以下是组件提供的 `event` 事件列表

| event | 描述 |
| --- | --- |
| [afterRender](#on-afterRender) | 标签渲染后的事件 |
| [beforeChange](#on-beforeChange) | 标签切换前的事件 |
| [afterChange](#on-afterChange) | 标签切换后的事件 |
| [beforeClose](#on-beforeClose) | 标签关闭前的事件 |
| [afterClose](#on-afterClose) | 标签关闭后的事件 |


<h3 id="on-afterRender" class="ws-anchor ws-bold">标签渲染后的事件</h3>

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

标签渲染成功后触发。

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

<h3 id="on-beforeChange" class="ws-anchor ws-bold">标签切换前的事件</h3>

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

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

```js
// 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;
});
```

示例演示：

<pre class="layui-code" lay-options="{preview: true, layout: ['preview', 'code'], codeStyle: 'max-height: 520px;', tools: ['full'], done: function(obj){
  obj.render();
}}">
  <textarea>
{{- d.include("/tabs/examples/beforeChange.md") }}
  </textarea>
</pre>

<h3 id="on-afterChange" class="ws-anchor ws-bold">标签切换后的事件</h3>

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

标签成功切换后触发。

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

<h3 id="on-beforeClose" class="ws-anchor ws-bold">标签关闭前的事件</h3>

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

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

<pre class="layui-code" lay-options="{preview: true, layout: ['preview', 'code'], codeStyle: 'max-height: 520px;', tools: ['full'], done: function(obj){
  obj.render();
}}">
  <textarea>
{{- d.include("/tabs/examples/beforeClose.md") }}
  </textarea>
</pre>

<h3 id="on-afterClose" class="ws-anchor ws-bold">标签关闭后的事件</h3>

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

标签被成功关闭后触发。

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

## 💖 心语

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

