m8-framework-mcp 1.0.0

package/docs/m8mpdoc-develop/009-UI/347/273/204/344/273/266/048-tab/346/240/207/347/255/276/351/241/265.md

@@ -0,0 +1,577 @@
+# 组件使用
+
+## tab 标签页
+
+### 介绍
+
+-   `Tab`标签页。
+
+### 代码演示
+
+#### 基础用法
+
+通过 `v-model` 绑定当前激活标签对应的索引值，默认情况下启用第一个标签。
+
+```html
+<em-tabs v-model="active">
+    <em-tab title="标签 1">内容 1</em-tab>
+    <em-tab title="标签 2">内容 2</em-tab>
+    <em-tab title="标签 3">内容 3</em-tab>
+    <em-tab title="标签 4">内容 4</em-tab>
+</em-tabs>
+```
+
+::: ifdef M83
+
+```js
+export default {
+    data() {
+        return {
+            active: 0
+        };
+    }
+};
+```
+
+::: endif
+::: ifdef M84
+
+```js
+import { ref } from 'vue';
+const active = ref(0);
+```
+
+::: endif
+
+#### 子级扩展
+
+通过`sub-tabs`可设置标签的默认子级扩展，通过`@subTabClick`设置扩展选项点击事项。
+也可以通过名为`subtab`的插槽设置自定义的子级扩展内容。
+
+```html
+<em-tabs v-model="active">
+    <em-tab title="选中项目" :sub-tabs="subTabs" @subTabClick="subTabClick">
+        <div class="tab-content">默认的横向扩展</div>
+    </em-tab>
+    <em-tab title="标签 2">
+        <template v-slot:subtab>
+            <div class="sub-content">自定义子级扩展内容</div>
+        </template>
+        <div class="tab-content">内容 2</div>
+    </em-tab>
+</em-tabs>
+```
+::: ifdef M83
+```js
+export default {
+    data() {
+        return {
+            active: 0,
+            subTabs: [
+                {
+                    text: '选项1',
+                    value: 1,
+                    checked: true
+                },
+                {
+                    text: '选项2',
+                    value: 2
+                },
+                {
+                    text: '选项3',
+                    value: 3
+                },
+                {
+                    text: '选项4',
+                    value: 4
+                }
+            ]
+        };
+    },
+    methods: {
+        subTabClick(item, index) {
+            Toast(item.text);
+        }
+    }
+};
+```
+::: endif
+::: ifdef M84
+```js
+import { ref } from 'vue';
+const active = ref(0);
+const subTabs = [
+    {
+        text: '选项1',
+        value: 1,
+        checked: true
+    },
+    {
+        text: '选项2',
+        value: 2
+    },
+    {
+        text: '选项3',
+        value: 3
+    },
+    {
+        text: '选项4',
+        value: 4
+    }
+];
+const subTabClick = (item, index) => {
+    Toast(item.text);
+};
+```
+::: endif
+
+#### 下拉
+
+通过`isDropdown`可设置标签是否可下拉。
+组件提供两种默认的子级扩展，可通过`sub-direction`设置展示为横向`horizontal`或纵向`vertical`。
+
+```html
+<em-tabs v-model="active">
+    <em-tab title="选中项目" :sub-tabs="subTabs" :isDropdown="true" sub-direction="vertical" @subTabClick="subTabClick">
+        <div class="tab-content-down">默认的纵向扩展</div>
+    </em-tab>
+    <em-tab title="标签 2" :sub-tabs="subTabs" :isDropdown="true" sub-direction="horizontal" @subTabClick="subTabClick">
+        <div class="tab-content-down">默认的横向扩展</div>
+    </em-tab>
+    <em-tab title="标签 3" :isDropdown="true">
+        <template v-slot:subtab>
+            <div class="sub-content">自定义子级扩展内容</div>
+        </template>
+        <div class="tab-content-down">内容 3</div>
+    </em-tab>
+</em-tabs>
+```
+::: ifdef M83
+```js
+export default {
+    data() {
+        return {
+            active: 0,
+            subTabs: [
+                {
+                    text: '选项1',
+                    value: 1,
+                    checked: true
+                },
+                {
+                    text: '选项2',
+                    value: 2
+                },
+                {
+                    text: '选项3',
+                    value: 3
+                },
+                {
+                    text: '选项4',
+                    value: 4
+                }
+            ]
+        };
+    },
+    methods: {
+        subTabClick(item, index) {
+            Toast(item.text);
+        }
+    }
+};
+```
+::: endif
+::: ifdef M84
+```js
+import { ref } from 'vue';
+const active = ref(0);
+const subTabs = [
+    {
+        text: '选项1',
+        value: 1,
+        checked: true
+    },
+    {
+        text: '选项2',
+        value: 2
+    },
+    {
+        text: '选项3',
+        value: 3
+    },
+    {
+        text: '选项4',
+        value: 4
+    }
+];
+const subTabClick = (item, index) => {
+    Toast(item.text);
+};
+```
+::: endif
+
+#### 同级扩展
+
+标签数量较多时，通过`putaway`可设置同级扩展。
+
+```html
+<em-tabs v-model="active" :putaway="true">
+    <em-tab v-for="item in [1,2,3,4,5,6,7,8,9]" :key="item" :title="`标签 ${item}`">
+        <div class="tab-content">内容 {{item}}</div>
+    </em-tab>
+</em-tabs>
+```
+::: ifdef M83
+```js
+export default {
+    data() {
+        return {
+            active: 0
+        };
+    }
+};
+```
+::: endif
+::: ifdef M84
+```js
+import { ref } from 'vue';
+const active = ref(0);
+```
+::: endif
+
+#### 通过名称匹配
+
+在标签指定 `name` 属性的情况下，`v-model` 的值为当前标签的 `name`（此时无法通过索引值来匹配标签）。
+
+```html
+<em-tabs v-model="activeName">
+    <em-tab title="标签 1" name="a">内容 1</em-tab>
+    <em-tab title="标签 2" name="b">内容 2</em-tab>
+    <em-tab title="标签 3" name="c">内容 3</em-tab>
+</em-tabs>
+```
+::: ifdef M83
+```js
+export default {
+    data() {
+        return {
+            activeName: 'a'
+        };
+    }
+};
+```
+::: endif
+::: ifdef M84
+```js
+import { ref } from 'vue';
+const activeName = ref('a');
+```
+::: endif
+
+#### 标签栏滚动
+
+标签数量超过 `5` 个时，标签栏可以在水平方向上滚动，切换时会自动将当前标签居中。
+
+```html
+<em-tabs>
+    <em-tab v-for="index in 8" :title="'标签 ' + index">内容 {{ index }}</em-tab>
+</em-tabs>
+```
+
+#### 禁用标签
+
+设置 `disabled` 属性即可禁用标签，如果需要监听禁用标签的点击事件，可以在 `em-tabs` 上监听`disabled` 事件。
+
+```html
+<em-tabs @disabled="onClickDisabled">
+    <em-tab title="标签 1">内容 1</em-tab>
+    <em-tab title="标签 2" disabled>内容 2</em-tab>
+    <em-tab title="标签 3">内容 3</em-tab>
+</em-tabs>
+```
+::: ifdef M83
+```js
+export default {
+    methods: {
+        onClickDisabled(name, title) {
+            Toast(name + '已被禁用');
+        }
+    }
+};
+```
+::: endif
+::: ifdef M84
+```js
+const onClickDisabled = (name, title) => {
+    Toast(name + '已被禁用');
+};
+```
+::: endif
+
+#### 样式风格
+
+`Tab` 支持两种样式风格：`line` 和`card`，默认为 `line` 样式，可以通过 `type` 属性切换样式风格。
+
+```html
+<em-tabs type="card">
+    <em-tab title="标签 1">内容 1</em-tab>
+    <em-tab title="标签 2">内容 2</em-tab>
+    <em-tab title="标签 3">内容 3</em-tab>
+</em-tabs>
+```
+
+#### 点击事件
+
+可以在 `em-tabs` 上绑定 `click` 事件，事件传参为标签对应的标识符和标题。
+
+```html
+<em-tabs @click="onClick">
+    <em-tab title="标签 1">内容 1</em-tab>
+    <em-tab title="标签 2">内容 2</em-tab>
+</em-tabs>
+```
+::: ifdef M83
+```js
+export default {
+    methods: {
+        onClick(name, title) {
+            Toast(title);
+        }
+    }
+};
+```
+::: endif
+::: ifdef M84
+```js
+const onClick = (name, title) => {
+    Toast(title);
+};
+```
+::: endif
+
+#### 粘性布局
+
+通过 `sticky` 属性可以开启粘性布局，粘性布局下，标签页滚动到顶部时会自动吸顶。
+
+**TIP:** 使用粘性布局时，微信小程序中，页面上需要添加`onPageScroll`函数用于监听页面滚动
+
+```html
+<em-tabs v-model="active" sticky>
+    <em-tab v-for="index in 4" :title="'选项 ' + index">内容 {{ index }}</em-tab>
+</em-tabs>
+```
+
+#### 切换动画
+
+通过 `animated` 属性可以开启切换标签内容时的转场动画。
+
+```html
+<em-tabs v-model="active" animated>
+    <em-tab v-for="index in 4" :title="'选项 ' + index">内容 {{ index }}</em-tab>
+</em-tabs>
+```
+
+#### 滑动切换
+
+通过 `swipeable` 属性可以开启滑动切换标签页。
+
+```html
+<em-tabs v-model="active" swipeable>
+    <em-tab v-for="index in 4" :title="'选项 ' + index">内容 {{ index }}</em-tab>
+</em-tabs>
+```
+
+#### 滚动导航
+
+通过 `scrollspy` 属性可以开启滚动导航模式，该模式下，内容将会平铺展示。
+
+**TIP:** 使用粘性布局时，微信小程序中，页面上需要添加`onPageScroll`函数用于监听页面滚动。
+
+tab 组件的父级容器及祖先容器的`overflow`只能是`visible`。
+
+```html
+<em-tabs v-model="active" scrollspy sticky>
+    <em-tab v-for="index in 8" :title="'选项 ' + index">内容 {{ index }}</em-tab>
+</em-tabs>
+```
+
+#### 异步切换
+
+通过 `before-change` 属性可以在切换标签前执行特定的逻辑。
+
+```html
+<em-tabs :before-change="beforeChange">
+    <em-tab v-for="index in 4" :title="'选项 ' + index">内容 {{ index }}</em-tab>
+</em-tabs>
+```
+::: ifdef M83
+```js
+export default {
+    methods: {
+        beforeChange(index) {
+            // 返回 false 表示阻止此次切换
+            if (index === 1) {
+                return false;
+            }
+
+            // 返回 Promise 来执行异步逻辑
+            return new Promise((resolve) => {
+                // 在 resolve 函数中返回 true 或 false
+                resolve(index !== 3);
+            });
+        }
+    }
+};
+```
+::: endif
+::: ifdef M84
+```js
+const beforeChange = (index) => {
+    // 返回 false 表示阻止此次切换
+    if (index === 1) {
+        return false;
+    }
+
+    // 返回 Promise 来执行异步逻辑
+    return new Promise((resolve) => {
+        // 在 resolve 函数中返回 true 或 false
+        resolve(index !== 3);
+    });
+};
+```
+::: endif
+
+### API
+
+#### Tabs Props
+
+| 参数                                                                         | 说明                                                                 | 类型                        | 默认值    |
+| :--------------------------------------------------------------------------- | :------------------------------------------------------------------- | :-------------------------- | :-------- |
+| v-model ::: ifdef M83 (value) ::: endif ::: ifdef M84 (modelValue) ::: endif | 绑定当前选中标签的标识符                                             | number / string             | `0`       |
+| type                                                                         | 样式风格类型，可选值为 `card`                                        | string                      | `line`    |
+| color                                                                        | 标签主题色                                                           | string                      | `#2e6be5` |
+| background                                                                   | 标签栏背景色                                                         | string                      | `white`   |
+| duration                                                                     | 动画时间，单位秒                                                     | number / string             | `0.3`     |
+| line-width                                                                   | 底部条宽度，默认单位`px`                                             | number / string             | `30px`    |
+| line-height                                                                  | 底部条高度，默认单位`px`                                             | number / string             | `3px`     |
+| line-skew                                                                    | 是否开启底部条两端倾斜角度效果                                       | boolean                     | `true`    |
+| animated                                                                     | 是否开启切换标签内容时的转场动画                                     | boolean                     | `false`   |
+| border                                                                       | 是否显示标签栏外边框，仅在 `type="line"`时有效                       | boolean                     | `true`    |
+| ellipsis                                                                     | 是否省略过长的标题文字                                               | boolean                     | `true`    |
+| sticky                                                                       | 是否使用粘性定位布局                                                 | boolean                     | `false`   |
+| scrollspy                                                                    | 是否使用滚动导航                                                     | boolean                     | `false`   |
+| swipeable                                                                    | 是否开启手势滑动切换                                                 | boolean                     | `false`   |
+| lazy-render                                                                  | 是否开启延迟渲染（首次切换到标签时才触发内容渲染）                   | boolean                     | `true`    |
+| offset-top                                                                   | 粘性定位布局下与顶部的最小距离，支持 `px` `vw` `rem` 单位，默认 `px` | number / string             | `0`       |
+| swipe-threshold                                                              | 滚动阈值，标签数量超过阈值时开始横向滚动                             | number / string             | `5`       |
+| title-active-color                                                           | 标题选中态颜色                                                       | string                      | -         |
+| title-inactive-color                                                         | 标题默认态颜色                                                       | string                      | -         |
+| before-change                                                                | 切换标签前的回调函数，返回 `false` 可阻止切换，支持返回 `Promise`    | (name) => boolean / Promise | -         |
+| putaway                                                                      | 标签数过多时是否展示同级扩展                                         | boolean                     | `false`   |
+| shrink                                                                       | 标签是否开启左对齐                                                   | boolean                     | `false`   |
+| pop-height `v8.3.7`                                                          | 自定义下拉弹窗的高度，单位为`px`                                     | string/number               | -         |
+
+#### Tab Props
+
+| 参数         | 说明                                                                                          | 类型            | 默认值       |
+| :----------- | :-------------------------------------------------------------------------------------------- | :-------------- | :----------- |
+| title        | 标题                                                                                          | string          | -            |
+| disabled     | 是否禁用标签                                                                                  | boolean         | `false`      |
+| dot          | 是否在标题右上角显示小红点                                                                    | boolean         | `false`      |
+| badge        | 图标右上角徽标的内容                                                                          | number / string | -            |
+| name         | 标签名称，作为匹配的标识符                                                                    | number / string | 标签的索引值 |
+| url          | 点击后跳转的链接地址                                                                          | string          | -            |
+| to           | 点击后跳转的目标路由对象，同 `vue-router` 的 `to` 属性，仅支持`path` `query` `replace` `hash` | string / object | -            |
+| replace      | 是否在跳转时替换当前页面历史                                                                  | boolean         | `false`      |
+| title-style  | 自定义标题样式                                                                                | any             | -            |
+| subTabs      | 子级扩展列表                                                                                  | array           | -            |
+| subDirection | 子级扩展排列方向，可选值：` horizontal``vertical `                                            | string          | `horizontal` |
+| isDropdown   | 是否下拉                                                                                      | boolean         | `false`      |
+| overlay      | 下拉时是否需要遮罩                                                                            | boolean         | `true`       |
+
+#### Tab subTab 数据格式
+
+| 参数    | 说明                                                                       | 类型    |
+| :------ | :------------------------------------------------------------------------- | :------ |
+| text    | 选项文字                                                                   | string  |
+| value   | 选项值                                                                     | string  |
+| checked | 是否已选中，初始化时可通过该参数设置默认选中项，注意：默认子级扩展都是单选 | boolean |
+
+#### Tabs Events
+
+| 事件名         | 说明                                             | 回调参数                                           |
+| :------------- | :----------------------------------------------- | :------------------------------------------------- |
+| click          | 点击标签时触发                                   | `name`：标识符，`title`：标题                      |
+| change         | 当前激活的标签改变时触发                         | `name`：标识符，`title`：标题                      |
+| disabled       | 点击被禁用的标签时触发                           | `name`：标识符，`title`：标题                      |
+| rendered       | 标签内容首次渲染时触发（仅在开启延迟渲染后触发） | `name`：标识符，`title`：标题                      |
+| scroll         | 滚动时触发，仅在 `sticky` 模式下生效             | { `scrollTop`: 距离顶部位置, `isFixed`: 是否吸顶 } |
+| load `v8.3.14` | mounted 中触发                                   | -                                                  |
+
+#### Tab Events
+
+| 事件名         | 说明                                   | 回调参数                            |
+| :------------- | :------------------------------------- | :---------------------------------- |
+| subTabClick    | 使用默认子级扩展时，点击扩展选项的事件 | `item`：选中项，`index`：选中项索引 |
+| load `v8.3.14` | mounted 中触发                         | -                                   |
+
+#### Tabs 方法
+
+通过 ref 可以获取到 Tabs 实例并调用实例方法，详见组件实例方法
+
+| 方法名 | 说明                                         | 参数 | 返回值 |
+| :----- | :------------------------------------------- | :--- | :----- |
+| resize | 外层元素大小变化后，可以调用此方法来触发重绘 | -    | `void` |
+
+#### Tab 方法
+
+通过 ref 可以获取到 Tab 实例并调用实例方法，详见组件实例方法
+
+| 方法名     | 说明                                 | 参数 | 返回值 |
+| :--------- | :----------------------------------- | :--- | :----- |
+| triggerPop | 使用下拉时，可通过此方法切换下拉状态 | -    | `void` |
+
+#### Tabs Slots
+
+| 名称     | 说明         |
+| :------- | :----------- |
+| navLeft  | 标题左侧内容 |
+| navRight | 标题右侧内容 |
+
+#### Tab Slots
+
+| 名称    | 说明           |
+| :------ | :------------- |
+| default | 标签页内容     |
+| subtab  | 自定义子级扩展 |
+
+::: ifdef M83
+<iframe
+ src="//app.epoint.com.cn/m8mpdoc/showcase/index.html#/modules/m8showcase/examples/em-tab"
+ frameborder=0
+ allowfullscreen class="ui-showcase-iframe">
+  </iframe>
+::: endif
+::: ifdef M84
+<iframe
+ src="//app.epoint.com.cn/m8mpdoc/showcase/m8.4/index.html#/modules/m8showcase/examples/em-tab"
+ frameborder=0
+ allowfullscreen class="ui-showcase-iframe">
+  </iframe>
+::: endif
+
+ <style>
+ .ui-showcase-iframe {
+    position: fixed;
+    right: 3.5vw;
+    top: 17%;
+    width: 375px;
+    height: 75vh;
+    box-shadow: 0 0 12px 6px #eee;
+    border-radius: 15px;
+ }
+ .main .markdown-body {
+    padding: 45px;
+    width: calc(97vw - 661px);
+}
+ </style>