@fox-js/phone-skills 4.0.1-0

package/foxui/references/fox-tabs-bar/doc.md

@@ -0,0 +1,533 @@
+<!--
+ * @Author: 江成
+ * @Date: 2026-04-27 00:37:28
+ * @LastEditors: 江成
+ * @LastEditTime: 2026-05-12 22:33:21
+-->
+---
+title: TabsBar 组件使用规范
+impact: HIGH
+type: capability
+description: 选项卡栏
+tags: [foxui, fox-tabs-bar, FoxTabsBar]
+version: "4.0.0"
+author: jiangcheng
+related: ["fox-js","fox-tabs-container","fox-tabs-pane","fox-tabs-frame","fox-tabs","fox-tabpane"]
+---
+
+# TabsBar 组件使用规范
+
+## 1. 核心职责 (Core Responsibility)
+TabsBar 是 foxui 中用于 **选项卡栏** 的标准组件。
+- **基于**: NutUI `nut-tabs-bar` 进行了二次封装 (若为纯自研组件则填 "自定义开发")
+- **核心增强**: 基于 NutUI 组件二次封装、支持 v-model 双向绑定、适配 H5 与小程序多端、支持插槽扩展自定义内容、支持主题定制
+- **适用场景**: 选项卡栏
+
+> 💡 **关键原则**: 在所有 选项卡栏 中，**必须**优先使用此组件，禁止直接使用原生 NutUI 组件。
+
+---
+
+## 2. 关键 API 说明 (Key API)
+
+### 2.1 Props 属性
+
+| 属性名 | 类型 | 必填 | 默认值 | 说明 |
+| :--- | :--- | :---: | :---: | :--- |
+| `v-model` | 绑定当前选中标签的标识符 | number,string | - |
+| `direction` | 是否支持拖拽 |  'horizontal' | 'vertical' |
+| `width` | 容器宽度 | string/number |
+| `height` | 容器高度 | string/number |
+
+### 2.2 Events 事件
+
+| 事件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `change` | 当前激活的标签改变时触发 | item, index |
+
+### 2.3 Methods 方法
+
+| 方法名 | 参数 | 说明 |
+| :--- | :--- | :--- |
+无
+
+### 2.4 Slots 插槽
+
+| 插槽名 | 说明 |
+| :--- | :--- |
+| `item` | 自定义标签 |
+| `text` | 自定义text |
+| `navigation` | 导航插槽 |
+| `popupItem` | 快速导航标签插槽 |
+| `navigation` | 导航插槽 |
+| `leftArrow` | 左箭头插槽 |
+| `rightArrow` | 左箭头插槽 |
+
+## 3. 例子 (Examples)
+
+## 代码演示
+
+### 基础用法
+```html
+<template>
+ <h2>基础用法</h2>
+ <fox-tabs-bar v-model="baseSelectedValue" :data="baseTabs"></fox-tabs-bar>
+</template>
+<script lang="ts" setup>
+ // 基础数据源
+ const baseTabs = [
+  {
+    text: 'Tab 1',
+    value: '01'
+  },
+  {
+    text: 'Tab 2',
+    value: '02'
+  },
+  {
+    text: 'Tab 3',
+    value: '03'
+  }
+]
+// base selected value
+const baseSelectedValue = ref('01')
+</script>
+```
+### 左对齐
+通过属性`align`设置标签左对齐
+```html
+<template>
+ <h2>左对齐</h2>
+ <fox-tabs-bar v-model="leftSelectedValue" :data="baseTabs" align="left"></fox-tabs-bar>
+</template>
+<script lang="ts" setup>
+ // 基础数据源
+ const baseTabs = [
+  {
+    text: 'Tab 1',
+    value: '01'
+  },
+  {
+    text: 'Tab 2',
+    value: '02'
+  },
+  {
+    text: 'Tab 3',
+    value: '03'
+  }
+]
+// left selected value
+const leftSelectedValue = ref('')
+</script>
+```
+### 可滚动
+在数量过多的情况下，通过属性`scroll`设置标签可滚动
+```html
+<template>
+ <h2>可滚动</h2>
+ <fox-tabs-bar v-model="moreSelectedValue" :data="moreTabs" :scroll="true" gutter="10px"></fox-tabs-bar>
+</template>
+<script lang="ts" setup>
+// 更多数据源
+const moreTabs = [
+  {
+    text: 'Tab 1',
+    value: '01'
+  },
+  {
+    text: 'Tab 2',
+    value: '02'
+  },
+  {
+    text: 'Tab 3',
+    value: '03'
+  },
+  {
+    text: 'Tab 4',
+    value: '04'
+  },
+  {
+    text: 'Tab 5',
+    value: '05'
+  },
+  {
+    text: 'Tab 6',
+    value: '06'
+  },
+  {
+    text: 'Tab 7',
+    value: '07'
+  },
+  {
+    text: 'Tab 8',
+    value: '08'
+  },
+  {
+    text: 'Tab 9',
+    value: '09'
+  },
+  {
+    text: 'Tab 10',
+    value: '10'
+  }
+]
+// more selected value
+const moreSelectedValue = ref('')
+</script>
+```
+### 标签形状
+可以通过属性`shape`设置标签的形状
+```html
+<template>
+   <h2>按钮形状</h2>
+    <fox-tabs-bar v-model="buttonSelectedValue" :data="moreTabs" :scroll="true" shape="button"></fox-tabs-bar>
+    <h2>按钮组形状</h2>
+    <fox-tabs-bar v-model="buttonGroupSelectedValue" :data="buttonGroupTabs" shape="button-group"></fox-tabs-bar>
+    <h2>胶囊形状</h2>
+    <fox-tabs-bar
+      v-model="capsuleGroupSelectedValue"
+      :data="capsuleGroupTabs"
+      shape="capsule"
+      :scroll="true"
+    ></fox-tabs-bar>
+ </template>
+<script lang="ts" setup>
+// 更多数据源
+export const moreTabs = [
+  {
+    text: 'Tab 1',
+    value: '01'
+  },
+  {
+    text: 'Tab 2',
+    value: '02'
+  },
+  {
+    text: 'Tab 3',
+    value: '03'
+  },
+  {
+    text: 'Tab 4',
+    value: '04'
+  },
+  {
+    text: 'Tab 5',
+    value: '05'
+  },
+  {
+    text: 'Tab 6',
+    value: '06'
+  },
+  {
+    text: 'Tab 7',
+    value: '07'
+  },
+  {
+    text: 'Tab 8',
+    value: '08'
+  },
+  {
+    text: 'Tab 9',
+    value: '09'
+  },
+  {
+    text: 'Tab 10',
+    value: '10'
+  }
+]
+// 按钮组tabs
+export const buttonGroupTabs = [
+  {
+    text: '按钮组1',
+    value: '01'
+  },
+  {
+    text: '按钮组2',
+    value: '02'
+  },
+  {
+    text: '按钮组3',
+    value: '03'
+  }
+]
+// 胶囊tabs
+export const capsuleGroupTabs = [
+  {
+    text: '胶囊1',
+    value: '01'
+  },
+  {
+    text: '胶囊2',
+    value: '02'
+  },
+  {
+    text: '胶囊3',
+    value: '03'
+  },
+  {
+    text: '胶囊4',
+    value: '04'
+  }
+]
+// button shape selected value
+const buttonSelectedValue = ref('06')
+// button group shape selected value
+const buttonGroupSelectedValue = ref('')
+// capsule group shape selected value
+const capsuleGroupSelectedValue = ref('')
+</script>
+```
+### 快速导航
+```html
+<template>
+ <h2>快速导航</h2>
+ <fox-tabs-bar
+      v-model="quickSelectedValue"
+      :data="moreTabs"
+      :scroll="true"
+      :show-quick-navigation="true"
+      shape="button"
+  ></fox-tabs-bar>
+ </template>
+<script lang="ts" setup>
+// 更多数据源
+export const moreTabs = [
+  {
+    text: 'Tab 1',
+    value: '01'
+  },
+  {
+    text: 'Tab 2',
+    value: '02'
+  },
+  {
+    text: 'Tab 3',
+    value: '03'
+  },
+  {
+    text: 'Tab 4',
+    value: '04'
+  },
+  {
+    text: 'Tab 5',
+    value: '05'
+  },
+  {
+    text: 'Tab 6',
+    value: '06'
+  },
+  {
+    text: 'Tab 7',
+    value: '07'
+  },
+  {
+    text: 'Tab 8',
+    value: '08'
+  },
+  {
+    text: 'Tab 9',
+    value: '09'
+  },
+  {
+    text: 'Tab 10',
+    value: '10'
+  }
+]
+// quick selected value
+const quickSelectedValue = ref('06')
+</script>
+```
+
+### 箭头指示
+```html
+<template>
+ <h2>箭头指示</h2>
+    <fox-tabs-bar
+      v-model="scrollArrowSelectedValue"
+      :data="moreTabs"
+      :scroll="true"
+      :show-scroll-arrow="true"
+      shape="button"
+    ></fox-tabs-bar>
+ </template>
+<script lang="ts" setup>
+// 更多数据源
+export const moreTabs = [
+  {
+    text: 'Tab 1',
+    value: '01'
+  },
+  {
+    text: 'Tab 2',
+    value: '02'
+  },
+  {
+    text: 'Tab 3',
+    value: '03'
+  },
+  {
+    text: 'Tab 4',
+    value: '04'
+  },
+  {
+    text: 'Tab 5',
+    value: '05'
+  },
+  {
+    text: 'Tab 6',
+    value: '06'
+  },
+  {
+    text: 'Tab 7',
+    value: '07'
+  },
+  {
+    text: 'Tab 8',
+    value: '08'
+  },
+  {
+    text: 'Tab 9',
+    value: '09'
+  },
+  {
+    text: 'Tab 10',
+    value: '10'
+  }
+]
+// scroll arrow selected value
+const scrollArrowSelectedValue = ref('')
+</script>
+```
+
+### 徽标提示
+```html
+<template>
+ <h2>徽标提示</h2>
+ <fox-tabs-bar v-model="logoTipsSelectedValue" :data="baseTabs" :item-options="logoTipsItemOptions"></fox-tabs-bar>
+    <fox-tabs-container v-model="logoTipsSelectedValue">
+      <fox-tabs-pane v-for="(tab, index) in baseTabs" :pane-key="tab.value" :key="tab.value">
+        <div style="text-align: center; padding: 30px">{{ tab.text }}</div>
+      </fox-tabs-pane>
+    </fox-tabs-container>
+ </template>
+<script lang="ts" setup>
+// 基础数据源
+export const baseTabs = [
+  {
+    text: 'Tab 1',
+    value: '01'
+  },
+  {
+    text: 'Tab 2',
+    value: '02'
+  },
+  {
+    text: 'Tab 3',
+    value: '03'
+  }
+]
+// 徽标提示 selected value
+const logoTipsSelectedValue = ref('')
+//徽标提示
+const logoTipsItemOptions = (item: Record<string, any>, index: number) => {
+  if (index === 0) {
+    return {
+      doit: true
+    }
+  } else if (index === 1) {
+    return {
+      num: 11
+    }
+  }
+  return null
+}
+</script>
+```
+### 竖向排列
+```html
+<h2>竖向排列</h2>
+<fox-tabs-bar
+  v-model="verticalSelectedValue"
+  :data="baseTabs"
+  direction="vertical"
+  style="height: 120px"
+></fox-tabs-bar>
+<h2>可滚动(竖向)</h2>
+<fox-tabs-bar
+  v-model="verticalMoreSelectedValue"
+  :data="moreTabs"
+  direction="vertical"
+  :scroll="true"
+  gutter="1rem"
+  style="height: 200px"
+></fox-tabs-bar>
+```
+
+### 可拖拽
+在组件`fox-tabs-container`中设置`draggle`属性，可开启拖拽支持
+
+
+```html
+<template>
+ <h2>可以拖拽</h2>
+    <fox-tabs-bar v-model="draggleSelectedValue" :data="baseTabs"></fox-tabs-bar>
+    <fox-tabs-container v-model="draggleSelectedValue" :draggle="true">
+      <fox-tabs-pane v-for="(tab, index) in baseTabs" :pane-key="tab.value" :key="tab.value">
+        <div style="text-align: center; padding: 30px">{{ tab.text }}</div>
+      </fox-tabs-pane>
+    </fox-tabs-container>
+</template> 
+
+<script lang="ts" setup>
+ // 基础数据源
+ const baseTabs = [
+  {
+    text: 'Tab 1',
+    value: '01'
+  },
+  {
+    text: 'Tab 2',
+    value: '02'
+  },
+  {
+    text: 'Tab 3',
+    value: '03'
+  }
+]
+// draggle selected value
+const draggleSelectedValue = ref('01')
+</script>
+```
+
+
+### 简易用法
+
+在组件`fox-tabs-frame`提供了`fox-tabs-bar`和`fox-tabs-container`的简易用法
+
+```html
+<template>
+  <h2 style="margin: 10px 0px">基本用法(tab水平排列)</h2>
+  <fox-tabs-frame v-model="activeName" align="left">
+    <fox-tabs-pane label="User" pane-key="first">User</fox-tabs-pane>
+    <fox-tabs-pane label="Config" pane-key="second">Config</fox-tabs-pane>
+    <fox-tabs-pane label="Role" pane-key="third">Role</fox-tabs-pane>
+    <fox-tabs-pane label="Task" pane-key="fourth">Task</fox-tabs-pane>
+  </fox-tabs-frame>
+
+  <h2 style="margin: 10px 0px">基本用法(tab竖向排列)</h2>
+  <fox-tabs-frame v-model="activeName" align="left" direction="vertical" height="250px">
+    <fox-tabs-pane label="User" pane-key="first">User</fox-tabs-pane>
+    <fox-tabs-pane label="Config" pane-key="second">Config</fox-tabs-pane>
+    <fox-tabs-pane label="Role" pane-key="third">Role</fox-tabs-pane>
+    <fox-tabs-pane label="Task" pane-key="fourth">Task</fox-tabs-pane>
+  </fox-tabs-frame>
+</template>
+```
+
+## 4. 相关组件 (Related Components)
+- **fox-js**: 与 TabsBar 配合使用的相关组件
+- **fox-tabs-container**: 与 TabsBar 配合使用的相关组件
+- **fox-tabs-pane**: 与 TabsBar 配合使用的相关组件
+- **fox-tabs-frame**: 与 TabsBar 配合使用的相关组件
+- **fox-tabs**: 与 TabsBar 配合使用的相关组件
+- **fox-tabpane**: 与 TabsBar 配合使用的相关组件
+