refactor: 重写 tabs 标签页组件文档

2026-01-28 19:11:26 +08:00 · 2025-03-05 19:37:39 +08:00
parent 82a497927c
commit 725fc442f7
10 changed files with 625 additions and 143 deletions
--- a/docs/tabs/index.md
+++ b/docs/tabs/index.md
@@ -5,123 +5,346 @@ toc: true

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

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

-<h2 id="examples" lay-toc="{hot: true}" style="margin-bottom: 0;">示例</h2>
+<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="{}">API</h2>
-
-该组件继承 `component` 提供的[基础接口](../component/#inherit)，并在此基础上为组件专门扩展了以下接口：
+<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, options)](#add) | 新增一个标签项。|
-| [tabs.close(id, index)](#close) | 关闭指定的标签项。|
-| [tabs.closeMore(id, type, index)](#closeMore) | 批量关闭标签项。|
-| [tabs.change(id, index)](#change) | 切换到指定的标签项。|
-| [tabs.data(id)](#data) | 获取当前标签页信息。|
-| [tabs.headerItem(id, index)](#headerItem) | 获取指定的标签头部项。|
-| [tabs.bodyItem(id, index)](#bodyItem) | 获取指定的标签内容项。|
-| [tabs.setView(id)](#setView) | 重新调整标签视图结构。|
+| [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);`
+`tabs.render(options)`

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

-tabs 组件会在元素加载完毕后，默认自动对 `class="layui-tabs"` 目标元素完成一次渲染，如果无法找到默认的目标元素，可使用该方法完成标签的初始化渲染。
+组件支持以下三种渲染方式：

-<h3 id="options" lay-toc="{level: 2, hot: true}">属性</h3>
+#### 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" lay-toc="{level: 2}">新增标签</h3>
+<h3 id="add" class="ws-anchor ws-bold">新增标签</h3>

-`tabs.add(id, options);`
+`tabs.add(id, opts)`

- 参数 `id` : tabs 容器的唯一 id 标识
- 参数 `options` : 标签配置项
-  ```js
-  {
-    title: '标题', // 标签标题
-    content: '内容', // 标签内容
-    id: 'xxx', // 标签的 lay-id 属性值
-    mode: 'append', // 插入模式。可选值: append/prepend/curr
-    unclosed: true, // 是否禁止关闭。默认 false
-    done: function(obj){} // 标签添加完毕的回调
-  }
-  ```
+- 参数 `id` :  组件的实例 ID
+- 参数 `opts` : 标签配置项。可选项详见下表

-<h3 id="close" lay-toc="{level: 2}">关闭标签</h3>
+| 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.close(id, index);`
+该方法用于给对应的 tabs 实例新增一个标签

- 参数 `id` : tabs 容器的唯一 id 标识
- 参数 `index` : 标签项的索引或 lay-id 属性值
+```js
+tabs.add('test', {
+  title: 'New Tab 1',
+  content: 'New Tab Content 1',
+});
+```

-<h3 id="closeMore" lay-toc="{level: 2}">批量关闭标签</h3>
+<h3 id="close" class="ws-anchor ws-bold">关闭标签</h3>

-`tabs.closeMore(id, type, index);`
+`tabs.close(id, index, force)`

- 参数 `id` : tabs 容器的唯一 id 标识
- 参数 `type` : 关闭类型。可选值：
-  - `'all'` : 关闭所有标签
-  - `'other'` : 关闭其他标签
-  - `'left'` : 关闭左侧标签
-  - `'right'` : 关闭右侧标签
- 参数 `index` : 标签项的索引或 lay-id 属性值，用于定位基准点
+- 参数 `id` : 组件的实例 ID
+- 参数 `index` : 标签索引或标签的 `lay-id` 属性值
+- 参数 `force` : 是否强制关闭。若设置 `true` 将忽略 `beforeClose` 事件行为。默认 `false`

-<h3 id="change" lay-toc="{level: 2}">切换标签</h3>
+该方法用于关闭指定的标签项。

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

- 参数 `id` : tabs 容器的唯一 id 标识
- 参数 `index` : 标签项的索引或 lay-id 属性值
+<h3 id="closeMult" class="ws-anchor ws-bold">批量关闭标签</h3>

-<h3 id="data" lay-toc="{level: 2}">获取标签信息</h3>
+`tabs.closeMult(id, mode, index)`

-`tabs.data(id);`
+- 参数 `id` : 组件的实例 ID
+- 参数 `mode` : 关闭方式。支持以下可选值：

- 参数 `id` : tabs 容器的唯一 id 标识
- 返回值：包含当前标签页信息的对象
-  ```js
-  {
-    index: 0, // 当前标签项的索引
-    prevIndex: -1, // 上一个标签项的索引
-    headerElem: {}, // 当前标签头部元素
-    bodyElem: {} // 当前标签内容元素
-  }
-  ```
+| mode | 描述 |
+| --- | --- |
+| other | 关闭除当前标签外的所有标签 |
+| right | 关闭当前标签及右侧标签 |
+| all | 关闭所有标签 |

-<h3 id="headerItem" lay-toc="{level: 2}">获取标签头部项</h3>
+- 参数 `index` : 活动标签的索引或 `lay-id` 属性值，默认取当前选中标签的索引。一般用于标签右键事件。

-`tabs.headerItem(id, index);`
+该方法用于批量关闭标签。

- 参数 `id` : tabs 容器的唯一 id 标识
- 参数 `index` : 标签项的索引或 lay-id 属性值
- 返回值：标签头部项的 DOM 元素
+```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="bodyItem" lay-toc="{level: 2}">获取标签内容项</h3>
+<h3 id="change" class="ws-anchor ws-bold">切换标签</h3>

-`tabs.bodyItem(id, index);`
+`tabs.change(id, index, force)`

- 参数 `id` : tabs 容器的唯一 id 标识
- 参数 `index` : 标签项的索引或 lay-id 属性值
- 返回值：标签内容项的 DOM 元素
+- 参数 `id` : 组件的实例 ID
+- 参数 `index` : 标签索引或标签的 `lay-id` 属性值
+- 参数 `force` : 是否强制切换。若设置 `true` 将忽略 `beforeChange` 事件行为。默认 false

-<h3 id="setView" lay-toc="{level: 2}">重新调整视图</h3>
+该方法用于切换到指定的标签项。

-`tabs.setView(id);`
+```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" 的标签
+```

- 参数 `id` : tabs 容器的唯一 id 标识
- 描述：用于重新调整标签视图结构，如在容器尺寸变化时调用
+<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 组件。