Subsection 分段器

17:06

说明

在多个选项中做单选，mode 决定两种形态：button（默认）在浅色底上放一个滑块按钮，切换时滑块在选项间平移；subsection 用边框分隔各选项，选中项整块填充 active-color 实心高亮。current 指定选中项（从 0 开始），切换时派发 change(index)。

兼容性

平台	支持情况
App	✅ 支持
H5	✅ 支持（监听窗口 resize，自动重算滑块宽度与位置）
微信小程序	✅ 支持

示例

按钮模式

默认 button 模式，滑块在按钮间滑动切换。

查看源码

<template>
    <ux-subsection :list="list" :current="current" @change="onChange"></ux-subsection>
</template>

<script setup lang="uts">
import type { SubsectionListItem } from '@/uni_modules/uview-pro-x';

const list: SubsectionListItem[] = [
    { name: 'Tab1' },
    { name: 'Tab2' },
    { name: 'Tab3' }
];

const current = ref<number>(0);

function onChange(index: number): void {
    current.value = index;
}
</script>

分段模式

mode=subsection 为分段模式，选项间有边框分隔。

查看源码

<template>
    <ux-subsection :list="list" :current="current" mode="subsection" @change="onChange"></ux-subsection>
</template>

<script setup lang="uts">
import type { SubsectionListItem } from '@/uni_modules/uview-pro-x';

const list: SubsectionListItem[] = [
    { name: 'Tab1' },
    { name: 'Tab2' },
    { name: 'Tab3' }
];

const current = ref<number>(0);

function onChange(index: number): void {
    current.value = index;
}
</script>

自定义颜色

通过 active-color 和 inactive-color 自定义激活与未激活颜色。

查看源码

<template>
    <ux-subsection :list="list" :current="current" active-color="#fa3534" inactive-color="#909399"></ux-subsection>
</template>

<script setup lang="uts">
import type { SubsectionListItem } from '@/uni_modules/uview-pro-x';

const list: SubsectionListItem[] = [
    { name: 'A' },
    { name: 'B' },
    { name: 'C' },
    { name: 'D' }
];

const current = ref<number>(1);
</script>

关闭动画

animation=false 关闭滑块滑动动画效果。

查看源码

<template>
    <ux-subsection :list="list" :current="current" :animation="false" @change="onChange"></ux-subsection>
</template>

<script setup lang="uts">
import type { SubsectionListItem } from '@/uni_modules/uview-pro-x';

const list: SubsectionListItem[] = [
    { name: 'Tab1' },
    { name: 'Tab2' },
    { name: 'Tab3' }
];

const current = ref<number>(0);

function onChange(index: number): void {
    current.value = index;
}
</script>

自定义样式

组合 font-size、height、bg-color、button-color 等属性自定义外观。

查看源码

<template>
    <ux-subsection :list="list" :current="current" :font-size="12" :height="30" bg-color="#ecf5ff" button-color="#2979ff" active-color="#ffffff" inactive-color="#2979ff"></ux-subsection>
</template>

<script setup lang="uts">
import type { SubsectionListItem } from '@/uni_modules/uview-pro-x';

const list: SubsectionListItem[] = [
    { name: 'Day' },
    { name: 'Week' },
    { name: 'Month' }
];

const current = ref<number>(0);
</script>

禁用状态

disabled=true 禁用整个分段器；单项 disabled:true 则该项不可点击。

查看源码

<template>
    <ux-subsection :list="list" disabled></ux-subsection>
    <view class="gap"></view>
    <ux-subsection :list="list2" active-color="#fa3534" inactive-color="#909399"></ux-subsection>
</template>

<script setup lang="uts">
import type { SubsectionListItem } from '@/uni_modules/uview-pro-x';

const list: SubsectionListItem[] = [
    { name: 'Tab1' },
    { name: 'Tab2' },
    { name: 'Tab3' }
];

const list2: SubsectionListItem[] = [
    { name: 'A' },
    { name: 'B', disabled: true },
    { name: 'C' }
];
</script>

<style scoped>
.gap {
    height: 10px;
}
</style>

API

Props

属性	说明	类型	默认值	版本
customStyle	自定义根节点样式	UTSJSONObject	-	-
customClass	自定义根节点样式类	string	''	-
list	选项列表，每项 name 为文本、可选 disabled 单独禁用	SubsectionListItem[]	-	-
current	当前选中项索引（从 0 开始）	number | string	0	-
activeColor	选中项颜色，默认取 $u.color.mainColor	string	''	-
inactiveColor	未选中项颜色，默认取 $u.color.contentColor	string	''	-
mode	显示模式：button-滑块按钮，subsection-分段	SubsectionMode	'button'	-
fontSize	选项文字大小，单位px	number | string	14	-
height	组件高度，单位px	number | string	35	-
animation	是否开启滑块滑动动画	boolean	true	-
bold	选中项文字是否加粗	boolean	true	-
bgColor	button 模式外层背景色，默认取 $u.color.dividerColor	string	''	-
buttonColor	button 模式滑块颜色，默认取 $u.color.bgWhite	string	''	-
vibrateShort	切换时是否触发轻微震动（首次切换不触发）	boolean	false	-
disabled	是否禁用整个分段器	boolean	false	-

Events

事件名	说明	回调参数	版本
change	选中项变化时触发，回调为选中项索引	index: number	-

Slots

ux-subsection 无插槽。

注意事项

1. current 是受控值，需配合 @change 回写；点击时会先比对内部索引，若目标项已是当前项则直接返回，不会重复派发 change。
2. 滑块宽度取自首个选项的实测宽度（getBoundingClientRectAsync）：H5 端监听窗口 resize 自动重算，App / 微信小程序仅在挂载及 list、mode 变化时重算，容器宽度在运行中变化（如横竖屏切换）后滑块可能错位。
3. bgColor / buttonColor 只在 button 模式生效；subsection 模式选中项文字固定为白色（$u.color.whiteColor），active-color 过浅会导致文字看不清。
4. 整体 disabled 或单项 disabled 时点击无效、不派发 change；单项禁用时文字透明度降到 0.4，整体禁用时容器透明度 0.6。
5. vibrateShort 开启后首次切换不震动（内部首触守卫），此后每次切换才触发。