xtf-tabbar

组件说明

xtf-tabbar 是底部导航组件，适用于应用一级导航；支持图标、图片、徽标、路由跳转和多种外观。 核心能力以当前 xtf-tabbar.vue 源码为准。

---

基础用法

1. 基础用法

最小配置下即可完成常见业务交互：

<template>
  <xtf-tabbar v-model="value" :list="items" :fixed="false" @change="onEvent" />
</template>

<script>
export default {
  data() {
    return {
      value: 0,
      items: [
        { text: '首页', icon: 'home' },
        { text: '我的', icon: 'user' }
      ]
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

2. 核心交互

监听组件事件并维护页面状态：

<template>
  <xtf-tabbar
    v-model="value"
    :list="items"
    :fixed="false"
    variant="floating"
    show-indicator
    @click-item="onEvent"
  />
</template>

<script>
export default {
  data() {
    return {
      value: 0,
      items: [
        { text: '首页', icon: 'home' },
        { text: '我的', icon: 'user' }
      ]
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

3. 进阶配置

组合布局、样式或插槽能力：

<template>
  <xtf-tabbar
    v-model="value"
    :list="items"
    :fixed="false"
    variant="segment"
    :label-visible="false"
  />
</template>

<script>
export default {
  data() {
    return {
      value: 0,
      items: [
        { text: '首页', icon: 'home' },
        { text: '我的', icon: 'user' }
      ]
    }
  },
  methods: {
    onEvent(payload) {
      console.log('组件事件', payload)
    }
  }
}
</script>

---

全部属性

属性	类型	默认值	作用描述	适用范围
modelValue	Number	undefined	控制组件的 modelValue 行为。	按业务需要设置。
list	Array	函数返回值	控制组件的 list 行为。	按业务需要设置。
value	Number	0	控制组件的 value 行为。	按业务需要设置。
variant	String	'solid'	控制组件的 variant 行为。	按业务需要设置。
shape	String	'auto'	控制组件的 shape 行为。	按业务需要设置。
activeColor	String	'var(--xtf-color-primary)'	控制组件的 activeColor 行为。	按业务需要设置。
inactiveColor	String	'var(--xtf-color-text-secondary)'	控制组件的 inactiveColor 行为。	按业务需要设置。
activeTextColor	String	''	控制组件的 activeTextColor 行为。	按业务需要设置。
inactiveTextColor	String	''	控制组件的 inactiveTextColor 行为。	按业务需要设置。
iconSize	[String, Number]	48	控制组件的 iconSize 行为。	按业务需要设置。
iconOnlySize	[String, Number]	''	控制组件的 iconOnlySize 行为。	按业务需要设置。
mediaType	String	'auto'	控制组件的 mediaType 行为。	按业务需要设置。
imageSize	[String, Number]	48	控制组件的 imageSize 行为。	按业务需要设置。
imageRadius	[String, Number]	16	控制组件的 imageRadius 行为。	按业务需要设置。
imageMode	String	'aspectFit'	控制组件的 imageMode 行为。	按业务需要设置。
backgroundColor	String	'var(--xtf-color-surface)'	控制组件的 backgroundColor 行为。	按业务需要设置。
borderTop	Boolean	true	仅控制根节点的 xtf-tabbar--border class；当前模板中的 .xtf-tabbar__border 节点由未声明的 border 条件控制，borderTop 不会直接显示或隐藏该边框节点。	当前不能用它控制模板边框显隐。
fixed	Boolean	true	控制组件的 fixed 行为。	按业务需要设置。
safeAreaInsetBottom	Boolean	true	控制组件的 safeAreaInsetBottom 行为。	按业务需要设置。
route	Boolean	false	控制组件的 route 行为。	按业务需要设置。
zIndex	Number	100	控制组件的 zIndex 行为。	按业务需要设置。
height	[String, Number]	110	控制组件的 height 行为。	按业务需要设置。
padding	[String, Number]	''	控制组件的 padding 行为。	按业务需要设置。
itemDirection	String	'auto'	控制组件的 itemDirection 行为。	按业务需要设置。
iconPosition	String	'start'	控制组件的 iconPosition 行为。	按业务需要设置。
labelVisible	Boolean	true	控制组件的 labelVisible 行为。	按业务需要设置。
labelSpacing	[String, Number]	''	控制组件的 labelSpacing 行为。	按业务需要设置。
itemAlign	String	'center'	控制组件的 itemAlign 行为。	按业务需要设置。
gap	[String, Number]	''	控制组件的 gap 行为。	按业务需要设置。
itemPadding	[String, Number]	''	控制组件的 itemPadding 行为。	按业务需要设置。
itemRadius	[String, Number]	''	控制组件的 itemRadius 行为。	按业务需要设置。
activeInset	[String, Number]	''	控制组件的 activeInset 行为。	按业务需要设置。
activeRadius	[String, Number]	''	控制组件的 activeRadius 行为。	按业务需要设置。
stackPaddingTop	[String, Number]	''	控制组件的 stackPaddingTop 行为。	按业务需要设置。
stackPaddingBottom	[String, Number]	''	控制组件的 stackPaddingBottom 行为。	按业务需要设置。
iconWrapMinHeight	[String, Number]	''	控制组件的 iconWrapMinHeight 行为。	按业务需要设置。
activeItemBackground	String	''	控制组件的 activeItemBackground 行为。	按业务需要设置。
inactiveItemBackground	String	''	控制组件的 inactiveItemBackground 行为。	按业务需要设置。
showIndicator	Boolean	false	控制组件的 showIndicator 行为。	按业务需要设置。
indicatorStyle	String	'pill'	控制组件的 indicatorStyle 行为。	按业务需要设置。
indicatorColor	String	''	控制组件的 indicatorColor 行为。	按业务需要设置。
indicatorWidth	[String, Number]	''	控制组件的 indicatorWidth 行为。	按业务需要设置。
indicatorHeight	[String, Number]	''	控制组件的 indicatorHeight 行为。	按业务需要设置。
indicatorPosition	String	'auto'	控制组件的 indicatorPosition 行为。	按业务需要设置。
indicatorOffset	[String, Number]	''	控制组件的 indicatorOffset 行为。	按业务需要设置。
itemClass	String	''	控制组件的 itemClass 行为。	按业务需要设置。
itemStyle	[String, Object]	''	控制组件的 itemStyle 行为。	按业务需要设置。
activeItemClass	String	''	控制组件的 activeItemClass 行为。	按业务需要设置。
activeItemStyle	[String, Object]	''	控制组件的 activeItemStyle 行为。	按业务需要设置。
labelClass	String	''	控制组件的 labelClass 行为。	按业务需要设置。
labelStyle	[String, Object]	''	控制组件的 labelStyle 行为。	按业务需要设置。
activeLabelClass	String	''	控制组件的 activeLabelClass 行为。	按业务需要设置。
activeLabelStyle	[String, Object]	''	控制组件的 activeLabelStyle 行为。	按业务需要设置。
iconWrapStyle	[String, Object]	''	控制组件的 iconWrapStyle 行为。	按业务需要设置。
activeIconWrapStyle	[String, Object]	''	控制组件的 activeIconWrapStyle 行为。	按业务需要设置。
customClass	String	''	控制组件的 customClass 行为。	按业务需要设置。
customStyle	[String, Object]	''	控制组件的 customStyle 行为。	按业务需要设置。

数据项结构

字段	类型	默认值	说明
id/key	String | Number	index	稳定键；列表、轮播和瀑布流项目建议提供。
title/label/name	String	''	展示名称，具体读取字段见组件对应 prop。
disabled	Boolean	false	禁用可交互项目。

---

事件

事件名称	触发时机	回调参数	参数说明
input	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('input', ...) 为准。
update:value	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('update:value', ...) 为准。
update:modelValue	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('update:modelValue', ...) 为准。
change	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('change', ...) 为准。
click-item	对应交互或状态变化时触发。	payload	参数形状以源码 $emit('click-item', ...) 为准。

事件使用示例

<template>
  <xtf-tabbar @input="onEvent" />
</template>
<script>
export default {
  methods: {
    onEvent(payload) {
      console.log('收到事件', payload)
    }
  }
}
</script>

---

方法

无公开实例方法，通过 modelValue / value 控制当前项。

---

主题说明

• var(--xtf-color-primary) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-text-secondary) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-surface) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-text-tertiary) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-tabbar-gap) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-tabbar-padding) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-motion-base) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-motion-standard) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-color-border) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-motion-fast) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-motion-spring) 参与组件的颜色、背景、边框或动效呈现。
• var(--xtf-tabbar-direction) 参与组件的颜色、背景、边框或动效呈现。
• 视觉变体的可选值以 variant、theme、layout 等属性在源码中的分支为准。

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。